# cwentor/dataagent architecture

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

- Interactive diagram: https://gitdiagram.com/cwentor/dataagent
- Repository: https://github.com/cwentor/dataagent

## Overview

DataAgent turns natural-language questions into controlled DSL, deterministic SQL, and explainable results. The principal flow enters through the web service, is routed and handled by the agent, compiled against a semantic contract and catalog, then safely executed and presented. Separate branches provide the LangGraph analysis workflow, sandbox and attribution skills, provider management, and audit/observability. Relationships for unsampled subsystems follow README descriptions; the source excerpts are incomplete, so some internal call details remain unverified.

Main entry points: [`web/service.py`](https://github.com/cwentor/dataagent/blob/master/web/service.py) (Web Service), [`core/orchestrator/langgraph_engine.py`](https://github.com/cwentor/dataagent/blob/master/core/orchestrator/langgraph_engine.py) (Graph Orchestrator), [`agent/pipeline.py`](https://github.com/cwentor/dataagent/blob/master/agent/pipeline.py) (NL to DSL), [`tools/builtins/_query_core.py`](https://github.com/cwentor/dataagent/blob/master/tools/builtins/_query_core.py) (Guarded Execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_web["Web Service<br/>[service.py]"]
  node_auth["Authentication<br/>[gateway.py]"]
  node_workbench["Web Workbench<br/>[app.js]"]
end

subgraph group_agent["Agent Workflow"]
  node_router["Intent Router<br/>[intent_router.py]"]
  node_dialogue["Dialogue Memory<br/>[memory.py]"]
  node_nl_dsl["NL to DSL<br/>[pipeline.py]"]
  node_tool_agent["Tool Agent<br/>[tool_agent.py]"]
  node_orchestrator["Graph Orchestrator"]
end

subgraph group_data["Query and Data"]
  node_contract["DSL Contract<br/>[dsl_schema.py]"]
  node_catalog["Semantic Catalog<br/>[catalog.py]"]
  node_policy["Access Policy<br/>[policy.py]"]
  node_compiler["SQL Compiler<br/>[sql_compiler.py]"]
  node_execution["Guarded Execution<br/>[_query_core.py]"]
  node_warehouse[("DuckDB Warehouse")]
end

subgraph group_analysis["Analysis and Delivery"]
  node_retrieval["Retrieval Guardrails<br/>[guardrails.py]"]
  node_sandbox["Analysis Sandbox<br/>[api.py]"]
  node_skills["Analysis Skills<br/>[decomposition.py]"]
  node_delivery["Explain and Visualize<br/>[explain.py]"]
end

subgraph group_platform["Platform Services"]
  node_providers["Model Providers<br/>[adapters.py]"]
  node_audit["Audit and Metrics<br/>[logging.py]"]
  node_sessions["Authentication Sessions<br/>[session.py]"]
end

node_user(("User"))

node_user -->|"asks"| node_web
node_web -->|"authenticates"| node_auth
node_web -->|"routes intent"| node_router
node_router -->|"dispatches query"| node_nl_dsl
node_web -->|"loads context"| node_dialogue
node_router -->|"dispatches tools"| node_tool_agent
node_web -->|"starts agent run"| node_orchestrator
node_nl_dsl -->|"produces DSL"| node_contract
node_nl_dsl -->|"applies policy"| node_policy
node_compiler -->|"consumes DSL"| node_contract
node_compiler -->|"resolves fields"| node_catalog
node_execution -->|"generates DSL"| node_nl_dsl
node_execution -->|"compiles query"| node_compiler
node_execution -->|"executes SQL"| node_warehouse
node_orchestrator -->|"uses retrieval"| node_retrieval
node_orchestrator -->|"runs analysis"| node_sandbox
node_sandbox -->|"runs skills"| node_skills
node_orchestrator -->|"creates report"| node_delivery
node_web -->|"returns explanation"| node_delivery
node_nl_dsl -.->|"requests model"| node_providers
node_orchestrator -.->|"selects model"| node_providers
node_web -->|"records activity"| node_audit
node_orchestrator -->|"emits metrics"| node_audit
node_auth -.->|"uses sessions"| node_sessions
node_workbench -->|"submits requests"| node_web

click node_web "https://github.com/cwentor/dataagent/blob/master/web/service.py"
click node_auth "https://github.com/cwentor/dataagent/blob/master/auth/gateway.py"
click node_workbench "https://github.com/cwentor/dataagent/blob/master/web/static/app.js"
click node_router "https://github.com/cwentor/dataagent/blob/master/agent/router/intent_router.py"
click node_dialogue "https://github.com/cwentor/dataagent/blob/master/agent/memory.py"
click node_nl_dsl "https://github.com/cwentor/dataagent/blob/master/agent/pipeline.py"
click node_tool_agent "https://github.com/cwentor/dataagent/blob/master/agent/tool_agent.py"
click node_orchestrator "https://github.com/cwentor/dataagent/blob/master/core/orchestrator/langgraph_engine.py"
click node_contract "https://github.com/cwentor/dataagent/blob/master/semantic/dsl_schema.py"
click node_catalog "https://github.com/cwentor/dataagent/blob/master/semantic/catalog.py"
click node_policy "https://github.com/cwentor/dataagent/blob/master/security/policy.py"
click node_compiler "https://github.com/cwentor/dataagent/blob/master/compiler/sql_compiler.py"
click node_execution "https://github.com/cwentor/dataagent/blob/master/tools/builtins/_query_core.py"
click node_retrieval "https://github.com/cwentor/dataagent/blob/master/core/retrieval/guardrails.py"
click node_sandbox "https://github.com/cwentor/dataagent/blob/master/core/sandbox/api.py"
click node_skills "https://github.com/cwentor/dataagent/blob/master/core/skills/decomposition.py"
click node_delivery "https://github.com/cwentor/dataagent/blob/master/present/explain.py"
click node_providers "https://github.com/cwentor/dataagent/blob/master/providers/adapters.py"
click node_audit "https://github.com/cwentor/dataagent/blob/master/audit/logging.py"
click node_sessions "https://github.com/cwentor/dataagent/blob/master/auth/session.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_web,node_auth,node_workbench,node_user toneBlue
class node_router,node_dialogue,node_nl_dsl,node_tool_agent,node_orchestrator toneAmber
class node_contract,node_catalog,node_policy,node_compiler,node_execution,node_warehouse toneMint
class node_retrieval,node_sandbox,node_skills,node_delivery toneRose
class node_providers,node_audit,node_sessions toneIndigo
```

## Components

### User Entry

- [Web Service](https://github.com/cwentor/dataagent/blob/master/web/service.py): `web/service.py`
- [Authentication](https://github.com/cwentor/dataagent/blob/master/auth/gateway.py): `auth/gateway.py`
- [Web Workbench](https://github.com/cwentor/dataagent/blob/master/web/static/app.js): `web/static/app.js`

### Agent Workflow

- [Intent Router](https://github.com/cwentor/dataagent/blob/master/agent/router/intent_router.py): `agent/router/intent_router.py`
- [Dialogue Memory](https://github.com/cwentor/dataagent/blob/master/agent/memory.py): `agent/memory.py`
- [NL to DSL](https://github.com/cwentor/dataagent/blob/master/agent/pipeline.py): `agent/pipeline.py`
- [Tool Agent](https://github.com/cwentor/dataagent/blob/master/agent/tool_agent.py): `agent/tool_agent.py`
- [Graph Orchestrator](https://github.com/cwentor/dataagent/blob/master/core/orchestrator/langgraph_engine.py): `core/orchestrator/langgraph_engine.py`

### Query and Data

- [DSL Contract](https://github.com/cwentor/dataagent/blob/master/semantic/dsl_schema.py): `semantic/dsl_schema.py`
- [Semantic Catalog](https://github.com/cwentor/dataagent/blob/master/semantic/catalog.py): `semantic/catalog.py`
- [Access Policy](https://github.com/cwentor/dataagent/blob/master/security/policy.py): `security/policy.py`
- [SQL Compiler](https://github.com/cwentor/dataagent/blob/master/compiler/sql_compiler.py): `compiler/sql_compiler.py`
- [Guarded Execution](https://github.com/cwentor/dataagent/blob/master/tools/builtins/_query_core.py): `tools/builtins/_query_core.py`
- **DuckDB Warehouse**

### Analysis and Delivery

- [Retrieval Guardrails](https://github.com/cwentor/dataagent/blob/master/core/retrieval/guardrails.py): `core/retrieval/guardrails.py`
- [Analysis Sandbox](https://github.com/cwentor/dataagent/blob/master/core/sandbox/api.py): `core/sandbox/api.py`
- [Analysis Skills](https://github.com/cwentor/dataagent/blob/master/core/skills/decomposition.py): `core/skills/decomposition.py`
- [Explain and Visualize](https://github.com/cwentor/dataagent/blob/master/present/explain.py): `present/explain.py`

### Platform Services

- [Model Providers](https://github.com/cwentor/dataagent/blob/master/providers/adapters.py): `providers/adapters.py`
- [Audit and Metrics](https://github.com/cwentor/dataagent/blob/master/audit/logging.py): `audit/logging.py`
- [Authentication Sessions](https://github.com/cwentor/dataagent/blob/master/auth/session.py): `auth/session.py`

### Other components

- **User**

## Connections

- User → Web Service: asks
- Web Service → Authentication: authenticates
- Web Service → Intent Router: routes intent (evidence: `agent/router/intent_router.py`)
- Intent Router → NL to DSL: dispatches query
- Web Service → Dialogue Memory: loads context (evidence: `web/service.py`)
- Intent Router → Tool Agent: dispatches tools
- Web Service → Graph Orchestrator: starts agent run
- NL to DSL → DSL Contract: produces DSL (evidence: `agent/pipeline.py`)
- NL to DSL → Access Policy: applies policy (evidence: `agent/pipeline.py`)
- SQL Compiler → DSL Contract: consumes DSL (evidence: `compiler/sql_compiler.py`)
- SQL Compiler → Semantic Catalog: resolves fields (evidence: `compiler/sql_compiler.py`)
- Guarded Execution → NL to DSL: generates DSL (evidence: `tools/builtins/_query_core.py`)
- Guarded Execution → SQL Compiler: compiles query (evidence: `tools/builtins/_query_core.py`)
- Guarded Execution → DuckDB Warehouse: executes SQL
- Graph Orchestrator → Retrieval Guardrails: uses retrieval
- Graph Orchestrator → Analysis Sandbox: runs analysis
- Analysis Sandbox → Analysis Skills: runs skills
- Graph Orchestrator → Explain and Visualize: creates report
- Web Service → Explain and Visualize: returns explanation
- NL to DSL → Model Providers: requests model
- Graph Orchestrator → Model Providers: selects model
- Web Service → Audit and Metrics: records activity (evidence: `web/service.py`)
- Graph Orchestrator → Audit and Metrics: emits metrics (evidence: `core/orchestrator/langgraph_engine.py`)
- Authentication → Authentication Sessions: uses sessions
- Web Workbench → Web Service: submits requests
