# 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