# 🛠️ Technical Specification: GitLab Context Brain

This document outlines the architecture, tech stack, and integration points for building the GitLab Context Brain.

---

## 🏗️ High-Level Architecture
The project follows a **Modular Multi-Agent Architecture** running on **GitLab Runners**, coordinated by **LangGraph**.

### Tech Stack
*   **Language**: Python 3.10+
*   **Orchestration**: [LangGraph](https://www.langchain.com/langgraph) (to manage agent state and transitions)
*   **AI Engine**: [Gemini 3.1](https://cloud.google.com/vertex-ai) (via Vertex AI SDK)
*   **Integrations**:
    *   **GitLab**: `python-gitlab` (REST/GraphQL) + `glab` CLI
    *   **GCP**: `google-cloud-*` SDKs (Logging, Error Reporting, Service Usage, Resource Manager)
*   **Runtime**: GitLab Duo Agent Platform (Custom Flows on Runners)

---

## 🤖 Agent Definitions

### 1. **GitLab Librarian (Context Agent)**
*   **Responsibility**: Gathers all repository-level data.
*   **Inputs**: `$AI_FLOW_CONTEXT` (MR Diff, Labels).
*   **Actions**: Search for related Issues, fetch previous MRs for the same files, identify `CODEOWNERS`.

### 2. **Cloud Sentinel (GCP Ops Agent)**
*   **Responsibility**: Gathers production health data.
*   **Actions**: Query Cloud Logging for error patterns in affected services; check Error Reporting for recurring production crashes linked to the code path.

### 3. **Gatekeeper (GCP Infra Agent)**
*   **Responsibility**: "Shift-Left" infrastructure validation.
*   **Actions**: 
    *   Compare code SDK usage with Terraform IAM policies.
    *   Query GCP Quotas for the target region.
    *   Run BigQuery `--dry-run` on modified SQL.

### 4. **The Architect (Synthesis Agent)**
*   **Responsibility**: Final reasoning and reporting.
*   **Actions**: Combine outputs from all agents into a structured, user-friendly GitLab comment.

---

## 🔄 Integration Flow

1.  **Trigger**: Developer opens an MR or @mentions the agent.
2.  **Deployment**: GitLab triggers a **Custom Flow** defined in `.gitlab/ai-agents/context-brain.yml`.
3.  **Runner Activation**: A GitLab Runner starts a Python container.
4.  **Execution**: 
    *   `main.py` initializes the LangGraph state.
    *   Agents execute their tools in parallel.
    *   Gemini synthesizes the findings.
5.  **Output**: The agent uses `glab mr note` to post the final Intelligence Report.

---

## 📂 Project Structure (Simple)
```text
.
├── .gitlab/
│   └── ai-agents/
│       └── context-brain.yml    # Flow & Trigger config
├── agents/
│   ├── librarian.py           # GitLab API logic
│   ├── sentinel.py            # GCP Ops logic
│   └── gatekeeper.py          # GCP Infra logic
├── main.py                    # LangGraph Orchestrator
├── requirements.txt           # Python dependencies
└── technical.md               # This file
```

---

## 🔑 Authentication & Security
*   **GitLab**: Uses the CI/CD job token (`$CI_JOB_TOKEN`) or a Project Access Token.
*   **GCP**: Uses **Workload Identity Federation** (recommended) or a Service Account Key stored in GitLab CI/CD Secrets.