docs/technical.md

🛠️ 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 (to manage agent state and transitions)
• AI Engine: Gemini 3.1 (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)

.
├── .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.