Andrew Ridgway
c8f3600b32
- Add Matrix bot to the feature list and prerequisites. - Add a Matrix Appservice section covering config, Synapse registration, and the shared conversation pipeline. - Document the matrix config section in CONFIGURATION.md. - Add a ready-to-use Synapse appservice registration template (matrix/steward_appservice.yaml). - Document the Gitea Actions build/deploy workflow and kube manifests. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
# 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.
|