# nvidia/agentiq architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia/agentiq
- Repository: https://github.com/nvidia/agentiq

## Overview

##### Main Components
- Plugins and Extensions: The “packages” directory holds provider-specific plugins (e.g., agentiq_langchain, agentiq_llama_index, agentiq_mem0ai, agentiq_semantic_kernel, etc.). These extend the core capabilities by providing integrations with different frameworks and tools.
- Evaluation, Profiling, and Observability: Within the “src/aiq/eval”, “src/aiq/profiler”, and “src/aiq/observability” directories you have dedicated code for profiling workflows, evaluating results, and monitoring operations (including OpenTelemetry integration).
- Front-End and API Interfaces: The “src/aiq/front_ends” contain the FastAPI server, console, and other interfaces. This layer exposes the system for CLI commands or web-based interactions.
- Data Models and Registry Handlers: Directories like “src/aiq/data_models” and “src/aiq/registry_handlers” encapsulate data definitions and interactions with external package registries (both local and remote, e.g., PyPI or REST endpoints).

##### Component Relationships and Interactions
- User Interaction Layer: Start with the UI or CLI. Users interact through the CLI (the “src/aiq/cli” module) or via the FastAPI front-end provided in “src/aiq/front_ends/fastapi”, which accepts workflow configurations and inputs.
- Workflow Orchestration: The CLI commands parse configuration files (like the workflow.yaml shown in the README) and trigger workflows. The “builder” components are responsible for constructing and coordinating the execution of agent workflows.
- Evaluation and Observability: The evaluator and profiler components monitor the performance of each workflow step (tracking token usage, timing, etc.) and report to external observability tools (using OpenTelemetry support).
- Repository and Plugin Management: The registry handlers manage the registration, discovery, and publication of workflows, agents, and plugins. This is how the system self-updates or shares components.
- CI/CD and Deployment: The presence of a “.devcontainer”, “ci”, and Docker configurations indicate that the system is designed to be deployed both locally and in containers. Include these aspects to show the environmental and deployment perspectives.

##### Architectural Patterns and Technologies
- Plugin-Based Extensibility: Emphasize the decoupling introduced by plugins (in the “packages” directory) and how they interface with the main library.
- Modular and Composable Design: Show that each workflow is built as a series of function calls that can be reused and repurposed. Reflect that in the segmentation between agents, tools, and workflow builders.
- Observability and Profiling: Underline that the system has built-in methods for tracing, profiling, and collecting metrics.
- Multi-Interface Support: Note the separation between command line usage, API-based interactions (FastAPI), and potential UI components.

##### Elements
- Annotations: Where needed, annotate the use of key technologies (Python, uv for virtual environments, Docker, FastAPI, etc.) and reference some key modules (for example, “src/aiq/agent/react_agent” for composable agent-driven workflows).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI Module"]:::cli
        FASTAPI["FastAPI Interface"]:::api
    end

    %% Workflow Engine Layer
    subgraph "Workflow Engine Layer"
        BUILDER["Workflow Builder"]:::builder
        RUNTIME["Runtime Module"]:::runtime
        subgraph "Agent Modules"
            REACT["React Agent"]:::agent
            REASONING["Reasoning Agent"]:::agent
            TOOLCALL["Tool Calling Agent"]:::agent
        end
    end

    %% Plugin & Integration Layer
    subgraph "Plugin & Integration Layer"
        PLUGINS["Plugins Directory"]:::plugin
    end

    %% Evaluation & Observability Layer
    subgraph "Evaluation & Observability Layer"
        EVAL["Evaluation"]:::eval
        PROFILER["Profiling"]:::profiler
        OBS["Observability"]:::observability
    end

    %% Data & Registry Layer
    subgraph "Data & Registry Layer"
        DATA["Data Models"]:::data
        REG["Registry Handlers"]:::registry
    end

    %% Deployment & CI/CD Layer
    subgraph "Deployment & CI/CD Layer"
        DEVCONTAINER["Development Container"]:::deploy
        CI["CI Scripts"]:::deploy
    end

    %% Connections: User Interface to Workflow Engine
    CLI -->|"triggers"| BUILDER
    FASTAPI -->|"triggers"| BUILDER

    %% Connections: Workflow orchestration and agent execution
    BUILDER -->|"orchestrates"| RUNTIME
    BUILDER -->|"orchestrates"| REACT
    BUILDER -->|"orchestrates"| REASONING
    BUILDER -->|"orchestrates"| TOOLCALL

    %% Connections: Agent Modules interacting with Plugins
    REACT -->|"uses"| PLUGINS
    REASONING -->|"uses"| PLUGINS
    TOOLCALL -->|"uses"| PLUGINS

    %% Connections: Monitoring and Observability
    BUILDER -->|"monitored_by"| EVAL
    RUNTIME -->|"monitored_by"| PROFILER
    RUNTIME -->|"monitored_by"| OBS

    %% Connections: Data and Registry support
    DATA -->|"supplies"| BUILDER
    REG -->|"supplies"| BUILDER

    %% Connections: Deployment
    BUILDER -->|"deployed_with"| DEVCONTAINER
    BUILDER -->|"deployed_with"| CI

    %% Click Events
    click REACT "https://github.com/nvidia/agentiq/tree/develop/src/aiq/agent/react_agent"
    click REASONING "https://github.com/nvidia/agentiq/tree/develop/src/aiq/agent/reasoning_agent"
    click TOOLCALL "https://github.com/nvidia/agentiq/tree/develop/src/aiq/agent/tool_calling_agent"
    click BUILDER "https://github.com/nvidia/agentiq/tree/develop/src/aiq/builder"
    click RUNTIME "https://github.com/nvidia/agentiq/tree/develop/src/aiq/runtime"
    click CLI "https://github.com/nvidia/agentiq/tree/develop/src/aiq/cli"
    click PLUGINS "https://github.com/nvidia/agentiq/tree/develop/packages"
    click EVAL "https://github.com/nvidia/agentiq/tree/develop/src/aiq/eval"
    click PROFILER "https://github.com/nvidia/agentiq/tree/develop/src/aiq/profiler"
    click OBS "https://github.com/nvidia/agentiq/tree/develop/src/aiq/observability"
    click FASTAPI "https://github.com/nvidia/agentiq/tree/develop/src/aiq/front_ends/fastapi"
    click DATA "https://github.com/nvidia/agentiq/tree/develop/src/aiq/data_models"
    click REG "https://github.com/nvidia/agentiq/tree/develop/src/aiq/registry_handlers"
    click DEVCONTAINER "https://github.com/nvidia/agentiq/blob/develop/.devcontainer"
    click CI "https://github.com/nvidia/agentiq/tree/develop/ci"

    %% Styles
    classDef cli fill:#E3F2FD,stroke:#0D47A1,stroke-width:2px;
    classDef api fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef builder fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef runtime fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef agent fill:#FFECB3,stroke:#F57F17,stroke-width:2px;
    classDef plugin fill:#FFE0B2,stroke:#E64A19,stroke-width:2px;
    classDef eval fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef profiler fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef observability fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef data fill:#F0F4C3,stroke:#9E9D24,stroke-width:2px;
    classDef registry fill:#F0F4C3,stroke:#9E9D24,stroke-width:2px;
    classDef deploy fill:#CFD8DC,stroke:#455A64,stroke-width:2px;
```
