# pavansaxena/mars architecture

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

- Interactive diagram: https://gitdiagram.com/pavansaxena/mars
- Repository: https://github.com/pavansaxena/mars

## Overview

MARS accepts executive queries through its API, routes strategic requests to relevant department specialists, grounds their assessments in historical precedents and optional live data, then synthesizes a risk-aware recommendation with lineage. The graph preserves the documented calibration, conformal-risk, and evaluation capabilities. Several runtime modules are listed but unsampled, so those connections are shown only where the README explicitly documents them; evaluation links likewise follow the cited imports or documentation.

Main entry points: [`backend/app/agents/master_agent.py`](https://github.com/pavansaxena/mars/blob/main/backend/app/agents/master_agent.py) (Workflow Orchestrator), [`backend/app/services/case_retrieval_service.py`](https://github.com/pavansaxena/mars/blob/main/backend/app/services/case_retrieval_service.py) (Precedent Retrieval), [`backend/app/mcp/server.py`](https://github.com/pavansaxena/mars/blob/main/backend/app/mcp/server.py) (MCP Tool Layer), [`backend/app/reasoning/aggregator.py`](https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/aggregator.py) (Assessment Aggregator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Surface"]
  node_api_routes["Query API<br/>[routes.py]"]
  node_compat_api["OpenAI-Compatible API<br/>[openai_compat.py]"]
end

subgraph group_agents["Decision Agents"]
  node_master["Workflow Orchestrator<br/>[master_agent.py]"]
  node_finance["Finance Agent<br/>[finance_agent.py]"]
  node_legal["Legal Agent<br/>[legal_agent.py]"]
  node_operations["Operations Agent"]
  node_rd["R&amp;D Agent<br/>[rd_agent.py]"]
end

subgraph group_reasoning["Reasoning Engine"]
  node_router["Semantic Router<br/>[semantic_router.py]"]
  node_aggregator["Assessment Aggregator<br/>[aggregator.py]"]
  node_confidence["Confidence Calibration<br/>[confidence.py]"]
  node_conformal["Conformal Risk Bounds"]
  node_weights["Weight Registry<br/>[weight_registry.py]"]
end

subgraph group_evidence["Evidence and Tools"]
  node_retrieval_service["Precedent Retrieval"]
  node_retriever["Vector Retriever<br/>[retriever.py]"]
  node_embedder["Text Embedder<br/>[embedder.py]"]
  node_supabase[("Supabase pgvector<br/>[supabase_client.py]")]
  node_mcp["MCP Tool Layer<br/>[server.py]"]
  node_live_data["Live Data Providers<br/>[base.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_data["Evaluation Dataset<br/>[dataset.py]"]
  node_eval_retrieval["Retrieval Benchmark<br/>[eval_retrieval.py]"]
  node_eval_routing["Routing Benchmark<br/>[eval_routing.py]"]
  node_eval_generation["Generation Benchmark<br/>[eval_generation.py]"]
  node_eval_longitudinal["Longitudinal Evaluation"]
end

node_executive(("Corporate Executive"))
node_recommendation["Decision Recommendation"]

node_executive -->|"submits query"| node_api_routes
node_api_routes -->|"invokes workflow"| node_master
node_executive -->|"submits query"| node_compat_api
node_compat_api -->|"invokes workflow"| node_master
node_master -->|"routes query"| node_router
node_master -->|"dispatches active agents"| node_finance
node_master -->|"dispatches active agents"| node_legal
node_master -->|"dispatches active agents"| node_operations
node_master -->|"dispatches active agents"| node_rd
node_finance -->|"retrieves precedents"| node_retrieval_service
node_legal -->|"retrieves precedents"| node_retrieval_service
node_operations -->|"retrieves precedents"| node_retrieval_service
node_rd -->|"retrieves precedents"| node_retrieval_service
node_retrieval_service -->|"calls retrieval"| node_retriever
node_retriever -->|"embeds query"| node_embedder
node_retriever -->|"queries vectors"| node_supabase
node_router -->|"embeds query"| node_embedder
node_finance -.->|"uses live tools"| node_mcp
node_legal -.->|"uses live tools"| node_mcp
node_operations -.->|"uses live tools"| node_mcp
node_rd -.->|"uses live tools"| node_mcp
node_mcp -->|"dispatches provider calls"| node_live_data
node_master -->|"sends assessments"| node_aggregator
node_aggregator -->|"ranks by confidence"| node_confidence
node_aggregator -->|"computes risk bounds"| node_conformal
node_confidence -.->|"uses calibrated weights"| node_weights
node_aggregator -->|"produces recommendation"| node_recommendation
node_api_routes -->|"returns response"| node_recommendation
node_eval_retrieval -->|"loads cases"| node_eval_data
node_eval_routing -->|"loads cases"| node_eval_data
node_eval_generation -->|"loads cases"| node_eval_data
node_eval_longitudinal -.->|"evaluates chronology"| node_eval_data
node_eval_retrieval -->|"benchmarks retrieval"| node_retrieval_service
node_eval_routing -->|"benchmarks routing"| node_router
node_eval_generation -->|"evaluates generation"| node_master

click node_api_routes "https://github.com/pavansaxena/mars/blob/main/backend/app/api/routes.py"
click node_compat_api "https://github.com/pavansaxena/mars/blob/main/backend/app/api/openai_compat.py"
click node_master "https://github.com/pavansaxena/mars/blob/main/backend/app/agents/master_agent.py"
click node_router "https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/semantic_router.py"
click node_finance "https://github.com/pavansaxena/mars/blob/main/backend/app/agents/finance_agent.py"
click node_legal "https://github.com/pavansaxena/mars/blob/main/backend/app/agents/legal_agent.py"
click node_operations "https://github.com/pavansaxena/mars/blob/main/backend/app/agents/operations_agent.py"
click node_rd "https://github.com/pavansaxena/mars/blob/main/backend/app/agents/rd_agent.py"
click node_aggregator "https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/aggregator.py"
click node_confidence "https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/confidence.py"
click node_conformal "https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/conformal_predictor.py"
click node_weights "https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/weight_registry.py"
click node_retrieval_service "https://github.com/pavansaxena/mars/blob/main/backend/app/services/case_retrieval_service.py"
click node_retriever "https://github.com/pavansaxena/mars/blob/main/backend/app/storage/retriever.py"
click node_embedder "https://github.com/pavansaxena/mars/blob/main/backend/app/storage/embedder.py"
click node_supabase "https://github.com/pavansaxena/mars/blob/main/backend/app/services/supabase_client.py"
click node_mcp "https://github.com/pavansaxena/mars/blob/main/backend/app/mcp/server.py"
click node_live_data "https://github.com/pavansaxena/mars/blob/main/backend/app/mcp/providers/base.py"
click node_eval_data "https://github.com/pavansaxena/mars/blob/main/evaluation/dataset.py"
click node_eval_retrieval "https://github.com/pavansaxena/mars/blob/main/evaluation/eval_retrieval.py"
click node_eval_routing "https://github.com/pavansaxena/mars/blob/main/evaluation/eval_routing.py"
click node_eval_generation "https://github.com/pavansaxena/mars/blob/main/evaluation/eval_generation.py"
click node_eval_longitudinal "https://github.com/pavansaxena/mars/blob/main/evaluation/eval_longitudinal.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_api_routes,node_compat_api toneBlue
class node_master,node_finance,node_legal,node_operations,node_rd toneAmber
class node_router,node_aggregator,node_confidence,node_conformal,node_weights toneMint
class node_retrieval_service,node_retriever,node_embedder,node_supabase,node_mcp,node_live_data toneRose
class node_eval_data,node_eval_retrieval,node_eval_routing,node_eval_generation,node_eval_longitudinal,node_executive,node_recommendation toneIndigo
```

## Components

### API Surface

- [Query API](https://github.com/pavansaxena/mars/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [OpenAI-Compatible API](https://github.com/pavansaxena/mars/blob/main/backend/app/api/openai_compat.py): `backend/app/api/openai_compat.py`

### Decision Agents

- [Workflow Orchestrator](https://github.com/pavansaxena/mars/blob/main/backend/app/agents/master_agent.py): `backend/app/agents/master_agent.py`
- [Finance Agent](https://github.com/pavansaxena/mars/blob/main/backend/app/agents/finance_agent.py): `backend/app/agents/finance_agent.py`
- [Legal Agent](https://github.com/pavansaxena/mars/blob/main/backend/app/agents/legal_agent.py): `backend/app/agents/legal_agent.py`
- [Operations Agent](https://github.com/pavansaxena/mars/blob/main/backend/app/agents/operations_agent.py): `backend/app/agents/operations_agent.py`
- [R&D Agent](https://github.com/pavansaxena/mars/blob/main/backend/app/agents/rd_agent.py): `backend/app/agents/rd_agent.py`

### Reasoning Engine

- [Semantic Router](https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/semantic_router.py): `backend/app/reasoning/semantic_router.py`
- [Assessment Aggregator](https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/aggregator.py): `backend/app/reasoning/aggregator.py`
- [Confidence Calibration](https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/confidence.py): `backend/app/reasoning/confidence.py`
- [Conformal Risk Bounds](https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/conformal_predictor.py): `backend/app/reasoning/conformal_predictor.py`
- [Weight Registry](https://github.com/pavansaxena/mars/blob/main/backend/app/reasoning/weight_registry.py): `backend/app/reasoning/weight_registry.py`

### Evidence and Tools

- [Precedent Retrieval](https://github.com/pavansaxena/mars/blob/main/backend/app/services/case_retrieval_service.py): `backend/app/services/case_retrieval_service.py`
- [Vector Retriever](https://github.com/pavansaxena/mars/blob/main/backend/app/storage/retriever.py): `backend/app/storage/retriever.py`
- [Text Embedder](https://github.com/pavansaxena/mars/blob/main/backend/app/storage/embedder.py): `backend/app/storage/embedder.py`
- [Supabase pgvector](https://github.com/pavansaxena/mars/blob/main/backend/app/services/supabase_client.py): `backend/app/services/supabase_client.py`
- [MCP Tool Layer](https://github.com/pavansaxena/mars/blob/main/backend/app/mcp/server.py): `backend/app/mcp/server.py`
- [Live Data Providers](https://github.com/pavansaxena/mars/blob/main/backend/app/mcp/providers/base.py): `backend/app/mcp/providers/base.py`

### Evaluation

- [Evaluation Dataset](https://github.com/pavansaxena/mars/blob/main/evaluation/dataset.py): `evaluation/dataset.py`
- [Retrieval Benchmark](https://github.com/pavansaxena/mars/blob/main/evaluation/eval_retrieval.py): `evaluation/eval_retrieval.py`
- [Routing Benchmark](https://github.com/pavansaxena/mars/blob/main/evaluation/eval_routing.py): `evaluation/eval_routing.py`
- [Generation Benchmark](https://github.com/pavansaxena/mars/blob/main/evaluation/eval_generation.py): `evaluation/eval_generation.py`
- [Longitudinal Evaluation](https://github.com/pavansaxena/mars/blob/main/evaluation/eval_longitudinal.py): `evaluation/eval_longitudinal.py`

### Other components

- **Corporate Executive**
- **Decision Recommendation**

## Connections

- Corporate Executive → Query API: submits query
- Query API → Workflow Orchestrator: invokes workflow (evidence: `backend/app/api/routes.py`)
- Corporate Executive → OpenAI-Compatible API: submits query
- OpenAI-Compatible API → Workflow Orchestrator: invokes workflow (evidence: `backend/main.py`)
- Workflow Orchestrator → Semantic Router: routes query
- Workflow Orchestrator → Finance Agent: dispatches active agents
- Workflow Orchestrator → Legal Agent: dispatches active agents
- Workflow Orchestrator → Operations Agent: dispatches active agents
- Workflow Orchestrator → R&D Agent: dispatches active agents
- Finance Agent → Precedent Retrieval: retrieves precedents
- Legal Agent → Precedent Retrieval: retrieves precedents
- Operations Agent → Precedent Retrieval: retrieves precedents
- R&D Agent → Precedent Retrieval: retrieves precedents
- Precedent Retrieval → Vector Retriever: calls retrieval (evidence: `backend/app/services/case_retrieval_service.py`)
- Vector Retriever → Text Embedder: embeds query (evidence: `backend/app/storage/retriever.py`)
- Vector Retriever → Supabase pgvector: queries vectors (evidence: `backend/app/storage/retriever.py`)
- Semantic Router → Text Embedder: embeds query (evidence: `backend/app/reasoning/semantic_router.py`)
- Finance Agent → MCP Tool Layer: uses live tools
- Legal Agent → MCP Tool Layer: uses live tools
- Operations Agent → MCP Tool Layer: uses live tools
- R&D Agent → MCP Tool Layer: uses live tools
- MCP Tool Layer → Live Data Providers: dispatches provider calls (evidence: `backend/app/mcp/server.py`)
- Workflow Orchestrator → Assessment Aggregator: sends assessments
- Assessment Aggregator → Confidence Calibration: ranks by confidence
- Assessment Aggregator → Conformal Risk Bounds: computes risk bounds
- Confidence Calibration → Weight Registry: uses calibrated weights
- Assessment Aggregator → Decision Recommendation: produces recommendation
- Query API → Decision Recommendation: returns response (evidence: `backend/app/api/routes.py`)
- Retrieval Benchmark → Evaluation Dataset: loads cases (evidence: `evaluation/eval_retrieval.py`)
- Routing Benchmark → Evaluation Dataset: loads cases (evidence: `evaluation/eval_routing.py`)
- Generation Benchmark → Evaluation Dataset: loads cases (evidence: `evaluation/eval_generation.py`)
- Longitudinal Evaluation → Evaluation Dataset: evaluates chronology
- Retrieval Benchmark → Precedent Retrieval: benchmarks retrieval (evidence: `evaluation/eval_retrieval.py`)
- Routing Benchmark → Semantic Router: benchmarks routing (evidence: `evaluation/eval_routing.py`)
- Generation Benchmark → Workflow Orchestrator: evaluates generation (evidence: `evaluation/eval_generation.py`)
