# thirdweb-dev/ai architecture

> Architecture diagram of the GitHub repository thirdweb-dev/ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thirdweb-dev/ai
- Repository: https://github.com/thirdweb-dev/ai

## Overview

##### Project’s Type and Purpose
- Project Type: A Python-based SDK that serves as a middleware layer for blockchain operations. It exposes services for data intelligence (Insight), wallet/contract interactions (Engine), and natural language-powered blockchain communications (Nebula).
- Purpose: To abstract and simplify complex on-chain operations and facilitate integration with different AI frameworks via adapters (e.g., LangChain, OpenAI, Coinbase Agentkit, etc.) while also providing a server (MCP) that can be run independently.

##### File Structure
- Top-Level Organization:
- Directories like “python/thirdweb-ai” and “python/thirdweb-mcp” clearly split the library’s core functionality and the MCP server component.
- The “python/thirdweb-ai/src/thirdweb_ai” subdirectories are organized into “adapters”, “common”, “services” and “tools”, suggesting a layered design where:
▪ Services (located in services/) implement the core functions for Engine, Insight, and Nebula.
▪ Adapters (in adapters/) are bridging modules to integrate various external AI frameworks and specialized tooling.
▪ Tools provide utility functions for the agents.
- External Schemas:
- The “openapi” directory contains JSON files (engine.json and insight.json) which likely define API contracts or service interfaces.
- Example Implementations:
- The “python/examples” directory provides sample integrations for multiple adapters, including setup instructions (README, pyproject.toml), reinforcing the extensibility of the toolkit.

##### README Insights
- The README highlights three central services (Insight, Engine, Nebula) and explains their respective roles—from data analysis to wallet operations and AI-enabled blockchain interactions.
- It also details how to integrate with various frameworks using the adapters, backed by examples.
- The quickstart sections for both MCP Server and Python SDK provide context for both standalone and integrated operation modes.

a. Main Components:
- Core Services Layer:
▪ Insight (blockchain data analysis: chains, transactions, blocks, events, prices, tokens)
▪ Engine (wallet management, read/write operations on blockchain)
▪ Nebula (AI-driven natural language interaction)
- Adapters/Integration Layer:
▪ Specific adapters for frameworks such as autogen, coinbase_agentkit, goat, langchain, llama_index, mcp, openai, pydantic_ai, and smolagents.
- MCP Server:
▪ A separate component that wraps around the Engine (and possibly other tools) for a server-based execution (using uvx or pipx installation).
- External Interfaces:
▪ Blockchain networks, smart contracts, and possibly external price feeds or market data sources (as implied by the features in Insight).
- Utility/Tooling:
▪ Common utilities and helper modules (located in the “common” and “tools” directories) that support the services and adapters.

b. Relationships and Interactions:
- The Core Services (Insight, Engine, Nebula) constitute the backbone.
- Adapters interface with these services to provide integration with various AI frameworks, thus enabling agents to interact with blockchain operations through chosen ecosystems.
- The MCP server wraps parts of the system (likely Engine) to expose RESTful or CLI-driven interactions.
- External blockchain networks interact with these services either directly (transaction flows, data feeds) or indirectly through API calls (as defined in the openapi files).
- Utility modules provide common functionality supporting all of these layers.

c. Architectural Patterns and Design Principles:
- Modularity and Extensibility: The clear separation between core services and adapters demonstrates adherence to the Open/Closed Principle where new integrations can be added without modifying core logic.
- Service-Oriented Architecture: Breaking down functionalities into distinct services (Insight, Engine, Nebula) that interact through defined interfaces and APIs.
- Layered Architecture: With a presentation or adapter layer on top of a robust business logic (services) layer.
- API Contract Definition: The inclusion of OpenAPI specifications for services suggests a design focused on standardized interactions.

d. Relevant Technologies, Frameworks, and Tools:
- Python (with pyproject configuration and examples)
- uvx/uv.lock for server running and dependency management
- Integration with popular AI frameworks (LangChain, OpenAI, etc.) via adapters
- Use of OpenAPI for documenting APIs
- Pip and pipx for package installation and distribution

##### Recommended Elements
- Core Services: Insight, Engine, Nebula
- External Interfaces: Blockchain network, smart contracts, price feeds, etc.
- Data flow (e.g., Insight fetching blockchain data, Engine handling transaction operations)
- Dependencies between components (e.g., Adapters consuming core service functionality)
- Integration paths (e.g., user agents feeding commands into Nebula via adapters)
- Distinguish between framework-specific adapters vs. core services vs. external systems.
- Optionally separate the “example” components to illustrate sample usage scenarios.

##### Detailing the Architecture Components
└─ Positioned as a deployment option that wraps around the Core SDK (especially Engine) for live blockchain operations.
- “Common/Tools” as supporting modules that feed into the Core SDK.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces and API Contracts
    ext["\"External Blockchain Networks & Data Sources\""]:::external
    api_insight["\"API Contract: Insight\""]:::api
    api_engine["\"API Contract: Engine\""]:::api
    common["\"Common Utilities\""]:::common
    tools["\"Tools/Utilities for Agents\""]:::common

    %% Core SDK: Thirdweb AI Core SDK
    subgraph "Thirdweb AI Core SDK"
        insight["\"Insight Service\""]:::service
        engine["\"Engine Service\""]:::service
        nebula["\"Nebula Service\""]:::service
    end

    %% Adapters Layer
    subgraph "Adapters Layer"
        autogen["\"Autogen Adapter\""]:::adapter
        coinbase["\"Coinbase Agentkit Adapter\""]:::adapter
        goat["\"Goat Adapter\""]:::adapter
        langchain["\"LangChain Adapter\""]:::adapter
        llama["\"Llama Index Adapter\""]:::adapter
        mcpAdapter["\"MCP Adapter\""]:::adapter
        openai["\"OpenAI Adapter\""]:::adapter
        pydantic["\"Pydantic AI Adapter\""]:::adapter
        smolagents["\"Smolagents Adapter\""]:::adapter
    end

    %% MCP Server
    mcp_server["\"MCP Server\""]:::server

    %% Connections: External Interfaces to Core Services
    ext -->|"blockchain_data"| insight
    ext -->|"blockchain_ops"| engine

    %% Connections: API Contracts to Core Services
    api_insight -->|"api_contract"| insight
    api_engine -->|"api_contract"| engine

    %% Connections: Common and Tools to Core Services
    common -->|"support"| insight
    common -->|"support"| engine
    common -->|"support"| nebula
    tools -->|"assist"| insight
    tools -->|"assist"| engine
    tools -->|"assist"| nebula

    %% Connections: Adapters Layer integrating with Core Services (targeting Engine Service)
    autogen -->|"integrate"| engine
    coinbase -->|"integrate"| engine
    goat -->|"integrate"| engine
    langchain -->|"integrate"| engine
    llama -->|"integrate"| engine
    mcpAdapter -->|"integrate"| engine
    openai -->|"integrate"| engine
    pydantic -->|"integrate"| engine
    smolagents -->|"integrate"| engine

    %% Connection: MCP Server wrapping Engine Service
    mcp_server -->|"wraps"| engine

    %% Click Events
    click insight "https://github.com/thirdweb-dev/ai/blob/main/python/thirdweb-ai/src/thirdweb_ai/services/insight.py"
    click engine "https://github.com/thirdweb-dev/ai/blob/main/python/thirdweb-ai/src/thirdweb_ai/services/engine.py"
    click nebula "https://github.com/thirdweb-dev/ai/blob/main/python/thirdweb-ai/src/thirdweb_ai/services/nebula.py"
    click autogen "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/autogen"
    click coinbase "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/coinbase_agentkit"
    click goat "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/goat"
    click langchain "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/langchain"
    click llama "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/llama_index"
    click mcpAdapter "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/mcp"
    click openai "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/openai"
    click pydantic "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/pydantic_ai"
    click smolagents "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/adapters/smolagents"
    click mcp_server "https://github.com/thirdweb-dev/ai/blob/main/python/thirdweb-mcp/src/mcp.py"
    click common "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/common"
    click tools "https://github.com/thirdweb-dev/ai/tree/main/python/thirdweb-ai/src/thirdweb_ai/tools"
    click api_engine "https://github.com/thirdweb-dev/ai/blob/main/openapi/engine.json"
    click api_insight "https://github.com/thirdweb-dev/ai/blob/main/openapi/insight.json"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef service fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef adapter fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef server fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef common fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
