# System Architecture & Invariants: Python FastAPI & AI Agent Service Architecture

## 1. System Overview
Production standards for Python 3.12+, FastAPI, async I/O, Pydantic v2 schemas, LangChain/LlamaIndex integration, and defensive error propagation.
All AI agents operating within this repository must adhere strictly to these architectural boundaries.

### Technology Stack
- **Framework**: FastAPI
- **Language Standard**: Python 3.12+
- **UI & Styling**: None / API Service
- **Data Persistence**: PostgreSQL / pgvector / Redis
- **Engineering Philosophy**: strict

## 2. Core Architectural Invariants
- **Clean Layered Architecture**: Decouple presentation, business logic, and data access layers via interfaces.
- **Guard Clauses & Early Returns**: Exit early from functions to eliminate deeply nested if-else pyramids.
- **Explicit Result / Tuple Returns**: Return [error, result] or Result<T, E> types for operations that can fail.
- **Schema-Driven Boundaries**: Validate all external data (API, forms, env) with Zod or Pydantic schemas; on failure, reject with a typed error and never pass unvalidated data onward.

## 3. Data Flow & State Management Principles
1. **Unidirectional Data Flow**: State flows top-down; mutations flow through explicit, typed handlers.
2. **Boundary Validation**: External inputs (API payloads, query parameters, environment variables) must be parsed with strict schemas before reaching domain logic.
3. **Surgical Precision**: Diffs must remain minimal and scoped exclusively to the objective. Do not reformat unrelated code.

## 4. Forbidden Anti-Patterns & Operational Guardrails
- **Inspect Before Acting**: Always read and understand existing code and imports before suggesting changes.
- **Minimal Surgical Diffs**: Touch only lines relevant to prompt. Preserve existing comments and formatting.
- **Concise & Direct Tone**: Skip conversational pleasantries. Deliver focused diffs and a short rationale.
- **Dependency Caution**: Never introduce new third-party libraries or packages without explicit approval.
- **Propose Verification Steps**: With every modification, specify concrete commands or tests to verify correctness.

## 5. Domain-Specific Invariants
- Never hardcode OpenAI/Anthropic API keys or secrets in source code.
- Always implement streaming responses for LLM text generation endpoints.
- Type annotate all function arguments and return types.

## 6. Implementation Reference Patterns

### Preferred Pattern
```python
# Good: Typed Pydantic v2 request with dependency injection
from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import BaseModel, Field

router = APIRouter()

class PromptRequest(BaseModel):
    query: str = Field(..., min_length=3, max_length=1000)
    temperature: float = Field(0.7, ge=0.0, le=1.0)

@router.post("/v1/generate", response_model=GenerationResponse)
async def generate(req: PromptRequest, svc: AIService = Depends(get_ai_service)):
    result = await svc.process_prompt(req.query, req.temperature)
    if not result.is_ok:
        raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=result.error_msg)
    return result.payload
```

### Forbidden Anti-Pattern
```python
# Discouraged: Untyped dict params and missing error handling
@app.post("/generate")
def generate(data: dict):
    result = client.chat(data["query"])
    return result
```

## 7. Verification Protocol
Before finalizing any implementation:
1. Define all request and response schemas strictly using Pydantic v2 BaseModels with Field validation.
2. Use asynchronous route handlers (async def) for any network I/O, LLM inference calls, or database operations.
3. Manage database sessions and external clients using FastAPI Depends injection.
4. Structure the repository into: api/ (routes), services/ (business logic), core/ (config), models/ (schemas).
5. Catch domain-specific exceptions at the service layer and translate to HTTPException at the route layer.