jpmschweitzerandClaude Opus 4.5
583c407edd
Build and Push / build (release) Successful in 53s
- Convert booleans to strings for Redis hset (Redis doesn't accept bool) - Extract capability from delegate_to_X tool names for tracking - Use loop_scope="module" for pytest-asyncio module-scoped fixtures - Add note about using venv for tests in AGENTS.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
105 lines
4.7 KiB
Markdown
105 lines
4.7 KiB
Markdown
# LLM Agent Instructions
|
|
|
|
This document contains instructions and documentation references for AI assistants working with this codebase.
|
|
|
|
> **📖 Important**: Before working on this project, read [PHILOSOPHY.md](PHILOSOPHY.md) to understand the system vision, architectural patterns, and design goals. All development should work towards realizing those patterns.
|
|
# 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?
|
|
|
|
### 🧪 Local Development Setup
|
|
* **Always test locally first** before committing and deploying. The build-deploy loop is slow.
|
|
* **Start the local server** with `./wakeup.sh` - logs are written to `logs/server.log` for easy tailing
|
|
* **Auto-reload**: The wakeup script runs uvicorn in reload mode - code changes are picked up automatically without restart (except for requirements.txt changes)
|
|
* **Test REST endpoints** against `http://localhost:8777` using curl or similar tools
|
|
* **Only deploy** when a phase or feature is complete and tested locally
|
|
* **Environment**: Copy `.env.example` to `.env` and configure for your local setup (Ollama, Redis, Qdrant hosts)
|
|
* **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/core/ -v # Core tests only
|
|
```
|
|
|
|
### 🌐 Internal Service Access
|
|
* **git.schweitz.net**: Access via `http://localhost:3002` (direct Gitea) to bypass Authentik SSO
|
|
* Example: `curl http://localhost:3002/jpmschweitzer/library-desk/raw/branch/main/README.md`
|
|
* Public repos are readable without authentication
|
|
* Related repos: `library-desk`, `scheduler`, `core-api`, `portainer-core`
|
|
|
|
### 🐳 Deployment & Infrastructure
|
|
* **Full stack documentation**: Available in the `portainer-core` repo
|
|
* Access: `curl http://localhost:3002/jpmschweitzer/portainer-core/raw/branch/main/CONTAINERS.md`
|
|
* Contains: All service ports, URLs, Redis DB allocations, external domains
|
|
* **Tatlock deployment**:
|
|
* LAN: `http://192.168.86.149:8000`
|
|
* External: `tatlock.schweitz.net` (behind Authentik SSO)
|
|
* Redis DBs: 1 (memory), 6 (benchmarks)
|
|
* **Health check**: `curl http://192.168.86.149:8000/health`
|
|
|
|
### 🛡️ Git Discipline
|
|
* **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 tag
|
|
- Watchtower pulls and deploys to production
|
|
- Verify deployment: `curl http://192.168.86.149:8000/health`
|
|
|
|
---
|
|
|
|
## 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
|
|
src/
|
|
├── auth/
|
|
│ ├── router.py # Endpoints
|
|
│ ├── schemas.py # Pydantic models
|
|
│ ├── service.py # Business logic (CRUD, etc.)
|
|
│ ├── dependencies.py# Module-specific dependencies
|
|
│ └── config.py # Module-specific settings
|
|
├── posts/
|
|
│ ├── router.py
|
|
│ └── ...
|
|
└── main.py # App entry point |