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
• 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)
• OpenAI API Key

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.

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.

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

License

See LICENSE file for details.