jusfutura/AGENTS.md

AGENTS.md

# Agents and responsibilities

This document describes the logical "agents" or roles inside the system.
It is meant to make the architecture easy to understand.

## 1. Gateway API (Flask app)

- **Role:** HTTP gateway and authentication layer.
- **Responsibilities:**
  - Expose REST endpoints over HTTP.
  - Enforce Google OAuth authentication.
  - Validate incoming requests (model name, prompt).
  - Forward prompts to the Ollama backend.
  - Return structured JSON responses.

## 2. Auth agent (Google OAuth)

- **Role:** Handle user authentication via Google.
- **Responsibilities:**
  - Redirect unauthenticated users to Google login.
  - Receive OAuth callback and exchange code for tokens.
  - Extract user identity (email, profile).
  - Store session information securely (server-side session or signed cookies).
  - Ensure only authenticated users can access `/api/*` endpoints.

## 3. Model routing agent

- **Role:** Decide which Ollama model to call.
- **Responsibilities:**
  - Map user-provided model names (e.g., `llama3.2`, `gemma4`, `qwen2.5`)
    to actual Ollama model identifiers.
  - Provide a default model if none is specified.
  - Handle unsupported model names gracefully (clear error messages).

## 4. Ollama backend agent

- **Role:** Execute model inference.
- **Responsibilities:**
  - Receive prompts from the gateway.
  - Call the Ollama HTTP API (e.g., `/api/generate`).
  - Stream or aggregate responses from Ollama.
  - Return the final text output to the gateway.

## 5. Logging and monitoring agent

- **Role:** Provide observability.
- **Responsibilities:**
  - Log incoming requests (without storing sensitive data).
  - Log errors and timeouts from Ollama.
  - Expose a simple health endpoint (`/health`) for monitoring.