# inspector-apm/neuron-ai architecture

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

- Interactive diagram: https://gitdiagram.com/inspector-apm/neuron-ai
- Repository: https://github.com/inspector-apm/neuron-ai

## Overview

##### Main Components
- Agent/Core Class: At the heart, the Agent class (in src/Agent.php) provides the base behavior for agents. In addition, there is a special branch for RAG systems where the user extends the NeuronAI\RAG\RAG class.
- Providers: AI providers (e.g., Anthropics in src/Providers/Anthropic, OpenAI, Ollama) that abstract the LLM interfacing. These modules encapsulate message handling (chat, stream, etc.) through separate classes.
- Chat and Message Handling: Represented by the src/Chat directory, which includes message types (UserMessage, AssistantMessage, etc.) and chat history implementations.
- Tools: Custom task modules (src/Tools folder) are defined and extended using a tool builder pattern (with callable functions and properties) so that agents can perform concrete tasks.
- MCP Connector: In the src/MCP directory, connectors (McpConnector, StdioTransport, etc.) let you tap into MCP servers to provide tool integrations.
- RAG Components: Under src/RAG, there are several submodules:
- Data Loaders: (FileDataLoader, PdfReader, etc.) for reading documents.
- Embeddings Providers: (OpenAIEmbeddingsProvider, VoyageEmbeddingsProvider) to generate embeddings.
- Vector Stores: (MemoryVectorStore, PineconeVectorStore, ElasticsearchVectorStore, etc.) to store and retrieve embedding vectors.
- Document Splitters: For dividing texts appropriately.
- Observability & Exceptions: Additional infrastructure is present for error handling, monitoring (such as src/Observability), and event-driven architecture (the src/Events directory).

##### Relationships and Interactions
- The Agent (or RAG) acts as the central orchestrator. It communicates with the AI provider to get responses.
- The provider interfaces are implemented in several sub-modules (Anthropic, OpenAI, etc.), and they serve as adapters between the framework and the underlying LLM.
- For tool-based interactions, the Agent either directly calls a custom tool (provided in src/Tools) or obtains them via an MCP connector.
- The chat-related classes manage message states and events, saving histories as files or in-memory (e.g., FileChatHistory, InMemoryChatHistory, and related event dispatches).

##### Architectural Patterns & Design Principles
- Modularity and Extensibility: The framework is built in a way that allows users to extend the Agent class, plug in new providers, or add/override tools.
- Abstraction Layers: The use of Interfaces (e.g., AIProviderInterface, EmbeddingsProviderInterface, VectorStoreInterface) abstracts the implementation details for each component.
- Event-Driven Architecture: The src/Events directory indicates that key actions (sending and receiving messages, tool calls, etc.) prompt events which may be handled or intercepted.
- Dependency Injection & Callable Abstractions: Tools and MCP connectors demonstrate the pattern of injecting functionality (by assigning callable functions) which can be swapped or extended.

##### Relevant Technologies, Frameworks, or Libraries
- PHP 8.0+ (core language requirement)
- Composer for dependency management (composer.json)
- Integration with external APIs (e.g., Anthropic, OpenAI, Pinecone, Typesense, Elasticsearch)
- MCP server connectivity (using Node-based tools, e.g., via npx command)
- Testing using PHPUnit, as indicated by phpunit.xml.dist and tests/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Agent Functionality
    subgraph "Core Agent Functionality"
        A["Agent"]:::core
        R["RAG"]:::core
    end

    %% Language Provider Interactions
    subgraph "Language Provider Interactions"
        AP["Anthropic Provider"]:::provider
        OP["OpenAI Provider"]:::provider
        OL["Ollama Provider"]:::provider
        DS["Deepseek"]:::provider
        HC["HandleClient"]:::provider
        HT["HandleWithTools"]:::provider
        MS["Mistral"]:::provider
    end

    %% Chat and Message Handling
    subgraph "Chat and Message Handling"
        CS["Chat System"]:::chat
        MT["Message Types"]:::chat
        CH["Chat History"]:::chat
    end

    %% Tool & MCP Integrations
    subgraph "Tool & MCP Integrations"
        T["Tools"]:::integration
        MCP["MCP Connector"]:::integration
    end

    %% RAG Pipelines
    subgraph "RAG Pipelines"
        DL["Data Loaders"]:::rag
        EP["Embeddings Providers"]:::rag
        VS["Vector Stores"]:::rag
        DSpl["Document Splitters"]:::rag
        RD["RAG Document Utility"]:::rag
    end

    %% Observability & Exceptions
    subgraph "Observability & Exceptions"
        OBS["Observability"]:::support
        EXC["Exception Handling"]:::support
    end

    %% Event System
    subgraph "Event System"
        EVT["Events"]:::event
    end

    %% Relationships from Core Agent Functionality
    A -->|"callsAnthropic"| AP
    A -->|"callsOpenAI"| OP
    A -->|"callsOllama"| OL
    A -->|"callsDeepseek"| DS
    A -->|"callsHandleClient"| HC
    A -->|"callsHandleWithTools"| HT
    A -->|"callsMistral"| MS

    A -->|"sendsMsg"| CS
    CS -->|"displaysMsg"| MT
    CS -->|"storesMsg"| CH

    A -->|"invokesTool"| T
    T -->|"usesMCP"| MCP

    A -->|"executesRAG"| R
    R -->|"feedsDocs"| DL
    DL -->|"processEmb"| EP
    EP -->|"storesVectors"| VS
    VS -->|"splitsDocs"| DSpl
    DSpl -->|"preparesDoc"| RD

    A -->|"monitors"| OBS
    A -->|"handlesErr"| EXC
    A -->|"triggersEvt"| EVT

    %% Styles
    classDef core fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef provider fill:#ABEBC6,stroke:#000,stroke-width:1px;
    classDef chat fill:#F9E79F,stroke:#000,stroke-width:1px;
    classDef integration fill:#F5CBA7,stroke:#000,stroke-width:1px;
    classDef rag fill:#D7BDE2,stroke:#000,stroke-width:1px;
    classDef support fill:#FADBD8,stroke:#000,stroke-width:1px;
    classDef event fill:#D5F5E3,stroke:#000,stroke-width:1px;

    %% Click Events for Core Agent Functionality
    click A "https://github.com/inspector-apm/neuron-ai/blob/main/src/Agent.php"
    click R "https://github.com/inspector-apm/neuron-ai/blob/main/src/RAG/RAG.php"

    %% Click Events for Providers
    click AP "https://github.com/inspector-apm/neuron-ai/tree/main/src/Providers/Anthropic"
    click OP "https://github.com/inspector-apm/neuron-ai/tree/main/src/Providers/OpenAI"
    click OL "https://github.com/inspector-apm/neuron-ai/tree/main/src/Providers/Ollama"
    click DS "https://github.com/inspector-apm/neuron-ai/blob/main/src/Providers/Deepseek.php"
    click HC "https://github.com/inspector-apm/neuron-ai/blob/main/src/Providers/HandleClient.php"
    click HT "https://github.com/inspector-apm/neuron-ai/blob/main/src/Providers/HandleWithTools.php"
    click MS "https://github.com/inspector-apm/neuron-ai/blob/main/src/Providers/Mistral.php"

    %% Click Events for Chat and Message Handling
    click CS "https://github.com/inspector-apm/neuron-ai/tree/main/src/Chat"
    click MT "https://github.com/inspector-apm/neuron-ai/tree/main/src/Chat/Messages"
    click CH "https://github.com/inspector-apm/neuron-ai/tree/main/src/Chat/History"

    %% Click Events for Tools & MCP
    click T "https://github.com/inspector-apm/neuron-ai/tree/main/src/Tools"
    click MCP "https://github.com/inspector-apm/neuron-ai/tree/main/src/MCP"

    %% Click Events for RAG Pipelines
    click DL "https://github.com/inspector-apm/neuron-ai/tree/main/src/RAG/DataLoader"
    click EP "https://github.com/inspector-apm/neuron-ai/tree/main/src/RAG/Embeddings"
    click VS "https://github.com/inspector-apm/neuron-ai/tree/main/src/RAG/VectorStore"
    click DSpl "https://github.com/inspector-apm/neuron-ai/blob/main/src/RAG/Splitters/DocumentSplitter.php"
    click RD "https://github.com/inspector-apm/neuron-ai/blob/main/src/RAG/Document.php"

    %% Click Events for Observability & Exceptions
    click OBS "https://github.com/inspector-apm/neuron-ai/tree/main/src/Observability"
    click EXC "https://github.com/inspector-apm/neuron-ai/tree/main/src/Exceptions"

    %% Click Event for Events
    click EVT "https://github.com/inspector-apm/neuron-ai/tree/main/src/Events"
```
