From 811ab6f45c26c366cba6e626ed4e8f5843f6a937 Mon Sep 17 00:00:00 2001
From: Renato Rosa <renatoxsr@gmail.com>
Date: Wed, 19 Aug 2026 20:16:08 -0300
Subject: [PATCH] Adicionar AGENTS.md

---
 AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6ac9035
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,53 @@
+### `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.