jpmschweitzerandClaude Opus 4.5
667e2ca8e4
- 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>
173 lines
4.1 KiB
Markdown
173 lines
4.1 KiB
Markdown
# 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
|