refactor: reorganize into monorepo with separate subprojects
Structure webber into three independent subprojects: - webber-api/: FastAPI backend server with all agent code - webber-cli/: Standalone CLI client (renamed from cli/ to webber_cli/) - webber-sandbox/: Test project for functional testing Key changes: - Each subproject has its own .venv (Python 3.12+) - Added sandbox.sh for managing test project templates - Created sandbox-templates/ with calculator-cli and empty starter - Updated CI/CD for prefixed tags (api/v*, cli/v*) - Added comprehensive AGENTS.md with operational instructions - Added gitignore filtering to glob and grep tools - Created pyproject.toml for each subproject Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.5
@@ -1,128 +1,245 @@
|
||||
|
||||
# AGENTS.md
|
||||
# Webber Monorepo - Agent Instructions
|
||||
|
||||
> **Start every session by reading this file.**
|
||||
> This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.
|
||||
> This file contains everything you need to work with this codebase efficiently.
|
||||
|
||||
## 1. Agent Operational Protocols
|
||||
## Quick Reference
|
||||
|
||||
### 🧠 Work Patterns (Plan-Act-Reflect)
|
||||
* **Plan:** Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
|
||||
* **Act:** Execute the changes in small, atomic steps.
|
||||
* **Reflect:** After coding, verify your work. Did you break existing tests? Did you add new tests?
|
||||
|
||||
### 🛡️ Git Discipline
|
||||
* **ALWAYS add the relevant tests for the added code** Make sure to keep the test coverage up as we go, and run tests before commiting.
|
||||
* **NEVER commit to `main` or `master` directly.** Always create a feature branch: `feature/your-feature-name` or `fix/issue-description`.
|
||||
* **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
|
||||
* `feat: add user login endpoint`
|
||||
* `fix: resolve database connection timeout`
|
||||
* `refactor: split monolith dependency file`
|
||||
* **Atomic Commits:** Keep commits small. One logical change = one commit.
|
||||
|
||||
### 📝 Changelog Maintenance
|
||||
* **Update `CHANGELOG.md`** with every user-facing change.
|
||||
* Format: `## [Unreleased] - YYYY-MM-DD` followed by `### Added`, `### Changed`, or `### Fixed`.
|
||||
|
||||
### 🚀 Release Flow
|
||||
When changes are ready for deployment:
|
||||
|
||||
1. **Ask user if deploy cycle is desired **
|
||||
|
||||
2. **Update version** in `pyproject.toml`:
|
||||
- Bug fixes: bump patch version (1.8.3 → 1.8.4)
|
||||
- New features: bump minor version (1.8.4 → 1.9.0)
|
||||
|
||||
3. **Update CHANGELOG.md**:
|
||||
- Move items from `[Unreleased]` to new version section
|
||||
- Add release date: `## [1.8.4] - 2025-12-16`
|
||||
|
||||
4. **Commit and tag**:
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "fix: description of changes"
|
||||
git tag v1.8.4
|
||||
git push origin main --tags
|
||||
```
|
||||
|
||||
5. **CI/CD triggers automatically**:
|
||||
- Gitea CI builds Docker image on new version tag (starts with "v")
|
||||
- Watchtower pulls and deploys to production
|
||||
- Verify deployment: `curl http://192.168.86.149:8086/health`
|
||||
| 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` |
|
||||
|
||||
---
|
||||
|
||||
### 🧪 Local Development Setup
|
||||
## Repository Structure
|
||||
|
||||
* **Always test locally first** before committing and deploying. The build-deploy loop is slow.
|
||||
* **Only deploy** when a phase or feature is complete and tested locally
|
||||
* **Environment**: Copy `.env.example` to `.env` and configure for your local setup
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
#### ⚠️ CRITICAL: Starting the Local Server
|
||||
---
|
||||
|
||||
**ALWAYS use `./wakeup.sh` to start the local server. NEVER use raw uvicorn commands.**
|
||||
## Development Workflow
|
||||
|
||||
### 1. Start the API Server
|
||||
|
||||
```bash
|
||||
cd webber-api
|
||||
./wakeup.sh
|
||||
```
|
||||
|
||||
The wakeup script provides:
|
||||
- **Port conflict detection** - Warns if port 8086 is already in use
|
||||
- **Virtual environment activation** - Ensures correct Python environment
|
||||
- **Centralized logging** - All logs written to `logs/server.log` for easy tailing
|
||||
- **Auto-reload** - Code changes picked up automatically (except requirements.txt changes)
|
||||
- **Consistent configuration** - Same startup every time
|
||||
- **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
|
||||
|
||||
To monitor logs in another terminal:
|
||||
```bash
|
||||
tail -f logs/server.log
|
||||
# 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
|
||||
```
|
||||
|
||||
To stop the server: Press `Ctrl+C`
|
||||
### 3. Use the CLI
|
||||
|
||||
To kill a stuck server:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Check if port is in use
|
||||
lsof -i :8095
|
||||
|
||||
# Kill stuck process
|
||||
pkill -f "uvicorn src.main:app"
|
||||
# or
|
||||
kill $(lsof -t -i:8086)
|
||||
```
|
||||
|
||||
#### Testing
|
||||
|
||||
**Test REST endpoints** against `http://localhost:8086`:
|
||||
### CLI can't connect
|
||||
```bash
|
||||
curl http://localhost:8086/health
|
||||
curl http://localhost:8086/
|
||||
curl http://localhost:8086/docs # Swagger UI
|
||||
# Check API is running
|
||||
curl http://localhost:8095/health
|
||||
|
||||
# Check CLI config
|
||||
echo $WEBBER_API_URL # Should be http://localhost:8095
|
||||
```
|
||||
|
||||
**Running tests**: Always use the venv explicitly to avoid environment mismatches:
|
||||
### Ollama errors
|
||||
```bash
|
||||
.venv/bin/python -m pytest tests/ # All tests
|
||||
.venv/bin/python -m pytest tests/ -v # Verbose output
|
||||
.venv/bin/python -m pytest tests/ --cov # With coverage
|
||||
# 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
|
||||
```bash
|
||||
# Run with verbose output
|
||||
cd webber-api
|
||||
.venv/bin/python -m pytest tests/ -v --tb=short
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1.5 Known Issues & Future Improvements
|
||||
## Known Limitations
|
||||
|
||||
### Explore Agent
|
||||
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
|
||||
|
||||
- **Gitignore Support**: The filesystem tools (`glob_files`, `grep_content`) currently do NOT honor `.gitignore`. They return results from ignored directories like `.venv/`, `node_modules/`, etc. This should be fixed to filter out gitignored files by default.
|
||||
|
||||
- **Model Hallucination**: Mistral Nemo sometimes hallucinates file contents instead of using actual tool results. Consider using a more capable model (codestral, qwen2.5-coder) or adding response validation.
|
||||
|
||||
- **Ollama Provider**: We use a custom `WebberOllamaProvider` (ported from tatlock) that sanitizes `content: null` to `content: ""` for assistant messages with tool calls. This works around an Ollama API limitation.
|
||||
|
||||
---
|
||||
|
||||
## 2. FastAPI Architecture & Best Practices
|
||||
*Reference: [FastAPI Best Practices](https://github.com/zhanymkanov/fastapi-best-practices)*
|
||||
|
||||
### 📂 Project Structure (Directory-based, NOT File-type based)
|
||||
Do **not** group files by type (e.g., one huge `routers` folder). Group by **domain/module** inside a `src/` directory.
|
||||
|
||||
**Correct Structure:**
|
||||
```text
|
||||
to be determined
|
||||
See `webber-api/docs/COVERAGE.md` for full feature coverage status.
|
||||
|
||||
Reference in New Issue
Block a user