steward_mirror/README.md

Steward

Steward is a long-running, AI-assisted personal operations platform designed to reduce cognitive load by acting as a persistent, trustworthy steward of both digital infrastructure and delegated personal objectives.

Features

• Telegram Bot: Group/channel support with thread-based conversations
• Matrix Bot: Native Matrix application-service (appservice) integration via Synapse
• Message Threads: Organized conversations with automatic summarization
• Knowledge Base: Stores and retrieves conversation summaries
• LLM Integration: OpenAI-compatible API support
• Tool Calling: Optional MCP/OpenAPI tool server integration
• Flexible Configuration: YAML + environment variables (Kubernetes-ready)

Quick Start

Prerequisites

• Python 3.12+
• Docker & Docker Compose
• Telegram Bot Token (from @BotFather) — required for the Telegram bot
• OpenAI API Key
• A Matrix homeserver (e.g. Synapse) — required for the Matrix appservice bot

Local Development

1. Clone the repository:

git clone https://github.com/djw4/steward.git
cd steward

2. Copy .env.example to .env and fill in your values:

cp .env.example .env
# Edit .env with your tokens and IDs

3. Create the data directory:

mkdir -p data

4. Start with Docker Compose:

docker compose -f docker-compose.dev.yml up --build

Configuration

See CONFIGURATION.md for detailed configuration options.

Matrix Appservice

Steward can run as a native Matrix bot by registering it as a Synapse application service. When configured, it receives room events via HTTP transactions and replies through the client-server API, reusing the same conversation pipeline as the Telegram bot.

To enable it:

1. Configure the matrix section (via STEWARD__MATRIX__* env vars or a config file):

   • homeserver_url — the homeserver client-server base URL (e.g. http://matrix:8008)
   • homeserver_domain — the server name (e.g. matrix.aridgwayweb.com)
   • as_token / hs_token — the appservice tokens
   • bot_localpart — the bot user localpart (defaults to steward)
   • listen_host / listen_port — where the appservice HTTP server listens
   • allowed_room_ids / allowed_user_ids — optional allow-lists

2. Register the appservice with Synapse. See matrix/steward_appservice.yaml for a ready-to-use registration template, and add it to your homeserver.yaml under app_service_config_files:.

3. Start Steward. It will run the Telegram bot, the Matrix appservice, or both depending on which are configured.

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=steward

Pre-commit Hooks

Set up pre-commit hooks to run linting and tests automatically:

pip install pre-commit
pre-commit install

This will run:

• ruff check for code style
• pytest for tests

On every commit. You can skip with git commit --no-verify if needed.

Development

• Read AGENTS.md for AI agent guidelines
• Read CONFIGURATION.md for config management
• Check .github/workflows/ci.yml for CI/CD pipeline

Deployment

For Kubernetes deployment, see examples in CONFIGURATION.md.

The repo includes a Gitea Actions workflow (.gitea/workflows/build_push.yml) that builds a multi-arch Docker image, pushes it to the gitea registry, and deploys to Kubernetes using the manifests in kube/. The deployment uses a NodePort service exposing port 30002 (the Matrix appservice endpoint) and a persistent volume for thread memory.

Production image: ghcr.io/djw4/steward:latest

License

See LICENSE file for details.