How inspector-apm/neuron-ai works
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/