54 lines
1.7 KiB
Markdown
54 lines
1.7 KiB
Markdown
### `AGENTS.md`
|
|
|
|
```markdown
|
|
# 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.
|