# saghosh8/ai-devops-release-assistant architecture

> Architecture diagram of the GitHub repository saghosh8/ai-devops-release-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saghosh8/ai-devops-release-assistant
- Repository: https://github.com/saghosh8/ai-devops-release-assistant

## Overview

This is an AI DevOps release assistant that grew from Gemini runbook Q&A into a tool-using agent, while retaining a separate RAG path for repository history. Users enter through the CLI or MCP; the agent plans investigations, invokes GitHub and analysis capabilities, applies safety checks, and returns an answer or proposed action. The RAG path ingests GitHub material, indexes it, retrieves relevant chunks, and grounds answers with Ollama. Several links rely on the SOURCE INDEX or README because the corresponding implementation was not excerpted; they are cited only where those references establish the relationship.

Main entry points: [`devops_assistant/agent.py`](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/agent.py) (Planning agent), [`devops_assistant/rag/retriever.py`](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/retriever.py) (Retriever), [`devops_assistant/rag/ask_rag.py`](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/ask_rag.py) (RAG question entry), [`devops_assistant/client.py`](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/client.py) (Gemini client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Command CLI<br/>[cli.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_ragcli["RAG question entry<br/>[ask_rag.py]"]
end

subgraph group_agent["Agent investigation"]
  node_agent["Planning agent<br/>[agent.py]"]
  node_github["GitHub tools<br/>[github_tools.py]"]
  node_ci["CI analysis"]
  node_commit["Commit analysis<br/>[commit_analysis.py]"]
  node_deployment["Deployment troubleshooting"]
  node_prreview["PR review<br/>[pr_review.py]"]
  node_logs["Log analysis<br/>[log_analysis.py]"]
end

subgraph group_rag["Repository knowledge"]
  node_ingest["GitHub ingestion<br/>[ingest.py]"]
  node_chunk["Document chunking<br/>[chunking.py]"]
  node_embed["Embedding model<br/>[embeddings.py]"]
  node_retriever["Retriever<br/>[retriever.py]"]
  node_store[("FAISS vector store<br/>[vectorstore.py]")]
  node_raganswer["Grounded answer<br/>[rag_client.py]"]
end

subgraph group_safety["Safety and telemetry"]
  node_security["Guardrails<br/>[security.py]"]
  node_observability["Cost and latency<br/>[observability.py]"]
end

subgraph group_models["Language models"]
  node_prompts["Prompt templates<br/>[prompts.py]"]
  node_client["Gemini client<br/>[client.py]"]
end

node_user(("DevOps user"))
node_githubservice["GitHub API"]
node_ollama["Ollama"]
node_gemini["Gemini API"]
node_runbook["Structured runbook"]

node_user -->|"asks through"| node_cli
node_cli -->|"runs agent"| node_agent
node_cli -->|"sends Q&amp;A"| node_client
node_client -->|"uses prompts"| node_prompts
node_client -->|"calls API"| node_gemini
node_client -->|"returns structured"| node_runbook
node_user -->|"requests tools"| node_mcp
node_mcp -->|"invokes agent"| node_agent
node_agent -->|"calls tools"| node_github
node_github -->|"reads and writes"| node_githubservice
node_agent -->|"analyzes failures"| node_ci
node_agent -->|"analyzes commits"| node_commit
node_agent -->|"troubleshoots"| node_deployment
node_agent -->|"reviews PRs"| node_prreview
node_ci -->|"extracts errors"| node_logs
node_agent -->|"validates results"| node_security
node_agent -->|"records metrics"| node_observability
node_user -->|"asks repository question"| node_ragcli
node_ragcli -->|"retrieves context"| node_retriever
node_ragcli -->|"builds index"| node_ingest
node_ingest -->|"fetches repository data"| node_githubservice
node_retriever -->|"loads documents"| node_ingest
node_retriever -->|"chunks documents"| node_chunk
node_retriever -->|"embeds chunks"| node_embed
node_retriever -->|"builds and searches"| node_store
node_ragcli -->|"requests answer"| node_raganswer
node_raganswer -->|"retrieves chunks"| node_retriever
node_raganswer -->|"generates answer"| node_ollama
node_agent -->|"searches history"| node_retriever

click node_cli "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/cli.py"
click node_mcp "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/mcp_server.py"
click node_agent "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/agent.py"
click node_github "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/github_tools.py"
click node_ci "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/ci_failure_analysis.py"
click node_commit "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/commit_analysis.py"
click node_deployment "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/deployment_troubleshooting.py"
click node_prreview "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/pr_review.py"
click node_logs "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/log_analysis.py"
click node_ragcli "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/ask_rag.py"
click node_ingest "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/ingest.py"
click node_chunk "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/chunking.py"
click node_embed "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/embeddings.py"
click node_retriever "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/retriever.py"
click node_store "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/vectorstore.py"
click node_raganswer "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/rag_client.py"
click node_security "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/security.py"
click node_observability "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/observability.py"
click node_prompts "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/prompts.py"
click node_client "https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp,node_ragcli,node_user toneBlue
class node_agent,node_github,node_ci,node_commit,node_deployment,node_prreview,node_logs toneAmber
class node_ingest,node_chunk,node_embed,node_retriever,node_store,node_raganswer,node_githubservice,node_gemini toneMint
class node_security,node_observability toneRose
class node_prompts,node_client,node_ollama,node_runbook toneIndigo
```

## Components

### User interfaces

- [Command CLI](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/cli.py): `devops_assistant/cli.py`
- [MCP server](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/mcp_server.py): `devops_assistant/mcp_server.py`
- [RAG question entry](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/ask_rag.py): `devops_assistant/rag/ask_rag.py`

### Agent investigation

- [Planning agent](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/agent.py): `devops_assistant/agent.py`
- [GitHub tools](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/github_tools.py): `devops_assistant/github_tools.py`
- [CI analysis](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/ci_failure_analysis.py): `devops_assistant/analysis/ci_failure_analysis.py`
- [Commit analysis](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/commit_analysis.py): `devops_assistant/analysis/commit_analysis.py`
- [Deployment troubleshooting](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/deployment_troubleshooting.py): `devops_assistant/analysis/deployment_troubleshooting.py`
- [PR review](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/pr_review.py): `devops_assistant/analysis/pr_review.py`
- [Log analysis](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/analysis/log_analysis.py): `devops_assistant/analysis/log_analysis.py`

### Repository knowledge

- [GitHub ingestion](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/ingest.py): `devops_assistant/rag/ingest.py`
- [Document chunking](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/chunking.py): `devops_assistant/rag/chunking.py`
- [Embedding model](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/embeddings.py): `devops_assistant/rag/embeddings.py`
- [Retriever](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/retriever.py): `devops_assistant/rag/retriever.py`
- [FAISS vector store](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/vectorstore.py): `devops_assistant/rag/vectorstore.py`
- [Grounded answer](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/rag/rag_client.py): `devops_assistant/rag/rag_client.py`

### Safety and telemetry

- [Guardrails](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/security.py): `devops_assistant/security.py`
- [Cost and latency](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/observability.py): `devops_assistant/observability.py`

### Language models

- [Prompt templates](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/prompts.py): `devops_assistant/prompts.py`
- [Gemini client](https://github.com/saghosh8/ai-devops-release-assistant/blob/main/devops_assistant/client.py): `devops_assistant/client.py`

### Other components

- **DevOps user**
- **GitHub API**
- **Ollama**
- **Gemini API**
- **Structured runbook**

## Connections

- DevOps user → Command CLI: asks through (evidence: `README.md`)
- Command CLI → Planning agent: runs agent (evidence: `devops_assistant/cli.py`)
- Command CLI → Gemini client: sends Q&A (evidence: `devops_assistant/cli.py`)
- Gemini client → Prompt templates: uses prompts (evidence: `devops_assistant/client.py`)
- Gemini client → Gemini API: calls API (evidence: `devops_assistant/client.py`)
- Gemini client → Structured runbook: returns structured (evidence: `README.md`)
- DevOps user → MCP server: requests tools (evidence: `README.md`)
- MCP server → Planning agent: invokes agent (evidence: `devops_assistant/mcp_server.py`)
- Planning agent → GitHub tools: calls tools (evidence: `devops_assistant/agent.py`)
- GitHub tools → GitHub API: reads and writes (evidence: `devops_assistant/github_tools.py`)
- Planning agent → CI analysis: analyzes failures (evidence: `devops_assistant/agent.py`)
- Planning agent → Commit analysis: analyzes commits (evidence: `devops_assistant/agent.py`)
- Planning agent → Deployment troubleshooting: troubleshoots (evidence: `devops_assistant/agent.py`)
- Planning agent → PR review: reviews PRs (evidence: `devops_assistant/agent.py`)
- CI analysis → Log analysis: extracts errors (evidence: `devops_assistant/analysis/ci_failure_analysis.py`)
- Planning agent → Guardrails: validates results (evidence: `devops_assistant/agent.py`)
- Planning agent → Cost and latency: records metrics (evidence: `devops_assistant/agent.py`)
- DevOps user → RAG question entry: asks repository question (evidence: `README.md`)
- RAG question entry → Retriever: retrieves context (evidence: `devops_assistant/rag/ask_rag.py`)
- RAG question entry → GitHub ingestion: builds index (evidence: `devops_assistant/rag/ask_rag.py`)
- GitHub ingestion → GitHub API: fetches repository data (evidence: `devops_assistant/rag/ingest.py`)
- Retriever → GitHub ingestion: loads documents (evidence: `devops_assistant/rag/retriever.py`)
- Retriever → Document chunking: chunks documents (evidence: `devops_assistant/rag/retriever.py`)
- Retriever → Embedding model: embeds chunks (evidence: `devops_assistant/rag/retriever.py`)
- Retriever → FAISS vector store: builds and searches (evidence: `devops_assistant/rag/retriever.py`)
- RAG question entry → Grounded answer: requests answer (evidence: `devops_assistant/rag/ask_rag.py`)
- Grounded answer → Retriever: retrieves chunks (evidence: `devops_assistant/rag/rag_client.py`)
- Grounded answer → Ollama: generates answer (evidence: `devops_assistant/rag/rag_client.py`)
- Planning agent → Retriever: searches history (evidence: `devops_assistant/agent.py`)