webber/AGENTS.md

Webber Monorepo - Agent Instructions

Start every session by reading this file. This file contains everything you need to work with this codebase efficiently.

Quick Reference

Action	Command
Start API server	cd webber-api && ./wakeup.sh
View API logs	tail -f webber-api/logs/server.log
Run API tests	cd webber-api && .venv/bin/python -m pytest tests/ -v
Check CLI status	cd webber-cli && .venv/bin/webber-cli status
Load sandbox	./sandbox.sh load calculator-cli
Explore sandbox	cd webber-cli && .venv/bin/webber-cli explore "query" -d ../webber-sandbox

---

Repository Structure

webber/
├── webber-api/          # FastAPI backend server
│   ├── src/             # API source code
│   ├── tests/           # API tests (pytest)
│   ├── docs/            # Architecture docs, COVERAGE.md
│   ├── logs/            # Runtime logs (server.log)
│   ├── .venv/           # API virtual environment
│   ├── wakeup.sh        # Dev server startup script
│   └── AGENTS.md        # API-specific development guide
│
├── webber-cli/          # CLI client
│   ├── webber_cli/      # Python package (underscore!)
│   ├── .venv/           # CLI virtual environment
│   └── README.md        # CLI usage guide
│
├── webber-sandbox/      # Active test project (contents swappable)
│   ├── src/             # Current project source
│   ├── tests/           # Current project tests
│   ├── .venv/           # Sandbox virtual environment
│   └── TASKS.md         # Tasks for Webber to complete
│
├── sandbox-templates/   # Template storage
│   ├── calculator-cli/  # Simple CLI with intentional bugs
│   └── empty/           # Blank starter project
│
├── sandbox.sh           # Sandbox management script
└── AGENTS.md            # THIS FILE

---

Development Workflow

1. Start the API Server

cd webber-api
./wakeup.sh

• Port: 8095 (dev), 8086 (production Docker)
• Logs: webber-api/logs/server.log
• Health check: curl http://localhost:8095/health
• API docs: http://localhost:8095/docs

To stop: Ctrl+C or pkill -f "uvicorn src.main:app"

2. Run Tests

# API tests (39 tests)
cd webber-api
.venv/bin/python -m pytest tests/ -v

# With coverage
.venv/bin/python -m pytest tests/ --cov=src

# Single test file
.venv/bin/python -m pytest tests/test_tools.py -v

3. Use the CLI

cd webber-cli

# Check API connection
.venv/bin/webber-cli status

# Explore a directory
.venv/bin/webber-cli explore "find all python files" -d ../webber-sandbox

# Interactive chat mode
.venv/bin/webber-cli chat -d ../webber-sandbox

Note: The API server must be running for CLI commands to work.

---

Sandbox Management

The sandbox is a swappable test project for functional testing.

Available Templates

Template	Description
calculator-cli	Python CLI with intentional bugs (div-by-zero, missing tests)
empty	Blank starter project

Commands

# List available templates
./sandbox.sh list

# Load a template (clears sandbox, preserves .venv)
./sandbox.sh load calculator-cli

# Reset to last loaded template
./sandbox.sh reset

# Save current sandbox as new template
./sandbox.sh save my-template

# Check current status
./sandbox.sh status

After Loading a Template

cd webber-sandbox
source .venv/bin/activate  # Create .venv first if missing
pip install -r requirements.txt

# Read the tasks
cat TASKS.md

# Run the project's tests
pytest tests/ -v

---

Testing Webber's Capabilities

Scenario: Find bugs in calculator-cli

# 1. Load the template
./sandbox.sh load calculator-cli

# 2. Have Webber explore it
cd webber-cli
.venv/bin/webber-cli explore "find all bugs in the code" -d ../webber-sandbox

# 3. Check TASKS.md for expected bugs
cat ../webber-sandbox/TASKS.md

Known bugs in calculator-cli:

• Division by zero not handled (operations.py:divide)
• Invalid operation causes KeyError (main.py:get_operation)
• Power function broken for fractional exponents
• Missing tests for divide and power functions

---

Key Files for Debugging

File	Purpose
webber-api/logs/server.log	API server logs
webber-api/src/domains/agents/explore/prompts.py	Explore agent system prompts
webber-api/src/domains/agents/explore/agent.py	Explore agent implementation
webber-api/src/ollama/provider.py	Ollama integration (sanitizes content:null)
webber-api/docs/COVERAGE.md	Feature coverage and known issues

---

Versioning & Releases

Uses prefixed tags:

• api/v0.3.0 → Triggers API Docker build
• cli/v0.1.0 → Triggers CLI build (future)

# API release
cd webber-api
# Update version in pyproject.toml
git add -A && git commit -m "chore: release api v0.3.0"
git tag api/v0.3.0
git push origin main --tags

---

Troubleshooting

API server won't start

# Check if port is in use
lsof -i :8095

# Kill stuck process
pkill -f "uvicorn src.main:app"

CLI can't connect

# Check API is running
curl http://localhost:8095/health

# Check CLI config
echo $WEBBER_API_URL  # Should be http://localhost:8095

Ollama errors

# Check Ollama is running
curl http://192.168.86.149:11434/api/tags

# Check model is available
curl http://192.168.86.149:11434/api/tags | grep mistral-nemo

Tests failing

# Run with verbose output
cd webber-api
.venv/bin/python -m pytest tests/ -v --tb=short

---

Known Limitations

1. Model hallucination - Mistral Nemo sometimes makes up file contents instead of using tool results
2. No conversation memory - CLI chat mode doesn't persist between sessions
3. No streaming - Responses appear all at once

See webber-api/docs/COVERAGE.md for full feature coverage status.