# 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](https://t.me/botfather))
- OpenAI API Key

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

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

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

## License

See LICENSE file for details.