# challenge10-pbia/rag_cognus architecture

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

- Interactive diagram: https://gitdiagram.com/challenge10-pbia/rag_cognus
- Repository: https://github.com/challenge10-pbia/rag_cognus

## Overview

Cognus is a local RAG application for answering questions from the Databricks Gold knowledge view and evaluating retrieval and answers. The main workflow is to sync Gold data to a local snapshot, retrieve passages with BM25 or dense search, and optionally generate grounded answers; users can invoke this through the CLI or browser chat. Evaluation records per-question results and aggregate metrics in local MLflow. The graph follows the README and sampled source; some chat wiring is visible only in the source index.

Main entry points: [`src/rag_cognus/cli.py`](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/cli.py) (CLI commands), [`src/rag_cognus/evaluation.py`](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/evaluation.py) (Evaluation runner), [`src/rag_cognus/chat_app.py`](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/chat_app.py) (Browser chat), [`src/rag_cognus/retrieval.py`](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/retrieval.py) (Gold retriever)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_chat["Browser chat<br/>[chat_app.py]"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_gold["Gold sync<br/>[gold.py]"]
  node_retriever["Gold retriever<br/>[retrieval.py]"]
end

subgraph group_answers["Answer generation"]
  node_pipeline["RAG pipeline<br/>[chain.py]"]
end

subgraph group_evaluation["Evaluation and tracking"]
  node_judge["Response judge<br/>[judges.py]"]
  node_eval_cases["Evaluation cases<br/>[questions.jsonl]"]
  node_evaluation["Evaluation runner<br/>[evaluation.py]"]
  node_metrics["Metric scoring<br/>[metrics.py]"]
end

node_user(("User"))
node_databricks[("Databricks Gold")]
node_ollama["Ollama models"]
node_mlflow[("Local MLflow")]

node_user -->|"runs commands"| node_cli
node_user -->|"asks questions"| node_chat
node_cli -->|"loads settings"| node_settings
node_chat -->|"configures runtime"| node_settings
node_cli -->|"syncs Gold"| node_gold
node_gold -->|"reads view"| node_databricks
node_cli -->|"loads snapshot"| node_gold
node_cli -->|"builds index"| node_retriever
node_chat -->|"prepares search"| node_retriever
node_retriever -->|"reads options"| node_settings
node_retriever -.->|"embeds passages"| node_ollama
node_cli -->|"runs prediction"| node_pipeline
node_chat -->|"generates answers"| node_pipeline
node_pipeline -->|"retrieves evidence"| node_retriever
node_pipeline -->|"generates response"| node_ollama
node_cli -->|"loads questions"| node_eval_cases
node_cli -->|"starts evaluation"| node_evaluation
node_chat -->|"evaluates answers"| node_evaluation
node_evaluation -->|"retrieves cases"| node_retriever
node_evaluation -->|"predicts answers"| node_pipeline
node_evaluation -->|"scores responses"| node_judge
node_judge -->|"judges locally"| node_ollama
node_evaluation -->|"scores retrieval"| node_metrics
node_evaluation -->|"logs evaluations"| node_mlflow
node_chat -->|"shows run metrics"| node_mlflow

click node_cli "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/cli.py"
click node_chat "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/chat_app.py"
click node_settings "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/config.py"
click node_gold "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/gold.py"
click node_retriever "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/retrieval.py"
click node_pipeline "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/chain.py"
click node_judge "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/judges.py"
click node_eval_cases "https://github.com/challenge10-pbia/rag_cognus/blob/main/data/evaluation/questions.jsonl"
click node_evaluation "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/evaluation.py"
click node_metrics "https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/metrics.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_chat,node_user toneBlue
class node_settings,node_gold,node_retriever,node_databricks,node_mlflow toneAmber
class node_pipeline toneMint
class node_judge,node_eval_cases,node_evaluation,node_metrics toneRose
class node_ollama toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/cli.py): `src/rag_cognus/cli.py`
- [Browser chat](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/chat_app.py): `src/rag_cognus/chat_app.py`

### Knowledge and retrieval

- [Runtime settings](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/config.py): `src/rag_cognus/config.py`
- [Gold sync](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/gold.py): `src/rag_cognus/gold.py`
- [Gold retriever](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/retrieval.py): `src/rag_cognus/retrieval.py`

### Answer generation

- [RAG pipeline](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/chain.py): `src/rag_cognus/chain.py`

### Evaluation and tracking

- [Response judge](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/judges.py): `src/rag_cognus/judges.py`
- [Evaluation cases](https://github.com/challenge10-pbia/rag_cognus/blob/main/data/evaluation/questions.jsonl): `data/evaluation/questions.jsonl`
- [Evaluation runner](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/evaluation.py): `src/rag_cognus/evaluation.py`
- [Metric scoring](https://github.com/challenge10-pbia/rag_cognus/blob/main/src/rag_cognus/metrics.py): `src/rag_cognus/metrics.py`

### Other components

- **User**
- **Databricks Gold**
- **Ollama models**
- **Local MLflow**

## Connections

- User → CLI commands: runs commands (evidence: `README.md`)
- User → Browser chat: asks questions (evidence: `README.md`)
- CLI commands → Runtime settings: loads settings (evidence: `src/rag_cognus/cli.py`)
- Browser chat → Runtime settings: configures runtime (evidence: `src/rag_cognus/chat_app.py`)
- CLI commands → Gold sync: syncs Gold (evidence: `src/rag_cognus/cli.py`)
- Gold sync → Databricks Gold: reads view (evidence: `src/rag_cognus/gold.py`)
- CLI commands → Gold sync: loads snapshot (evidence: `src/rag_cognus/cli.py`)
- CLI commands → Gold retriever: builds index (evidence: `src/rag_cognus/cli.py`)
- Browser chat → Gold retriever: prepares search (evidence: `src/rag_cognus/chat_app.py`)
- Gold retriever → Runtime settings: reads options (evidence: `src/rag_cognus/retrieval.py`)
- Gold retriever → Ollama models: embeds passages (evidence: `src/rag_cognus/retrieval.py`)
- CLI commands → RAG pipeline: runs prediction (evidence: `src/rag_cognus/cli.py`)
- Browser chat → RAG pipeline: generates answers (evidence: `src/rag_cognus/chat_app.py`)
- RAG pipeline → Gold retriever: retrieves evidence (evidence: `src/rag_cognus/chain.py`)
- RAG pipeline → Ollama models: generates response (evidence: `src/rag_cognus/chain.py`)
- CLI commands → Evaluation cases: loads questions (evidence: `README.md`)
- CLI commands → Evaluation runner: starts evaluation (evidence: `src/rag_cognus/cli.py`)
- Browser chat → Evaluation runner: evaluates answers (evidence: `src/rag_cognus/chat_app.py`)
- Evaluation runner → Gold retriever: retrieves cases (evidence: `src/rag_cognus/evaluation.py`)
- Evaluation runner → RAG pipeline: predicts answers (evidence: `src/rag_cognus/evaluation.py`)
- Evaluation runner → Response judge: scores responses (evidence: `src/rag_cognus/evaluation.py`)
- Response judge → Ollama models: judges locally (evidence: `src/rag_cognus/judges.py`)
- Evaluation runner → Metric scoring: scores retrieval (evidence: `src/rag_cognus/evaluation.py`)
- Evaluation runner → Local MLflow: logs evaluations (evidence: `src/rag_cognus/evaluation.py`)
- Browser chat → Local MLflow: shows run metrics (evidence: `README.md`)