# vivek1106-04/agentdb architecture

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

- Interactive diagram: https://gitdiagram.com/vivek1106-04/agentdb
- Repository: https://github.com/vivek1106-04/agentdb

## Overview

agentdb provides engine-aware analytics guidance through adapters, query and plan analysis, context, memory, and an MCP tool catalog. Its companion agenteval package benchmarks natural-language-to-SQL systems across ClickHouse and Databricks: suites supply questions, systems produce attempts, engines execute queries, and scoring and reporting turn traces into results. The README documents these product capabilities; some subsystem internals are unsampled, so uncertain implementation links are omitted.

Main entry points: [`eval/agenteval/cli.py`](https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/cli.py) (Benchmark CLI), [`src/agentdb/server/tools`](https://github.com/vivek1106-04/agentdb/tree/main/src/agentdb/server/tools) (Analytics Tools), [`src/agentdb/core/advisor`](https://github.com/vivek1106-04/agentdb/tree/main/src/agentdb/core/advisor) (Query Advisor), [`src/agentdb/adapters/base.py`](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/base.py) (Adapter Contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Agent Interface"]
  node_tool_catalog["Tool Catalog<br/>[app.py]"]
  node_tool_handlers["Analytics Tools"]
  node_server_transport["Server Transport<br/>[transports.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_engine["Engine Access"]
  node_adapter_contract["Adapter Contract<br/>[base.py]"]
  node_ch_adapter["ClickHouse Adapter<br/>[clickhouse.py]"]
  node_dbx_adapter["Databricks Adapter<br/>[databricks.py]"]
  node_dbx_client["Databricks Client"]
  node_engine_data[("Analytics Warehouses")]
end

subgraph group_analysis["Analytics Guidance"]
  node_context_builder["Context Builder<br/>[context_builder.py]"]
  node_context["Grounding Context<br/>[context.py]"]
  node_query_shape["Query Shape<br/>[query_shape.py]"]
  node_plan_analysis["Plan Analysis<br/>[plan_analyzer.py]"]
  node_advisor["Query Advisor"]
end

subgraph group_memory["Query Memory"]
  node_memory_store[("Exemplar Store<br/>[store.py]")]
end

subgraph group_benchmark["Benchmark Harness"]
  node_benchmark_cli["Benchmark CLI<br/>[cli.py]"]
  node_task_suites["Task Suites<br/>[tasks.py]"]
  node_systems["Agent Systems"]
  node_model_clients["Model Clients"]
  node_query_execution["Query Execution<br/>[execution.py]"]
  node_eval_engines["Benchmark Engines"]
  node_scoring["Blind Scoring<br/>[scorer.py]"]
  node_trace_report["Traces and Reports<br/>[report.py]"]
end

node_agent_client(("Agent Client"))

node_agent_client -.->|"calls tools"| node_tool_catalog
node_tool_catalog -->|"dispatches"| node_tool_handlers
node_server_transport -.->|"serves"| node_tool_catalog
node_tool_handlers -.->|"requests context"| node_context_builder
node_tool_handlers -->|"requests advice"| node_advisor
node_tool_handlers -.->|"uses memory"| node_memory_store
node_context_builder -->|"builds"| node_context
node_context_builder -->|"reads engine data"| node_adapter_contract
node_adapter_contract -->|"implemented by"| node_ch_adapter
node_adapter_contract -->|"implemented by"| node_dbx_adapter
node_dbx_client -->|"supports client"| node_dbx_adapter
node_ch_adapter -.->|"queries"| node_engine_data
node_dbx_client -->|"executes statements"| node_engine_data
node_advisor -->|"analyzes SQL"| node_query_shape
node_advisor -.->|"analyzes plans"| node_plan_analysis
node_advisor -->|"uses engine capabilities"| node_adapter_contract
node_benchmark_cli -->|"loads tasks"| node_task_suites
node_benchmark_cli -->|"runs systems"| node_systems
node_systems -->|"uses models"| node_model_clients
node_systems -->|"executes attempts"| node_query_execution
node_query_execution -->|"executes queries"| node_eval_engines
node_eval_engines -.->|"queries"| node_engine_data
node_benchmark_cli -.->|"scores attempts"| node_scoring
node_benchmark_cli -->|"generates reports"| node_trace_report
node_scoring -.->|"supplies scores"| node_trace_report

click node_tool_catalog "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/server/app.py"
click node_tool_handlers "https://github.com/vivek1106-04/agentdb/tree/main/src/agentdb/server/tools"
click node_server_transport "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/server/transports.py"
click node_config "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/config.py"
click node_adapter_contract "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/base.py"
click node_ch_adapter "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/clickhouse.py"
click node_dbx_adapter "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/databricks.py"
click node_dbx_client "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/databricks_client.py"
click node_context_builder "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/context_builder.py"
click node_context "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/context.py"
click node_query_shape "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/query_shape.py"
click node_plan_analysis "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/plan_analyzer.py"
click node_advisor "https://github.com/vivek1106-04/agentdb/tree/main/src/agentdb/core/advisor"
click node_memory_store "https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/memory/store.py"
click node_benchmark_cli "https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/cli.py"
click node_task_suites "https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/tasks.py"
click node_systems "https://github.com/vivek1106-04/agentdb/tree/main/eval/agenteval/systems"
click node_model_clients "https://github.com/vivek1106-04/agentdb/tree/main/eval/agenteval/models"
click node_query_execution "https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/execution.py"
click node_eval_engines "https://github.com/vivek1106-04/agentdb/tree/main/eval/agenteval/engines"
click node_scoring "https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/scorer.py"
click node_trace_report "https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/report.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_tool_catalog,node_tool_handlers,node_server_transport,node_config,node_agent_client toneBlue
class node_adapter_contract,node_ch_adapter,node_dbx_adapter,node_dbx_client,node_engine_data toneAmber
class node_context_builder,node_context,node_query_shape,node_plan_analysis,node_advisor toneMint
class node_memory_store toneRose
class node_benchmark_cli,node_task_suites,node_systems,node_model_clients,node_query_execution,node_eval_engines,node_scoring,node_trace_report toneIndigo
```

## Components

### Agent Interface

- [Tool Catalog](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/server/app.py): `src/agentdb/server/app.py`
- [Analytics Tools](https://github.com/vivek1106-04/agentdb/tree/main/src/agentdb/server/tools): `src/agentdb/server/tools`
- [Server Transport](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/server/transports.py): `src/agentdb/server/transports.py`
- [Configuration](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/config.py): `src/agentdb/config.py`

### Engine Access

- [Adapter Contract](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/base.py): `src/agentdb/adapters/base.py`
- [ClickHouse Adapter](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/clickhouse.py): `src/agentdb/adapters/clickhouse.py`
- [Databricks Adapter](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/databricks.py): `src/agentdb/adapters/databricks.py`
- [Databricks Client](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/adapters/databricks_client.py): `src/agentdb/adapters/databricks_client.py`
- **Analytics Warehouses**

### Analytics Guidance

- [Context Builder](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/context_builder.py): `src/agentdb/core/context_builder.py`
- [Grounding Context](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/context.py): `src/agentdb/core/context.py`
- [Query Shape](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/query_shape.py): `src/agentdb/core/query_shape.py`
- [Plan Analysis](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/plan_analyzer.py): `src/agentdb/core/plan_analyzer.py`
- [Query Advisor](https://github.com/vivek1106-04/agentdb/tree/main/src/agentdb/core/advisor): `src/agentdb/core/advisor`

### Query Memory

- [Exemplar Store](https://github.com/vivek1106-04/agentdb/blob/main/src/agentdb/core/memory/store.py): `src/agentdb/core/memory/store.py`

### Benchmark Harness

- [Benchmark CLI](https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/cli.py): `eval/agenteval/cli.py`
- [Task Suites](https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/tasks.py): `eval/agenteval/tasks.py`
- [Agent Systems](https://github.com/vivek1106-04/agentdb/tree/main/eval/agenteval/systems): `eval/agenteval/systems`
- [Model Clients](https://github.com/vivek1106-04/agentdb/tree/main/eval/agenteval/models): `eval/agenteval/models`
- [Query Execution](https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/execution.py): `eval/agenteval/execution.py`
- [Benchmark Engines](https://github.com/vivek1106-04/agentdb/tree/main/eval/agenteval/engines): `eval/agenteval/engines`
- [Blind Scoring](https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/scorer.py): `eval/agenteval/scorer.py`
- [Traces and Reports](https://github.com/vivek1106-04/agentdb/blob/main/eval/agenteval/report.py): `eval/agenteval/report.py`

### Other components

- **Agent Client**

## Connections

- Agent Client → Tool Catalog: calls tools
- Tool Catalog → Analytics Tools: dispatches (evidence: `src/agentdb/server/app.py`)
- Server Transport → Tool Catalog: serves
- Analytics Tools → Context Builder: requests context
- Analytics Tools → Query Advisor: requests advice (evidence: `src/agentdb/server/tools/advice.py`)
- Analytics Tools → Exemplar Store: uses memory
- Context Builder → Grounding Context: builds (evidence: `src/agentdb/core/context_builder.py`)
- Context Builder → Adapter Contract: reads engine data (evidence: `src/agentdb/core/context_builder.py`)
- Adapter Contract → ClickHouse Adapter: implemented by (evidence: `src/agentdb/adapters/clickhouse.py`)
- Adapter Contract → Databricks Adapter: implemented by (evidence: `src/agentdb/adapters/databricks.py`)
- Databricks Client → Databricks Adapter: supports client (evidence: `src/agentdb/adapters/databricks_client.py`)
- ClickHouse Adapter → Analytics Warehouses: queries
- Databricks Client → Analytics Warehouses: executes statements (evidence: `src/agentdb/adapters/databricks_client.py`)
- Query Advisor → Query Shape: analyzes SQL (evidence: `src/agentdb/core/advisor/clickhouse_advisor.py`)
- Query Advisor → Plan Analysis: analyzes plans
- Query Advisor → Adapter Contract: uses engine capabilities (evidence: `src/agentdb/core/advisor/clickhouse_advisor.py`)
- Benchmark CLI → Task Suites: loads tasks (evidence: `eval/agenteval/cli.py`)
- Benchmark CLI → Agent Systems: runs systems (evidence: `eval/agenteval/cli.py`)
- Agent Systems → Model Clients: uses models (evidence: `eval/agenteval/models/anthropic.py`)
- Agent Systems → Query Execution: executes attempts (evidence: `eval/agenteval/execution.py`)
- Query Execution → Benchmark Engines: executes queries (evidence: `eval/agenteval/engines/connect.py`)
- Benchmark Engines → Analytics Warehouses: queries
- Benchmark CLI → Blind Scoring: scores attempts
- Benchmark CLI → Traces and Reports: generates reports (evidence: `eval/agenteval/cli.py`)
- Blind Scoring → Traces and Reports: supplies scores
