webber/README.md

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 for structured LLM interactions.

Quick Start

Prerequisites

• Python 3.12+
• Ollama with models installed
• (Optional) Tatlock for multi-tenant authentication

Installation

# 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

# Copy example config
cp .env.example .env

# Edit .env with your settings
# At minimum, configure OLLAMA_URL to point to your Ollama instance

Running

# 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 for full configuration options.

Development

Code Quality

# 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

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=src --cov-report=html

Security Audit

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

# 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