tatlock/AGENTS.md

LLM Agent Instructions

This document contains instructions and documentation references for AI assistants working with this codebase.

📖 Important: Before working on this project, read docs/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 make run - logs are written to build/logs/server.log for easy tailing
• Auto-reload: make run runs uvicorn in reload mode - code changes are picked up automatically without restart (except for dependency 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:

  .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 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:

   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

📂 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:

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