# 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](https://t.me/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:
```bash
git clone https://github.com/djw4/steward.git
cd steward
```

2. Copy `.env.example` to `.env` and fill in your values:
```bash
cp .env.example .env
# Edit .env with your tokens and IDs
```

3. Create the data directory:
```bash
mkdir -p data
```

4. Start with Docker Compose:
```bash
docker compose -f docker-compose.dev.yml up --build
```

### Configuration

See [CONFIGURATION.md](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`](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

```bash
# 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:

```bash
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](AGENTS.md) for AI agent guidelines
- Read [CONFIGURATION.md](CONFIGURATION.md) for config management
- Check [.github/workflows/ci.yml](.github/workflows/ci.yml) for CI/CD pipeline

## Deployment

For Kubernetes deployment, see examples in [CONFIGURATION.md](CONFIGURATION.md#kubernetes).

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/`](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.