chore: add ruff linter, fix mypy errors, and write README

- Add ruff linter configuration to pyproject.toml with modern Python 3.12 rules - Add ruff~=0.9.4 to dev dependencies - Fix all mypy type errors (Optional[] hints, Token types, Any returns) - Auto-fix 54 ruff issues (import sorting, Optional -> X | None syntax) - Create ProjectMeta dataclass for single source of truth from pyproject.toml - Write comprehensive README.md with setup, config, and development docs - Update main.py to use settings.app_description from pyproject.toml Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 22:58:24 +01:00
parent 34b68621c6
commit 667e2ca8e4
13 changed files with 289 additions and 65 deletions
@@ -0,0 +1,172 @@
+# Webber
+
+Multi-Agent AI Development System - a FastAPI-based service that orchestrates local LLM agents for code exploration, planning, and task execution.
+
+## Overview
+
+Webber provides autonomous AI agents similar to Claude Code but running locally with configurable models via Ollama. It's designed for:
+
+- **Explore Agent** - Fast codebase navigation and code search
+- **Plan Agent** - Implementation design and step-by-step planning
+- **Task Agent** - Autonomous multi-step code generation and modification
+
+Built on [PydanticAI](https://ai.pydantic.dev/) for structured LLM interactions.
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- [Ollama](https://ollama.ai/) with models installed
+- (Optional) Tatlock for multi-tenant authentication
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://git.schweitz.internal/jpmschweitzer/webber.git
+cd webber
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# For development (includes testing and linting tools)
+pip install -r requirements-dev.txt
+```
+
+### Configuration
+
+```bash
+# Copy example config
+cp .env.example .env
+
+# Edit .env with your settings
+# At minimum, configure OLLAMA_URL to point to your Ollama instance
+```
+
+### Running
+
+```bash
+# Development (with auto-reload)
+./wakeup.sh
+
+# Or manually
+uvicorn src.main:app --host 0.0.0.0 --port 8086 --reload
+```
+
+The service will be available at `http://localhost:8086`. API docs at `/docs`.
+
+## Configuration
+
+All settings via environment variables or `.env` file:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEBUG` | `false` | Enable debug mode |
+| `LOG_LEVEL` | `INFO` | Logging level |
+| `PORT` | `8086` | Server port |
+| `OLLAMA_URL` | `http://192.168.86.149:11434` | Ollama API URL |
+| `OLLAMA_AGENT_MODEL` | `mistral-nemo-large:latest` | Model for agent reasoning |
+| `OLLAMA_EMBED_MODEL` | `nomic-embed-text:latest` | Model for embeddings |
+| `TOOL_TIMEOUT_SECONDS` | `120` | Tool execution timeout |
+| `SANDBOX_ENABLED` | `true` | Sandbox tool execution |
+| `ALLOWED_PATHS` | `[]` | Paths accessible to tools |
+
+See [.env.example](.env.example) for full configuration options.
+
+## Development
+
+### Code Quality
+
+```bash
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/ tests/
+
+# Auto-fix lint issues
+ruff check src/ tests/ --fix
+
+# Format code
+ruff format src/ tests/
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# With coverage
+pytest tests/ --cov=src --cov-report=html
+```
+
+### Security Audit
+
+```bash
+# Check dependencies for CVEs
+pip-audit
+```
+
+## Architecture
+
+Webber uses a domain-based architecture with clean separation of concerns:
+
+```
+src/
+├── main.py              # FastAPI app entry point
+├── shared/              # Cross-cutting infrastructure
+│   ├── base.py          # BaseController, BaseSchema
+│   ├── config.py        # Settings from pyproject.toml + env
+│   ├── logging.py       # @logged decorator with timing
+│   └── exceptions.py    # Exception hierarchy
+└── domains/             # Feature domains
+    ├── health/          # Health check endpoints
+    ├── agents/          # Agent orchestration
+    └── tools/           # Tool execution (file, shell, search)
+```
+
+See [docs/architecture.md](docs/architecture.md) for detailed patterns and conventions.
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Service information |
+| `/health` | GET | Health check for monitoring |
+| `/docs` | GET | Interactive API documentation |
+
+## Docker
+
+```bash
+# Build
+docker build -t webber .
+
+# Run
+docker run -p 8086:8086 --env-file .env webber
+```
+
+The container includes a healthcheck that pings `/health` every 30 seconds.
+
+## Deployment
+
+Deployed via Gitea Actions CI/CD:
+
+1. Tag a release (`git tag v0.x.x && git push --tags`)
+2. Workflow builds and pushes Docker image
+3. Watchtower auto-deploys to production
+
+Production runs in Portainer `agents` stack on the `docker-dataplane` network.
+
+## Status
+
+**Alpha** - Core infrastructure is complete. Agent and tool implementations are in progress.
+
+## License
+
+MIT