# denodo/denodo-ai-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/denodo/denodo-ai-sdk
- Repository: https://github.com/denodo/denodo-ai-sdk

## Overview

Denodo AI SDK exposes governed enterprise-data and AI capabilities through an API, with a sample chatbot as a user-facing client. The principal workflow is a natural-language question entering an answer endpoint, using metadata retrieval and VQL generation/execution to produce a grounded response. Separate branches support metadata search and DeepQuery research/report generation. The graph also shows configurable model/vector-store infrastructure and chatbot components. Source excerpts are partial; documented capabilities are retained, while unsupported implementation links are omitted or marked unverified.

Main entry points: [`api/main.py`](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/main.py) (SDK service), [`api/utils/data_category/pipeline.py`](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/pipeline.py) (VQL answer pipeline), [`api/deepquery/main.py`](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/deepquery/main.py) (Research orchestration), [`api/utils/state_manager.py`](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/state_manager.py) (Resource manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk_api["SDK API"]
  node_sdk_app["SDK service<br/>[main.py]"]
  node_answer_endpoint["Question answering<br/>[answerQuestion.py]"]
  node_metadata_endpoints["Metadata search"]
  node_deepquery_endpoint["DeepQuery endpoint<br/>[deepQuery.py]"]
  node_report_endpoint["Report endpoint"]
end

subgraph group_query_data["Query and Data"]
  node_data_pipeline["VQL answer pipeline<br/>[pipeline.py]"]
  node_vql_generation["VQL generation<br/>[generate.py]"]
  node_query_resolution["Query resolution<br/>[resolve.py]"]
  node_answer_building["Answer and plots<br/>[answer.py]"]
  node_sdk_utilities["SDK data utilities<br/>[sdk_utils.py]"]
  node_data_connection[("Denodo connection<br/>[connection.py]")]
  node_schema_catalog[("Schema catalog<br/>[catalog.py]")]
end

subgraph group_deepquery["DeepQuery Research"]
  node_analysis_orchestrator["Research orchestration<br/>[main.py]"]
  node_analysis_agent["Analysis agent<br/>[tools.py]"]
  node_reporting_agent["Report generation"]
end

subgraph group_runtime["AI Runtime"]
  node_resource_state["Resource manager<br/>[state_manager.py]"]
  node_llm_adapter["LLM adapters<br/>[uniformLLM.py]"]
  node_embedding_adapter["Embedding adapter"]
  node_vector_adapter["Vector-store adapter"]
  node_vector_service[("Vector database")]
  node_llm_provider["LLM provider"]
end

subgraph group_chatbot["Sample Chatbot"]
  node_chat_frontend["Chat interface<br/>[App.js]"]
  node_chat_api_client["API client<br/>[client.js]"]
  node_chat_routes["Chat routes<br/>[chat.py]"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_chat_sdk_client["SDK client<br/>[ai_sdk_client.py]"]
end

node_developer(("API caller"))
node_chat_user(("Chat user"))

node_developer -->|"submits requests"| node_sdk_app
node_sdk_app -->|"routes questions"| node_answer_endpoint
node_sdk_app -->|"routes search"| node_metadata_endpoints
node_sdk_app -->|"routes research"| node_deepquery_endpoint
node_sdk_app -->|"routes reports"| node_report_endpoint
node_answer_endpoint -.->|"processes questions"| node_data_pipeline
node_data_pipeline -->|"generates VQL"| node_vql_generation
node_data_pipeline -->|"resolves query"| node_query_resolution
node_data_pipeline -->|"builds response"| node_answer_building
node_query_resolution -.->|"executes VQL"| node_data_connection
node_metadata_endpoints -.->|"searches metadata"| node_vector_adapter
node_sdk_utilities -->|"uses connection"| node_data_connection
node_sdk_utilities -->|"uses catalog"| node_schema_catalog
node_deepquery_endpoint -->|"starts analysis"| node_analysis_orchestrator
node_analysis_orchestrator -->|"uses tools"| node_analysis_agent
node_analysis_orchestrator -->|"generates report"| node_reporting_agent
node_report_endpoint -->|"requests report"| node_analysis_orchestrator
node_resource_state -->|"creates models"| node_llm_adapter
node_resource_state -->|"creates embeddings"| node_embedding_adapter
node_resource_state -->|"creates stores"| node_vector_adapter
node_llm_adapter -.->|"calls provider"| node_llm_provider
node_vector_adapter -.->|"stores vectors"| node_vector_service
node_chat_user -.->|"asks questions"| node_chat_frontend
node_chat_frontend -->|"sends requests"| node_chat_api_client
node_chat_api_client -.->|"calls API"| node_chat_routes
node_chat_routes -.->|"delegates chat"| node_chat_service
node_chat_service -->|"uses SDK client"| node_chat_sdk_client
node_chat_sdk_client -.->|"calls SDK"| node_sdk_app

click node_sdk_app "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/main.py"
click node_answer_endpoint "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/endpoints/answerQuestion.py"
click node_metadata_endpoints "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/endpoints/similaritySearch.py"
click node_deepquery_endpoint "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/endpoints/deepQuery.py"
click node_report_endpoint "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/endpoints/generateDeepQueryReport.py"
click node_data_pipeline "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/pipeline.py"
click node_vql_generation "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/generate.py"
click node_query_resolution "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/resolve.py"
click node_answer_building "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/answer.py"
click node_sdk_utilities "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/sdk_utils.py"
click node_data_connection "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/data_marketplace/connection.py"
click node_schema_catalog "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/schema_catalog/catalog.py"
click node_analysis_orchestrator "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/deepquery/main.py"
click node_analysis_agent "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/deepquery/analysis_agent/tools.py"
click node_reporting_agent "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/deepquery/reporting_agent/report_processor.py"
click node_resource_state "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/state_manager.py"
click node_llm_adapter "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/uniformLLM.py"
click node_embedding_adapter "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/uniformEmbeddings.py"
click node_vector_adapter "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/uniformVectorStore.py"
click node_chat_frontend "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/frontend/src/App.js"
click node_chat_api_client "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/frontend/src/api/client.js"
click node_chat_routes "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/routes/chat.py"
click node_chat_service "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/services/chat_service.py"
click node_chat_sdk_client "https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/utils/ai_sdk_client.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_sdk_app,node_answer_endpoint,node_metadata_endpoints,node_deepquery_endpoint,node_report_endpoint,node_chat_user toneBlue
class node_data_pipeline,node_vql_generation,node_query_resolution,node_answer_building,node_sdk_utilities,node_data_connection,node_schema_catalog toneAmber
class node_analysis_orchestrator,node_analysis_agent,node_reporting_agent,node_developer toneMint
class node_resource_state,node_llm_adapter,node_embedding_adapter,node_vector_adapter,node_vector_service,node_llm_provider toneRose
class node_chat_frontend,node_chat_api_client,node_chat_routes,node_chat_service,node_chat_sdk_client toneIndigo
```

## Components

### SDK API

- [SDK service](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/main.py): `api/main.py`
- [Question answering](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/endpoints/answerQuestion.py): `api/endpoints/answerQuestion.py`
- [Metadata search](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/endpoints/similaritySearch.py): `api/endpoints/similaritySearch.py`
- [DeepQuery endpoint](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/endpoints/deepQuery.py): `api/endpoints/deepQuery.py`
- [Report endpoint](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/endpoints/generateDeepQueryReport.py): `api/endpoints/generateDeepQueryReport.py`

### Query and Data

- [VQL answer pipeline](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/pipeline.py): `api/utils/data_category/pipeline.py`
- [VQL generation](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/generate.py): `api/utils/data_category/generate.py`
- [Query resolution](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/resolve.py): `api/utils/data_category/resolve.py`
- [Answer and plots](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/data_category/answer.py): `api/utils/data_category/answer.py`
- [SDK data utilities](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/sdk_utils.py): `api/utils/sdk_utils.py`
- [Denodo connection](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/data_marketplace/connection.py): `utils/data_marketplace/connection.py`
- [Schema catalog](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/schema_catalog/catalog.py): `utils/schema_catalog/catalog.py`

### DeepQuery Research

- [Research orchestration](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/deepquery/main.py): `api/deepquery/main.py`
- [Analysis agent](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/deepquery/analysis_agent/tools.py): `api/deepquery/analysis_agent/tools.py`
- [Report generation](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/deepquery/reporting_agent/report_processor.py): `api/deepquery/reporting_agent/report_processor.py`

### AI Runtime

- [Resource manager](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/api/utils/state_manager.py): `api/utils/state_manager.py`
- [LLM adapters](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/uniformLLM.py): `utils/uniformLLM.py`
- [Embedding adapter](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/uniformEmbeddings.py): `utils/uniformEmbeddings.py`
- [Vector-store adapter](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/utils/uniformVectorStore.py): `utils/uniformVectorStore.py`
- **Vector database**
- **LLM provider**

### Sample Chatbot

- [Chat interface](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/frontend/src/App.js): `sample_chatbot/frontend/src/App.js`
- [API client](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/frontend/src/api/client.js): `sample_chatbot/frontend/src/api/client.js`
- [Chat routes](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/routes/chat.py): `sample_chatbot/routes/chat.py`
- [Chat service](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/services/chat_service.py): `sample_chatbot/services/chat_service.py`
- [SDK client](https://github.com/denodo/denodo-ai-sdk/blob/public/9/dev/sample_chatbot/utils/ai_sdk_client.py): `sample_chatbot/utils/ai_sdk_client.py`

### Other components

- **API caller**
- **Chat user**

## Connections

- API caller → SDK service: submits requests (evidence: `api/main.py`)
- SDK service → Question answering: routes questions (evidence: `api/main.py`)
- SDK service → Metadata search: routes search (evidence: `api/main.py`)
- SDK service → DeepQuery endpoint: routes research (evidence: `api/main.py`)
- SDK service → Report endpoint: routes reports (evidence: `api/main.py`)
- Question answering → VQL answer pipeline: processes questions
- VQL answer pipeline → VQL generation: generates VQL (evidence: `api/utils/data_category/pipeline.py`)
- VQL answer pipeline → Query resolution: resolves query (evidence: `api/utils/data_category/pipeline.py`)
- VQL answer pipeline → Answer and plots: builds response (evidence: `api/utils/data_category/pipeline.py`)
- Query resolution → Denodo connection: executes VQL
- Metadata search → Vector-store adapter: searches metadata
- SDK data utilities → Denodo connection: uses connection (evidence: `api/utils/sdk_utils.py`)
- SDK data utilities → Schema catalog: uses catalog (evidence: `api/utils/sdk_utils.py`)
- DeepQuery endpoint → Research orchestration: starts analysis (evidence: `api/endpoints/deepQuery.py`)
- Research orchestration → Analysis agent: uses tools (evidence: `api/deepquery/main.py`)
- Research orchestration → Report generation: generates report (evidence: `api/deepquery/main.py`)
- Report endpoint → Research orchestration: requests report (evidence: `api/endpoints/generateDeepQueryReport.py`)
- Resource manager → LLM adapters: creates models (evidence: `api/utils/state_manager.py`)
- Resource manager → Embedding adapter: creates embeddings (evidence: `api/utils/state_manager.py`)
- Resource manager → Vector-store adapter: creates stores (evidence: `api/utils/state_manager.py`)
- LLM adapters → LLM provider: calls provider
- Vector-store adapter → Vector database: stores vectors
- Chat user → Chat interface: asks questions
- Chat interface → API client: sends requests (evidence: `sample_chatbot/frontend/src/App.js`)
- API client → Chat routes: calls API
- Chat routes → Chat service: delegates chat
- Chat service → SDK client: uses SDK client (evidence: `sample_chatbot/services/chat_service.py`)
- SDK client → SDK service: calls SDK