# kartika09/mas-reliability-capstone architecture

> Architecture diagram of the GitHub repository kartika09/mas-reliability-capstone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kartika09/mas-reliability-capstone
- Repository: https://github.com/kartika09/mas-reliability-capstone

## Overview

This repository is a starter multi-agent research-analysis system. A researcher submits a question to the pipeline, which plans evidence and critical subtasks, optionally retrieves supporting abstracts, and has independent agents produce outputs. Depending on the experiment condition, the pipeline validates the evidence handoff, checks peer consistency, and may invoke a guard and recovery before the planner synthesizes a report. It records messages and run results for evaluation. Retrieval and fault injection are optional branches; several research mechanisms remain documented stubs. The dataset loader and logger details are inferred from documented interfaces, not sampled source.

Main entry points: [`pipeline.py`](https://github.com/kartika09/mas-reliability-capstone/blob/main/pipeline.py) (Run pipeline), [`schemas/models.py`](https://github.com/kartika09/mas-reliability-capstone/blob/main/schemas/models.py) (Data contracts), [`retrieval/retriever.py`](https://github.com/kartika09/mas-reliability-capstone/blob/main/retrieval/retriever.py) (Embedding retrieval), [`agents/agents.py`](https://github.com/kartika09/mas-reliability-capstone/blob/main/agents/agents.py) (Evidence agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Pipeline orchestration"]
  node_pipeline["Run pipeline<br/>[pipeline.py]"]
  node_injector["Fault injection<br/>[injector.py]"]
  node_report["Research report"]
end

subgraph group_research["Research and retrieval"]
  node_planner["Planner agent<br/>[agents.py]"]
  node_evidence["Evidence agent<br/>[agents.py]"]
  node_critical["Critical agent<br/>[agents.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_dataset["SciFact dataset"]
  node_loader["Dataset loader<br/>[dataset.py]"]
  node_retriever["Embedding retrieval<br/>[retriever.py]"]
  node_index["In-memory index<br/>[retriever.py]"]
end

subgraph group_checks["Validation and recovery"]
  node_validator["Sequential validator"]
  node_peer["Peer consistency<br/>[checker.py]"]
  node_guard["Guard decision<br/>[decision.py]"]
  node_recovery["Recovery<br/>[recovery.py]"]
end

subgraph group_contracts["Contracts and evaluation"]
  node_schemas["Data contracts<br/>[models.py]"]
  node_logger["Run logger<br/>[logger.py]"]
  node_runresult["Run result<br/>[models.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"submits question"| node_pipeline
node_pipeline -->|"decomposes and synthesizes"| node_planner
node_planner -->|"requests completion"| node_llm
node_pipeline -->|"requests evidence"| node_evidence
node_pipeline -->|"requests critique"| node_critical
node_evidence -->|"requests completion"| node_llm
node_critical -->|"requests completion"| node_llm
node_dataset -->|"loaded by"| node_loader
node_loader -->|"provides corpus"| node_retriever
node_retriever -->|"builds index"| node_index
node_pipeline -->|"retrieves passages"| node_retriever
node_retriever -->|"supplies context"| node_evidence
node_retriever -->|"supplies context"| node_critical
node_pipeline -.->|"optionally injects fault"| node_injector
node_pipeline -->|"validates handoff"| node_validator
node_pipeline -->|"checks agreement"| node_peer
node_pipeline -->|"requests decision"| node_guard
node_pipeline -->|"recovers flagged output"| node_recovery
node_pipeline -->|"verifies recovery"| node_peer
node_pipeline -->|"verifies recovery"| node_validator
node_pipeline -->|"logs messages and run"| node_logger
node_pipeline -->|"returns report"| node_report
node_pipeline -->|"creates run result"| node_runresult
node_pipeline -->|"uses contracts"| node_schemas
node_planner -->|"parses and returns shapes"| node_schemas
node_evidence -->|"parses output shape"| node_schemas
node_critical -->|"parses output shape"| node_schemas
node_validator -->|"returns validation result"| node_schemas
node_peer -->|"returns peer result"| node_schemas
node_guard -->|"returns guard decision"| node_schemas

click node_pipeline "https://github.com/kartika09/mas-reliability-capstone/blob/main/pipeline.py"
click node_planner "https://github.com/kartika09/mas-reliability-capstone/blob/main/agents/agents.py"
click node_evidence "https://github.com/kartika09/mas-reliability-capstone/blob/main/agents/agents.py"
click node_critical "https://github.com/kartika09/mas-reliability-capstone/blob/main/agents/agents.py"
click node_llm "https://github.com/kartika09/mas-reliability-capstone/blob/main/llm_client.py"
click node_dataset "https://github.com/kartika09/mas-reliability-capstone/blob/main/mas_scifact_dataset%20(1).json"
click node_loader "https://github.com/kartika09/mas-reliability-capstone/blob/main/dataset.py"
click node_retriever "https://github.com/kartika09/mas-reliability-capstone/blob/main/retrieval/retriever.py"
click node_index "https://github.com/kartika09/mas-reliability-capstone/blob/main/retrieval/retriever.py"
click node_injector "https://github.com/kartika09/mas-reliability-capstone/blob/main/fault_injection/injector.py"
click node_validator "https://github.com/kartika09/mas-reliability-capstone/blob/main/validation/sequential_validator.py"
click node_peer "https://github.com/kartika09/mas-reliability-capstone/blob/main/peer_consistency/checker.py"
click node_guard "https://github.com/kartika09/mas-reliability-capstone/blob/main/guard/decision.py"
click node_recovery "https://github.com/kartika09/mas-reliability-capstone/blob/main/guard/recovery.py"
click node_schemas "https://github.com/kartika09/mas-reliability-capstone/blob/main/schemas/models.py"
click node_logger "https://github.com/kartika09/mas-reliability-capstone/blob/main/evaluation/logger.py"
click node_runresult "https://github.com/kartika09/mas-reliability-capstone/blob/main/schemas/models.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_pipeline,node_injector,node_report toneBlue
class node_planner,node_evidence,node_critical,node_llm,node_dataset,node_loader,node_retriever,node_index toneAmber
class node_validator,node_peer,node_guard,node_recovery toneMint
class node_schemas,node_logger,node_runresult toneRose
class node_researcher toneIndigo
```

## Components

### Pipeline orchestration

- [Run pipeline](https://github.com/kartika09/mas-reliability-capstone/blob/main/pipeline.py): `pipeline.py`
- [Fault injection](https://github.com/kartika09/mas-reliability-capstone/blob/main/fault_injection/injector.py): `fault_injection/injector.py`
- **Research report**

### Research and retrieval

- [Planner agent](https://github.com/kartika09/mas-reliability-capstone/blob/main/agents/agents.py): `agents/agents.py`
- [Evidence agent](https://github.com/kartika09/mas-reliability-capstone/blob/main/agents/agents.py): `agents/agents.py`
- [Critical agent](https://github.com/kartika09/mas-reliability-capstone/blob/main/agents/agents.py): `agents/agents.py`
- [LLM client](https://github.com/kartika09/mas-reliability-capstone/blob/main/llm_client.py): `llm_client.py`
- [SciFact dataset](https://github.com/kartika09/mas-reliability-capstone/blob/main/mas_scifact_dataset%20(1).json): `mas_scifact_dataset (1).json`
- [Dataset loader](https://github.com/kartika09/mas-reliability-capstone/blob/main/dataset.py): `dataset.py`
- [Embedding retrieval](https://github.com/kartika09/mas-reliability-capstone/blob/main/retrieval/retriever.py): `retrieval/retriever.py`
- [In-memory index](https://github.com/kartika09/mas-reliability-capstone/blob/main/retrieval/retriever.py): `retrieval/retriever.py`

### Validation and recovery

- [Sequential validator](https://github.com/kartika09/mas-reliability-capstone/blob/main/validation/sequential_validator.py): `validation/sequential_validator.py`
- [Peer consistency](https://github.com/kartika09/mas-reliability-capstone/blob/main/peer_consistency/checker.py): `peer_consistency/checker.py`
- [Guard decision](https://github.com/kartika09/mas-reliability-capstone/blob/main/guard/decision.py): `guard/decision.py`
- [Recovery](https://github.com/kartika09/mas-reliability-capstone/blob/main/guard/recovery.py): `guard/recovery.py`

### Contracts and evaluation

- [Data contracts](https://github.com/kartika09/mas-reliability-capstone/blob/main/schemas/models.py): `schemas/models.py`
- [Run logger](https://github.com/kartika09/mas-reliability-capstone/blob/main/evaluation/logger.py): `evaluation/logger.py`
- [Run result](https://github.com/kartika09/mas-reliability-capstone/blob/main/schemas/models.py): `schemas/models.py`

### Other components

- **Researcher**

## Connections

- Researcher → Run pipeline: submits question
- Run pipeline → Planner agent: decomposes and synthesizes
- Planner agent → LLM client: requests completion
- Run pipeline → Evidence agent: requests evidence
- Run pipeline → Critical agent: requests critique
- Evidence agent → LLM client: requests completion
- Critical agent → LLM client: requests completion
- SciFact dataset → Dataset loader: loaded by
- Dataset loader → Embedding retrieval: provides corpus
- Embedding retrieval → In-memory index: builds index
- Run pipeline → Embedding retrieval: retrieves passages
- Embedding retrieval → Evidence agent: supplies context
- Embedding retrieval → Critical agent: supplies context
- Run pipeline → Fault injection: optionally injects fault
- Run pipeline → Sequential validator: validates handoff
- Run pipeline → Peer consistency: checks agreement
- Run pipeline → Guard decision: requests decision
- Run pipeline → Recovery: recovers flagged output
- Run pipeline → Peer consistency: verifies recovery
- Run pipeline → Sequential validator: verifies recovery
- Run pipeline → Run logger: logs messages and run
- Run pipeline → Research report: returns report
- Run pipeline → Run result: creates run result
- Run pipeline → Data contracts: uses contracts
- Planner agent → Data contracts: parses and returns shapes
- Evidence agent → Data contracts: parses output shape
- Critical agent → Data contracts: parses output shape
- Sequential validator → Data contracts: returns validation result
- Peer consistency → Data contracts: returns peer result
- Guard decision → Data contracts: returns guard decision