# pranav1237/qyravex architecture

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

- Interactive diagram: https://gitdiagram.com/pranav1237/qyravex
- Repository: https://github.com/pranav1237/qyravex

## Overview

QYRAVEX is an auditable financial-research agent, not a trading system. Users submit a research question through the CLI or browser; a bounded planner selects typed research tools, which retrieve and calculate evidence. The agent records evidence and run metrics, then the CLI or dashboard presents a synthesized report with provenance, conflicts, and limitations. The README also documents a browser dashboard, market charting, forecasting, and offline benchmarks. Sampled source supports the core orchestration; some dashboard and forecast internals were not inspected.

Main entry points: [`src/workbridge/tools.py`](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/tools.py) (Tool Registry), [`src/workbridge/web.py`](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/web.py) (Web API), [`src/workbridge/agent.py`](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/agent.py) (Research Agent), [`src/workbridge/cli.py`](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/cli.py) (Research CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["Research CLI<br/>[cli.py]"]
  node_dashboard["Web API<br/>[web.py]"]
  node_browser["Browser Dashboard<br/>[app.js]"]
end

subgraph group_research["Research Workflow"]
  node_agent["Research Agent<br/>[agent.py]"]
  node_registry["Tool Registry<br/>[tools.py]"]
  node_synthesis["Report Synthesis<br/>[synthesis.py]"]
  node_models["Research Models<br/>[models.py]"]
end

subgraph group_sources["Data Sources"]
  node_providers["Provider Clients<br/>[providers.py]"]
  node_sec["SEC EDGAR"]
  node_markets["Market Data"]
  node_fred["FRED Data"]
  node_news["Public News"]
  node_finnhub["Finnhub"]
  node_newsapi["NewsAPI"]
end

subgraph group_state["Evidence and State"]
  node_memory[("Research Memory<br/>[memory.py]")]
  node_config["Runtime Settings<br/>[config.py]"]
end

subgraph group_quality["Quality and Monitoring"]
  node_metrics["Run Metrics<br/>[observability.py]"]
  node_benchmarks["Offline Benchmarks<br/>[benchmarks.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"submits research"| node_cli
node_researcher -->|"submits research"| node_browser
node_browser -->|"uses API"| node_dashboard
node_cli -->|"runs research"| node_agent
node_cli -->|"creates registry"| node_registry
node_cli -->|"opens memory"| node_memory
node_cli -->|"synthesizes report"| node_synthesis
node_dashboard -->|"runs research"| node_agent
node_dashboard -->|"creates registry"| node_registry
node_dashboard -->|"uses memory"| node_memory
node_dashboard -->|"synthesizes report"| node_synthesis
node_dashboard -->|"runs challenges"| node_benchmarks
node_dashboard -->|"gets chart data"| node_providers
node_agent -->|"executes tools"| node_registry
node_agent -->|"stores evidence"| node_memory
node_agent -->|"records metrics"| node_metrics
node_agent -->|"uses models"| node_models
node_registry -->|"retrieves data"| node_providers
node_registry -->|"searches evidence"| node_memory
node_registry -->|"returns results"| node_models
node_providers -->|"reads settings"| node_config
node_registry -->|"retrieves filings and facts"| node_sec
node_registry -->|"retrieves prices"| node_markets
node_registry -->|"retrieves macro series"| node_fred
node_registry -->|"searches headlines"| node_news
node_providers -.->|"optional enrichment"| node_finnhub
node_providers -.->|"optional enrichment"| node_newsapi
node_synthesis -->|"builds report"| node_models
node_benchmarks -->|"checks persistence"| node_memory
node_benchmarks -->|"checks synthesis"| node_synthesis
node_benchmarks -->|"checks evidence models"| node_models

click node_cli "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/cli.py"
click node_dashboard "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/web.py"
click node_browser "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/static/app.js"
click node_agent "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/agent.py"
click node_registry "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/tools.py"
click node_synthesis "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/synthesis.py"
click node_models "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/models.py"
click node_providers "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/providers.py"
click node_memory "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/memory.py"
click node_config "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/config.py"
click node_metrics "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/observability.py"
click node_benchmarks "https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/benchmarks.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_dashboard,node_browser toneBlue
class node_agent,node_registry,node_synthesis,node_models toneAmber
class node_providers,node_sec,node_markets,node_fred,node_news,node_finnhub,node_newsapi toneMint
class node_memory,node_config toneRose
class node_metrics,node_benchmarks,node_researcher toneIndigo
```

## Components

### User Interfaces

- [Research CLI](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/cli.py): `src/workbridge/cli.py`
- [Web API](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/web.py): `src/workbridge/web.py`
- [Browser Dashboard](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/static/app.js): `src/workbridge/static/app.js`

### Research Workflow

- [Research Agent](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/agent.py): `src/workbridge/agent.py`
- [Tool Registry](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/tools.py): `src/workbridge/tools.py`
- [Report Synthesis](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/synthesis.py): `src/workbridge/synthesis.py`
- [Research Models](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/models.py): `src/workbridge/models.py`

### Data Sources

- [Provider Clients](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/providers.py): `src/workbridge/providers.py`
- **SEC EDGAR**
- **Market Data**
- **FRED Data**
- **Public News**
- **Finnhub**
- **NewsAPI**

### Evidence and State

- [Research Memory](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/memory.py): `src/workbridge/memory.py`
- [Runtime Settings](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/config.py): `src/workbridge/config.py`

### Quality and Monitoring

- [Run Metrics](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/observability.py): `src/workbridge/observability.py`
- [Offline Benchmarks](https://github.com/pranav1237/qyravex/blob/Collage-Projects/src/workbridge/benchmarks.py): `src/workbridge/benchmarks.py`

### Other components

- **Researcher**

## Connections

- Researcher → Research CLI: submits research (evidence: `README.md`)
- Researcher → Browser Dashboard: submits research (evidence: `README.md`)
- Browser Dashboard → Web API: uses API (evidence: `README.md`)
- Research CLI → Research Agent: runs research (evidence: `src/workbridge/cli.py`)
- Research CLI → Tool Registry: creates registry (evidence: `src/workbridge/cli.py`)
- Research CLI → Research Memory: opens memory (evidence: `src/workbridge/cli.py`)
- Research CLI → Report Synthesis: synthesizes report (evidence: `src/workbridge/cli.py`)
- Web API → Research Agent: runs research (evidence: `src/workbridge/web.py`)
- Web API → Tool Registry: creates registry (evidence: `src/workbridge/web.py`)
- Web API → Research Memory: uses memory (evidence: `src/workbridge/web.py`)
- Web API → Report Synthesis: synthesizes report (evidence: `src/workbridge/web.py`)
- Web API → Offline Benchmarks: runs challenges (evidence: `src/workbridge/web.py`)
- Web API → Provider Clients: gets chart data (evidence: `src/workbridge/web.py`)
- Research Agent → Tool Registry: executes tools (evidence: `src/workbridge/agent.py`)
- Research Agent → Research Memory: stores evidence (evidence: `src/workbridge/agent.py`)
- Research Agent → Run Metrics: records metrics (evidence: `src/workbridge/agent.py`)
- Research Agent → Research Models: uses models (evidence: `src/workbridge/agent.py`)
- Tool Registry → Provider Clients: retrieves data (evidence: `src/workbridge/tools.py`)
- Tool Registry → Research Memory: searches evidence (evidence: `src/workbridge/tools.py`)
- Tool Registry → Research Models: returns results (evidence: `src/workbridge/tools.py`)
- Provider Clients → Runtime Settings: reads settings (evidence: `src/workbridge/providers.py`)
- Tool Registry → SEC EDGAR: retrieves filings and facts (evidence: `README.md`)
- Tool Registry → Market Data: retrieves prices (evidence: `README.md`)
- Tool Registry → FRED Data: retrieves macro series (evidence: `README.md`)
- Tool Registry → Public News: searches headlines (evidence: `README.md`)
- Provider Clients → Finnhub: optional enrichment (evidence: `README.md`)
- Provider Clients → NewsAPI: optional enrichment (evidence: `README.md`)
- Report Synthesis → Research Models: builds report (evidence: `src/workbridge/synthesis.py`)
- Offline Benchmarks → Research Memory: checks persistence (evidence: `src/workbridge/benchmarks.py`)
- Offline Benchmarks → Report Synthesis: checks synthesis (evidence: `src/workbridge/benchmarks.py`)
- Offline Benchmarks → Research Models: checks evidence models (evidence: `src/workbridge/benchmarks.py`)
