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.

Gitea Actions Pipeline Variables

The workflow reads the following from the gitea repository's Settings → Actions → Secrets and Variables:

Secrets (sensitive):

Secret	Purpose
KUBEC_CONFIG_BUILDX_NEW	Kubeconfig for the buildx k8s driver + deploy step
REG_PASSWORD	Password for the gitea container registry login
DOCKER_PASSWORD	Password for the regcred docker-registry secret
TELEGRAM_BOT_TOKEN	Steward's Telegram bot token
OPENAI_API_KEY	LLM API key (or ollama placeholder for Ollama Cloud)
MATRIX_AS_TOKEN	Matrix appservice token (authenticates to homeserver)
MATRIX_HS_TOKEN	Matrix homeserver token (authenticates incoming transactions)

Variables (non-sensitive):

Variable	Purpose
DOCKER_SERVER	Registry host, e.g. git.aridgwayweb.com
DOCKER_USERNAME	Registry username, e.g. armistace
DOCKER_EMAIL	Registry email
TELEGRAM_ALLOWED_USER_IDS	Comma-separated Telegram user IDs
OPENAI_BASE_URL	LLM base URL (e.g. https://ollama.com/v1 for Ollama Cloud)
OPENAI_MODEL	LLM model name
MATRIX_HOMESERVER_URL	Homeserver client-server base URL, e.g. http://matrix:8008
MATRIX_HOMESERVER_DOMAIN	Homeserver server_name, e.g. matrix.aridgwayweb.com
MATRIX_BOT_LOCALPART	Bot localpart (default steward)
MATRIX_ALLOWED_ROOM_IDS	Comma-separated room allow-list (empty = all)
MATRIX_ALLOWED_USER_IDS	Comma-separated user MXID allow-list (empty = all)

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

License

See LICENSE file for details.