### Install Cookiecutter

Source: https://github.com/neural-maze/agent-api-cookiecutter/blob/main/README.md

Installs the Cookiecutter tool, a command-line utility that creates projects from templates. This is a prerequisite for using the Agent API Cookiecutter.

```bash
pip install -U cookiecutter
```

--------------------------------

### Start FastAPI Server and Send Chat Request

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Demonstrates how to start the generated FastAPI agent API server using Docker Compose and send a POST request to the chat endpoint. Includes example `curl` commands for starting the server and sending a JSON payload with a message and session ID.

```bash
# Start the API server
cd my-agent-api
docker compose up --build -d

# Send chat request
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hello, what can you help me with?", "session_id": "user-123" }'

# Response
# {"message": "Chat request received"}

# Template provides stub in infrastructure/api/main.py:31
# Implement chat_service in application/chat_service/ to add logic
```

--------------------------------

### Install and Use Cookiecutter for Project Generation

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Installs the Cookiecutter tool and demonstrates how to generate a new AI agent API project from the provided GitHub template. It lists the interactive prompts users will encounter during project creation and shows an example of the generated directory structure.

```bash
# Install cookiecutter
pip install -U cookiecutter

# Create new project from template
cookiecutter https://github.com/neural-maze/agent-api-cookiecutter.git

# Interactive prompts will ask for:
# - full_name: Your name (default: Miguel Otero Pedrido)
# - package_name: Package name (default: agent-api)
# - project_name: Display name (default: Agent API)
# - project_slug: Python module name (auto-generated: agent_api)
# - project_short_description: Brief description
# - first_version: Initial version (default: 0.1.0)

# Example output:
# agent-api/
# ├── Dockerfile
# ├── docker-compose.yaml
# ├── Makefile
# ├── pyproject.toml
# │├── src/agent_api/
```

--------------------------------

### Dockerfile with Multi-Stage Build using UV

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

An optimized Dockerfile that utilizes multi-stage builds and the uv package manager for faster dependency installation. It sets up a Python 3.12 environment, installs project dependencies, copies application code, and runs the FastAPI server.

```dockerfile
FROM python:3.12-slim

# Install uv package manager
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

# Install dependencies (cached layer)
COPY uv.lock pyproject.toml README.md ./
RUN uv sync --frozen --no-cache

# Copy application code
COPY src/agent_api agent_api/

# Run FastAPI server
CMD ["/app/.venv/bin/fastapi", "run", "agent_api/infrastructure/api/main.py", "--port", "8000", "--host", "0.0.0.0"]

# Build: docker build -t my-agent-api .
# Run: docker run -p 8000:8000 my-agent-api
```

--------------------------------

### Docker Compose Commands for Agent API

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Provides Make commands for building, starting, and stopping the agent API services using Docker Compose. It also lists equivalent direct Docker commands for managing the containers and viewing logs.

```bash
# Build Docker image
make build-project
# Equivalent to: docker compose build

# Start services in detached mode
make start-project
# Equivalent to: docker compose up --build -d

# Stop running services
make stop-project
# Equivalent to: docker compose stop

# Direct Docker commands also available
docker compose up --build -d
docker compose logs -f agent-api
docker compose down
```

--------------------------------

### GitHub Actions CI Workflow for Testing

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Defines a GitHub Actions workflow (.github/workflows/test.yml) for automating testing and linting on pull requests. It uses uv for Python environment management, installs dependencies, and runs linter and tests.

```yaml
name: Test

on:
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --all-extras --dev

      - name: Run linter
        run: uv run ruff check

      - name: Run tests
        run: uv run pytest

# Automatically runs on every PR to main branch
# Ensures code quality and test coverage
```

--------------------------------

### Send Document Ingestion Request to FastAPI Endpoint

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Provides an example `curl` command to send a POST request to the agent API for ingesting documents. This endpoint is intended to add data to the agent's knowledge base, with the example showing document content and source metadata.

```bash
# Ingest documents endpoint (note: currently duplicate route at /eval)
curl -X POST http://localhost:8000/eval \
  -H "Content-Type: application/json" \
  -d '{ "documents": [{"id": "doc1", "content": "Document text", "metadata": {"source": "manual"}}], "index_name": "knowledge_base" }'

# Response
# {"message": "Ingest documents request received"}

# Template stub at infrastructure/api/main.py:47
# Implement in application/ingest_documents_service/
```

--------------------------------

### Send Memory Reset Request to FastAPI Endpoint

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Illustrates how to reset an agent's memory or conversation history using a POST request to the `/reset-memory` endpoint. The example shows a `curl` command with a session ID and the type of reset requested.

```bash
# Reset agent memory
curl -X POST http://localhost:8000/reset-memory \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "user-123", "reset_type": "full" }'

# Response
# {"message": "Reset memory request received"}

# Template stub at infrastructure/api/main.py:55
# Implement in application/reset_memory_service/
```

--------------------------------

### Docker Build and Deployment

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Instructions for building and deploying the Agent API using Docker Compose.

```APIDOC
## Docker Build and Deployment

Build and deploy the agent API using Docker Compose.

### Build Docker image
```bash
make build-project
# Equivalent to: docker compose build
```

### Start services
```bash
make start-project
# Equivalent to: docker compose up --build -d
```

### Stop running services
```bash
make stop-project
# Equivalent to: docker compose stop
```

### Direct Docker commands
```bash
docker compose up --build -d
docker compose logs -f agent-api
docker compose down
```
```

--------------------------------

### Docker Multi-Stage Build

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

An optimized Dockerfile using UV for fast builds and efficient image size.

```APIDOC
## Docker Multi-Stage Build

Optimized Dockerfile using UV package manager for fast builds.

### Dockerfile
```dockerfile
FROM python:3.12-slim

# Install uv package manager
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

# Install dependencies (cached layer)
COPY uv.lock pyproject.toml README.md ./
RUN uv sync --frozen --no-cache

# Copy application code
COPY src/agent_api agent_api/

# Run FastAPI server
CMD ["/app/.venv/bin/fastapi", "run", "agent_api/infrastructure/api/main.py", "--port", "8000", "--host", "0.0.0.0"]
```

### Build and Run

**Build:**
```bash
docker build -t my-agent-api .
```

**Run:**
```bash
docker run -p 8000:8000 my-agent-api
```
```

--------------------------------

### Package Configuration

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Details the pyproject.toml file, which configures project dependencies and build tools.

```APIDOC
## Package Configuration

PyProject.toml configuration with dependencies and tooling.

### File
`pyproject.toml`

### Configuration Example (Conceptual)
```toml
[tool.poetry]
name = "agent-api"
version = "0.1.0"
description = "AI Agent API Template"
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.111.0"
pydantic = "^2.7.0"
pydantic-settings = "^2.3.0"

[tool.uv]
freeze = "uv.lock"

[tool.ruff]
line-length = 88

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
```

**Note:** This is a conceptual example. Refer to the actual `pyproject.toml` for precise configurations.
```

--------------------------------

### Project Structure Overview (Clean Architecture)

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Illustrates the project's adherence to Clean Architecture principles, detailing the responsibilities of the Domain, Application, and Infrastructure layers. Provides guidance on where to implement specific functionalities.

```python
# Domain Layer (src/agent_api/domain/)
# - Business logic, entities, exceptions
# - Tools, prompts, memory interfaces
# - No external dependencies

# Application Layer (src/agent_api/application/)
# - Use cases and services
# - chat_service/, evaluation_service/
# - ingest_documents_service/, reset_memory_service/
# - Orchestrates domain objects

# Infrastructure Layer (src/agent_api/infrastructure/)
# - External integrations
# - api/ (FastAPI endpoints)
# - db/ (database adapters)
# - llm_providers/ (OpenAI, Anthropic clients)
# - mcp_clients/ (MCP protocol clients)
# - monitoring/ (logging, metrics)

# Example: Implementing chat service
# 1. Define domain entities in domain/
# 2. Create use case in application/chat_service/
# 3. Expose via infrastructure/api/main.py
```

--------------------------------

### Configuration Settings

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Defines the application settings using Pydantic BaseSettings, including API keys and database URLs.

```APIDOC
## Configuration Settings

This section details the configuration of the Agent API using Pydantic BaseSettings.

### File
`src/agent_api/config.py`

### Settings Class
```python
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        extra="ignore",
        env_file_encoding="utf-8"
    )

    openai_api_key: str = ""
    db_url: str = "postgresql://localhost/agentdb"
    redis_url: str = "redis://localhost:6379"

settings = Settings()
```

### Usage
```python
from agent_api.config import settings

api_key = settings.openai_api_key
```
```

--------------------------------

### Project Structure Overview

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Provides an overview of the Agent API project structure following Clean Architecture principles.

```APIDOC
## Project Structure Overview

The generated project follows Clean Architecture with clear separation of layers.

### Layers

- **Domain Layer** (`src/agent_api/domain/`)
  - Business logic, entities, exceptions.
  - Tools, prompts, memory interfaces.
  - No external dependencies.

- **Application Layer** (`src/agent_api/application/`)
  - Use cases and services (e.g., `chat_service/`, `evaluation_service/`).
  - Orchestrates domain objects.

- **Infrastructure Layer** (`src/agent_api/infrastructure/`)
  - External integrations (FastAPI endpoints, database adapters, LLM clients, etc.).
  - `api/` (FastAPI endpoints)
  - `db/` (database adapters)
  - `llm_providers/` (OpenAI, Anthropic clients)
  - `monitoring/` (logging, metrics)

### Example Implementation Flow

1.  Define domain entities in `domain/`.
2.  Create use cases in `application/` (e.g., `application/chat_service/`)
3.  Expose functionality via API endpoints in `infrastructure/api/`.
```

--------------------------------

### PyProject.toml for Package Configuration

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Contains the project's build system and dependency information using the pyproject.toml standard. It specifies build backend, project metadata, and lists tool configurations for linters, formatters, and test runners like Ruff and pytest.

```toml
[build-system]
requires = ["poetry-core"] # or "setuptools", "flit"
build-backend = "poetry.core.masonry.api"

[project]
name = "agent-api"
version = "0.1.0"
description = "AI Agent API Template"
authors = [
    { name="Your Name", email="your.email@example.com" },
]
license = "MIT"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "fastapi>=0.111.0",
    "uvicorn[standard]>=0.27.0",
    "pydantic-settings>=2.2.1",
    "sqlalchemy>=2.0.23",
    "asyncpg>=0.29.0",
    "redis>=4.6.0",
    "langchain>=0.1.0",
    "openai>=1.0.0",
    "tiktoken>=0.6.0",
    "python-dotenv>=1.0.0",
    "python-multipart>=0.0.9",
    "python-json-logger>=2.0.7",
    "beautifulsoup4>=4.12.2",
    "sentence-transformers>=2.2.2",
    "trimesh>=3.23.4",
    "scipy>=1.11.4",
    "numpy>=1.26.2",
    "tqdm>=4.66.1",
    "tiktoken>=0.6.0",
    "python-dotenv>=1.0.0",
    "python-multipart>=0.0.9",
    "python-json-logger>=2.0.7",
    "beautifulsoup4>=4.12.2",
    "sentence-transformers>=2.2.2",
    "trimesh>=3.23.4",
    "scipy>=1.11.4",
    "numpy>=1.26.2",
    "tqdm>=4.66.1",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.3",
    "ruff>=0.2.0",
    "black>=23.12.0",
    "mypy>=1.8.0",
    "pre-commit>=3.5.0",
    "isort>=5.13.2",
    "pytest-asyncio>=0.21.1",
]

[tool.ruff]
line-length = 100
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".hg",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".trans",
    "__pypackages__",
    
```

--------------------------------

### API Lifespan Management

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Demonstrates the use of FastAPI's lifespan context manager for handling startup and shutdown events.

```APIDOC
## API Lifespan Management

FastAPI lifespan context manager for startup and shutdown operations.

### File
`infrastructure/api/main.py`

### Lifespan Context Manager
```python
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Handles startup and shutdown events for the API."""
    # Startup: Initialize connections, load models
    print("Starting up...")
    db_connection = await connect_to_database() # Placeholder for actual connection logic

    yield  # Application runs here

    # Shutdown: Cleanup resources
    print("Shutting down...")
    await db_connection.close()

app = FastAPI(
    title="Agent API",
    description="AI Agent API Template",
    docs_url="/docs",
    lifespan=lifespan
)
```
```

--------------------------------

### Configure Pydantic Settings

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Defines application settings using Pydantic's BaseSettings. It loads configuration from a .env file and sets default values for database and Redis URLs. The settings object is then instantiated for use throughout the application.

```python
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        extra="ignore",
        env_file_encoding="utf-8"
    )

    # Add your settings here
    openai_api_key: str = ""
    db_url: str = "postgresql://localhost/agentdb"
    redis_url: str = "redis://localhost:6379"

settings = Settings()

# Usage in your code
from agent_api.config import settings

api_key = settings.openai_api_key
```

--------------------------------

### Python Project Configuration (pyproject.toml)

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Defines project metadata, dependencies, and development tools for a Python project using pyproject.toml. It specifies core libraries for building an AI agent API and development tools for testing and code quality.

```toml
[project]
name = "agent-api"
version = "0.1.0"
description = "AI Agent API Template"
requires-python = ">= 3.10"

dependencies = [
  "typer",           # CLI framework
  "fastapi[standard]", # Web framework
  "loguru",          # Logging
  "pydantic",        # Data validation
  "pydantic-settings", # Config management
  "ipykernel"        # Jupyter support
]

[dependency-groups]
dev = [
  "coverage",  # Test coverage
  "pre-commit", # Git hooks
  "pytest",    # Testing framework
  "ruff"       # Linting/formatting
]

[tool.ruff]
line-length = 120

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "UP"]

```

--------------------------------

### Generate New Agent API Project

Source: https://github.com/neural-maze/agent-api-cookiecutter/blob/main/README.md

Uses Cookiecutter to generate a new AI agent project from the specified GitHub repository. After running this command, the user will be prompted to provide project-specific details.

```bash
cookiecutter https://github.com/neural-maze/agent-api-cookiecutter.git
```

--------------------------------

### FastAPI Lifespan Context Manager

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Implements a lifespan context manager for FastAPI applications to handle startup and shutdown events. It demonstrates connecting to a database on startup and closing the connection on shutdown, ensuring proper resource management.

```python
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Handles startup and shutdown events for the API."""
    # Startup: Initialize connections, load models
    print("Starting up...")
    db_connection = await connect_to_database()

    yield  # Application runs here

    # Shutdown: Cleanup resources
    print("Shutting down...")
    await db_connection.close()

app = FastAPI(
    title="Agent API",
    description="AI Agent API Template",
    docs_url="/docs",
    lifespan=lifespan
)
```

--------------------------------

### GitHub Actions CI Workflow

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Details the GitHub Actions workflow for automated testing and linting on pull requests.

```APIDOC
## GitHub Actions CI Workflow

Automated testing and linting pipeline for pull requests.

### File
`.github/workflows/test.yml`

### Workflow Definition
```yaml
name: Test

on:
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v5

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --all-extras --dev

      - name: Run linter
        run: uv run ruff check

      - name: Run tests
        run: uv run pytest
```

### Triggers
Automatically runs on every Pull Request to the `main` branch.
```

--------------------------------

### Send Evaluation Request to FastAPI Endpoint

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Shows how to send a POST request to the agent API's evaluation endpoint using `curl`. The request includes a conversation ID and a list of metrics to evaluate, demonstrating how performance metrics can be submitted.

```bash
# Send evaluation request
curl -X POST http://localhost:8000/eval \
  -H "Content-Type: application/json" \
  -d '{ "conversation_id": "conv-456", "metrics": ["accuracy", "latency", "relevance"] }'

# Response
# {"message": "Eval request received"}

# Template provides stub in infrastructure/api/main.py:39
# Implement evaluation_service in application/evaluation_service/
```

--------------------------------

### Post-Generation Success Message Hook

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

A simple Python script executed after the Cookiecutter project generation is complete. It prints a confirmation message to the console, indicating successful project creation.

```python
# hooks/post_gen_project.py runs after generation
#!/usr/bin/env python

if __name__ == "__main__":
    print("Your Agent API project has been created successfully!")

# Output appears after cookiecutter completes:
# $ cookiecutter https://github.com/neural-maze/agent-api-cookiecutter.git
# ...prompts...
# Your Agent API project has been created successfully!
```

--------------------------------

### Pydantic Request Models for API

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Defines Pydantic models for validating incoming API requests. Includes models for chat, evaluation, document ingestion, and memory reset operations, ensuring data integrity and structure.

```python
from pydantic import BaseModel

class ChatRequest(BaseModel):
    message: str
    session_id: str
    max_tokens: int = 1000

class EvalRequest(BaseModel):
    conversation_id: str
    metrics: list[str]

class IngestDocumentsRequest(BaseModel):
    documents: list[dict]
    index_name: str

class ResetMemoryRequest(BaseModel):
    session_id: str
    reset_type: str = "full"

# Use in endpoints for automatic validation
@app.post("/chat")
async def chat(request: ChatRequest):
    return {"response": f"Processing: {request.message}"}
```

--------------------------------

### Request Models Definition

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

Defines Pydantic models for API request validation, including Chat, Eval, IngestDocuments, and ResetMemory requests.

```APIDOC
## Request Models Definition

Pydantic models for API request validation.

### File
`infrastructure/api/models.py`

### Models
```python
from pydantic import BaseModel

class ChatRequest(BaseModel):
    message: str
    session_id: str
    max_tokens: int = 1000

class EvalRequest(BaseModel):
    conversation_id: str
    metrics: list[str]

class IngestDocumentsRequest(BaseModel):
    documents: list[dict]
    index_name: str

class ResetMemoryRequest(BaseModel):
    session_id: str
    reset_type: str = "full"
```

### Usage in Endpoints
```python
# Assuming 'app' is your FastAPI instance
@app.post("/chat")
async def chat(request: ChatRequest):
    return {"response": f"Processing: {request.message}"}
```
```

--------------------------------

### Python Module Name Validation (Pre-Generation Hook)

Source: https://context7.com/neural-maze/agent-api-cookiecutter/llms.txt

A Python script used as a pre-generation hook in Cookiecutter to validate if the provided project slug is a valid Python module name. It uses a regular expression to ensure compatibility with Python's module naming conventions.

```python
# hooks/pre_gen_project.py validates module name
import re
import sys

MODULE_REGEX = r"^[_a-zA-Z][_a-zA-Z0-9]+$"
module_name = "my_agent_api"  # Derived from package_name

if not re.match(MODULE_REGEX, module_name):
    print("ERROR: The project slug (my-agent-api) is not a valid Python module name.")
    sys.exit(1)

# Valid: my_agent_api, agent_api, my_api_v2
# Invalid: my-agent-api, 123api, agent-api (hyphens not allowed)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.