jpmschweitzerandClaude Opus 4.5
f4e8552298
Implements the first Claude-like agent for codebase exploration: Core Features: - Explore agent with glob, grep, read, and bash tools - Native PydanticAI tool calling with Ollama/Mistral Nemo - Sanitized Ollama provider (fixes content:null issue) - REST API endpoints for agent execution Tool Infrastructure: - BaseTool abstract class with ToolResult dataclass - ReadFileTool, GlobFilesTool, GrepContentTool, BashReadOnlyTool - Path validation and sandboxing support CLI Client (separate package for future extraction): - webber-cli command with chat, explore, status commands - Communicates with Webber API backend - Rich console output with theming Configuration: - Dev server on port 8095 (production uses 8086) - Mistral Nemo optimizations (temp 0.3, tool_choice required) Tests: 24 tests covering tools and API endpoints Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
128 lines
4.7 KiB
Markdown
128 lines
4.7 KiB
Markdown
|
|
# AGENTS.md
|
|
|
|
> **Start every session by reading this file.**
|
|
> This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.
|
|
|
|
## 1. Agent Operational Protocols
|
|
|
|
### 🧠 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`
|
|
|
|
---
|
|
|
|
### 🧪 Local Development Setup
|
|
|
|
* **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
|
|
|
|
#### ⚠️ CRITICAL: Starting the Local Server
|
|
|
|
**ALWAYS use `./wakeup.sh` to start the local server. NEVER use raw uvicorn commands.**
|
|
|
|
```bash
|
|
./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
|
|
|
|
To monitor logs in another terminal:
|
|
```bash
|
|
tail -f logs/server.log
|
|
```
|
|
|
|
To stop the server: Press `Ctrl+C`
|
|
|
|
To kill a stuck server:
|
|
```bash
|
|
pkill -f "uvicorn src.main:app"
|
|
# or
|
|
kill $(lsof -t -i:8086)
|
|
```
|
|
|
|
#### Testing
|
|
|
|
**Test REST endpoints** against `http://localhost:8086`:
|
|
```bash
|
|
curl http://localhost:8086/health
|
|
curl http://localhost:8086/
|
|
curl http://localhost:8086/docs # Swagger UI
|
|
```
|
|
|
|
**Running tests**: Always use the venv explicitly to avoid environment mismatches:
|
|
```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
|
|
```
|
|
|
|
---
|
|
|
|
## 1.5 Known Issues & Future Improvements
|
|
|
|
### Explore Agent
|
|
|
|
- **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 |