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

### 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.