{"id":27487228,"url":"https://github.com/inspector-apm/neuron-ai","last_synced_at":"2025-06-21T07:10:30.123Z","repository":{"id":280303965,"uuid":"941562247","full_name":"inspector-apm/neuron-ai","owner":"inspector-apm","description":"The PHP Agent Development Kit - powered by Inspector.dev","archived":false,"fork":false,"pushed_at":"2025-06-14T21:34:27.000Z","size":14343,"stargazers_count":718,"open_issues_count":7,"forks_count":59,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-06-14T22:31:10.918Z","etag":null,"topics":["agent","agentic-ai","agentic-framework","agents","ai","llm","llm-inference","llms","php","vector-database"],"latest_commit_sha":null,"homepage":"https://neuron-ai.dev","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inspector-apm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-02T15:35:21.000Z","updated_at":"2025-06-14T21:33:52.000Z","dependencies_parsed_at":"2025-03-02T16:32:54.176Z","dependency_job_id":"5fd412de-c7d7-40e5-8b59-8c7c80871d15","html_url":"https://github.com/inspector-apm/neuron-ai","commit_stats":null,"previous_names":["inspector-apm/neuron-ai"],"tags_count":157,"template":false,"template_full_name":null,"purl":"pkg:github/inspector-apm/neuron-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspector-apm%2Fneuron-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspector-apm%2Fneuron-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspector-apm%2Fneuron-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspector-apm%2Fneuron-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inspector-apm","download_url":"https://codeload.github.com/inspector-apm/neuron-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspector-apm%2Fneuron-ai/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260996843,"owners_count":23094775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentic-ai","agentic-framework","agents","ai","llm","llm-inference","llms","php","vector-database"],"created_at":"2025-04-16T19:01:15.234Z","updated_at":"2025-06-21T07:10:25.103Z","avatar_url":"https://github.com/inspector-apm.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"[![Latest Stable Version](https://poser.pugx.org/inspector-apm/neuron-ai/v/stable)](https://packagist.org/packages/inspector-apm/neuron-ai)\n[![License](https://poser.pugx.org/inspector-apm/neuron-ai/license)](//packagist.org/packages/inspector-apm/neuron-ai)\n\n\u003e Before moving on, support the community giving a GitHub star ⭐️. Thank you!\n\n![](./docs/img/neuron-ai-php-framework.png)\n\n## Requirements\n\n- PHP: ^8.1\n\n## Official documentation\n\n**[Go to the official documentation](https://neuron.inspector.dev/)**\n\n## Examples\n\n- [Install](#install)\n- [Create an Agent](#create)\n- [Talk to the Agent](#talk)\n- [Supported LLM Providers](#providers)\n- [Tools \u0026 Function Calls](#tools)\n- [MCP server connector](#mcp)\n- [Implement RAG systems](#rag)\n- [Structured Output](#structured)\n- [Official Documentation](#documentation)\n\n\u003ca name=\"install\"\u003e\n\n## Install\n\nInstall the latest version of the package:\n\n```\ncomposer require inspector-apm/neuron-ai\n```\n\n\u003ca name=\"create\"\u003e\n\n## Create an Agent\n\nNeuron provides you with the Agent class you can extend to inherit the main features of the framework,\nand create fully functional agents. This class automatically manages some advanced mechanisms for you such as memory,\ntools and function calls, up to the RAG systems. You can go deeper into these aspects in the [documentation](https://docs.neuron-ai.dev).\nIn the meantime, let's create the first agent, extending the `NeuronAI\\Agent` class:\n\n```php\nuse NeuronAI\\Agent;\nuse NeuronAI\\SystemPrompt;\nuse NeuronAI\\Providers\\AIProviderInterface;\nuse NeuronAI\\Providers\\Anthropic\\Anthropic;\n\nclass YouTubeAgent extends Agent\n{\n    public function provider(): AIProviderInterface\n    {\n        return new Anthropic(\n            key: 'ANTHROPIC_API_KEY',\n            model: 'ANTHROPIC_MODEL',\n        );\n    }\n\n    public function instructions(): string\n    {\n        return new SystemPrompt(\n            background: [\"You are an AI Agent specialized in writing YouTube video summaries.\"],\n            steps: [\n                \"Get the url of a YouTube video, or ask the user to provide one.\",\n                \"Use the tools you have available to retrieve the transcription of the video.\",\n                \"Write the summary.\",\n            ],\n            output: [\n                \"Write a summary in a paragraph without using lists. Use just fluent text.\",\n                \"After the summary add a list of three sentences as the three most important take away from the video.\",\n            ]\n        );\n    }\n}\n```\n\nThe `SystemPrompt` class is designed to take your base instructions and build a consistent prompt for the underlying model\nreducing the effort for prompt engineering.\n\n\u003ca name=\"talk\"\u003e\n\n## Talk to the Agent\n\nSend a prompt to the agent to get a response from the underlying LLM:\n\n```php\n$agent = YouTubeAgent::make();\n\n$response = $agent-\u003erun(new UserMessage(\"Hi, I'm Valerio. Who are you?\"));\necho $response-\u003egetContent();\n// I'm a friendly YouTube assistant to help you summarize videos.\n\n\n$response = $agent-\u003erun(\n    new UserMessage(\"Do you know my name?\")\n);\necho $response-\u003egetContent();\n// Your name is Valerio, as you said in your introduction.\n```\n\nAs you can see in the example above, the Agent automatically has memory of the ongoing conversation. Learn more about memory in the [documentation](https://docs.neuron-ai.dev/chat-history-and-memory).\n\n\u003ca name=\"providers\"\u003e\n\n## Supported LLM Providers\n\nWith Neuron you can switch between LLM providers with just one line of code, without any impact on your agent implementation.\nSupported providers:\n\n- Anthropic\n- Ollama (also available as an [embeddings provider](https://docs.neuron-ai.dev/components/embeddings-provider#ollama))\n- OpenAI\n- Mistral\n- Deepseek\n\n\u003ca name=\"tools\"\u003e\n\n## Tools \u0026 Function Calls\n\nYou can add the ability to perform concrete tasks to your Agent with an array of `Tool`:\n\n```php\nuse NeuronAI\\Agent;\nuse NeuronAI\\SystemPrompt;\nuse NeuronAI\\Providers\\AIProviderInterface;\nuse NeuronAI\\Providers\\Anthropic\\Anthropic;\nuse NeuronAI\\Tools\\Tool;\nuse NeuronAI\\Tools\\ToolProperty;\n\nclass YouTubeAgent extends Agent\n{\n    public function provider(): AIProviderInterface\n    {\n        return new Anthropic(\n            key: 'ANTHROPIC_API_KEY',\n            model: 'ANTHROPIC_MODEL',\n        );\n    }\n\n    public function instructions(): string\n    {\n        return new SystemPrompt(\n            background: [\"You are an AI Agent specialized in writing YouTube video summaries.\"],\n            steps: [\n                \"Get the url of a YouTube video, or ask the user to provide one.\",\n                \"Use the tools you have available to retrieve the transcription of the video.\",\n                \"Write the summary.\",\n            ],\n            output: [\n                \"Write a summary in a paragraph without using lists. Use just fluent text.\",\n                \"After the summary add a list of three sentences as the three most important take away from the video.\",\n            ]\n        );\n    }\n\n    public function tools(): array\n    {\n        return [\n            Tool::make(\n                'get_transcription',\n                'Retrieve the transcription of a youtube video.',\n            )-\u003eaddProperty(\n                new ToolProperty(\n                    name: 'video_url',\n                    type: 'string',\n                    description: 'The URL of the YouTube video.',\n                    required: true\n                )\n            )-\u003esetCallable(function (string $video_url) {\n                // ... retrieve the video transcription\n            })\n        ];\n    }\n}\n```\n\nLearn more about Tools on the [documentation](https://docs.neuron-ai.dev/tools-and-function-calls).\n\n\u003ca name=\"mcp\"\u003e\n\n## MCP server connector\n\nInstead of implementing tools manually, you can connect tools exposed by an MCP server with the `McpConnector` component:\n\n```php\nuse NeuronAI\\Agent;\nuse NeuronAI\\MCP\\McpConnector;\nuse NeuronAI\\Providers\\AIProviderInterface;\nuse NeuronAI\\Providers\\Anthropic\\Anthropic;\nuse NeuronAI\\Tools\\Tool;\nuse NeuronAI\\Tools\\ToolProperty;\n\nclass SEOAgent extends Agent\n{\n    public function provider(): AIProviderInterface\n    {\n        return new Anthropic(\n            key: 'ANTHROPIC_API_KEY',\n            model: 'ANTHROPIC_MODEL',\n        );\n    }\n\n    public function instructions(): string\n    {\n        return new SystemPrompt(\n            background: [\"Act as an expert of SEO (Search Engine Optimization).\"]\n            steps: [\n                \"Analyze a text of an article.\",\n                \"Provide suggestions on how the content can be improved to get a better rank on Google search.\"\n            ],\n            output: [\"Structure your analysis in sections. One for each suggestion.\"]\n        );\n    }\n\n    public function tools(): array\n    {\n        return [\n            // Connect an MCP server\n            ...McpConnector::make([\n                'command' =\u003e 'npx',\n                'args' =\u003e ['-y', '@modelcontextprotocol/server-everything'],\n            ])-\u003etools(),\n\n            // Implement your custom tools\n            Tool::make(\n                'get_transcription',\n                'Retrieve the transcription of a youtube video.',\n            )-\u003eaddProperty(\n                new ToolProperty(\n                    name: 'video_url',\n                    type: 'string',\n                    description: 'The URL of the YouTube video.',\n                    required: true\n                )\n            )-\u003esetCallable(function (string $video_url) {\n                // ... retrieve the video transcription\n            })\n        ];\n    }\n}\n```\n\nLearn more about MCP connector on the [documentation](https://docs.neuron-ai.dev/advanced/mcp-servers-connection).\n\n\u003ca name=\"rag\"\u003e\n\n## Implement RAG systems\n\nFor RAG use case, you must extend the `NeuronAI\\RAG\\RAG` class instead of the default Agent class.\n\nTo create a RAG you need to attach some additional components other than the AI provider, such as a `vector store`,\nand an `embeddings provider`.\n\nHere is an example of a RAG implementation:\n\n```php\nuse NeuronAI\\Providers\\AIProviderInterface;\nuse NeuronAI\\Providers\\Anthropic\\Anthropic;\nuse NeuronAI\\RAG\\Embeddings\\EmbeddingsProviderInterface;\nuse NeuronAI\\RAG\\Embeddings\\VoyageEmbeddingProvider;\nuse NeuronAI\\RAG\\RAG;\nuse NeuronAI\\RAG\\VectorStore\\PineconeVectoreStore;\nuse NeuronAI\\RAG\\VectorStore\\VectorStoreInterface;\n\nclass MyChatBot extends RAG\n{\n    public function provider(): AIProviderInterface\n    {\n        return new Anthropic(\n            key: 'ANTHROPIC_API_KEY',\n            model: 'ANTHROPIC_MODEL',\n        );\n    }\n\n    public function embeddings(): EmbeddingsProviderInterface\n    {\n        return new VoyageEmbeddingProvider(\n            key: 'VOYAGE_API_KEY',\n            model: 'VOYAGE_MODEL'\n        );\n    }\n\n    public function vectorStore(): VectorStoreInterface\n    {\n        return new PineconeVectoreStore(\n            key: 'PINECONE_API_KEY',\n            indexUrl: 'PINECONE_INDEX_URL'\n        );\n    }\n}\n```\n\nLearn more about RAG on the [documentation](https://docs.neuron-ai.dev/rag).\n\n\u003ca name=\"structured\"\u003e\n\n## Structured Output\nFor many applications, such as chatbots, Agents need to respond to users directly in natural language.\nHowever, there are scenarios where we need Agents to understand natural language, but output in a structured format.\n\nOne common use-case is extracting data from text to insert into a database or use with some other downstream system.\nThis guide covers a few strategies for getting structured outputs from the agent.\n\n```php\nuse NeuronAI\\StructuredOutput\\SchemaProperty;\n\n// Define the output structure with a PHP class, including validation constraints.\nclass Person\n{\n    #[SchemaProperty(description: 'The user name')]\n    public string $name;\n\n    #[SchemaProperty(description: 'What the user love to eat')]\n    public string $preference;\n}\n\n\n// Talk to the agent requiring the structured output\n$person = MyAgent::make()-\u003estructured(\n    new UserMessage(\"I'm John and I like pizza!\"),\n    Person::class\n);\n\necho $person-\u003ename ' like '.$person-\u003epreference;\n// John like pizza\n```\n\nLearn more about Structured Output on the [documentation](https://docs.neuron-ai.dev/advanced/structured-output).\n\n\u003ca name=\"documentation\"\u003e\n\n## Official documentation\n\n**[Go to the official documentation](https://neuron.inspector.dev/)**\n\n## Contributing\n\nWe encourage you to contribute to the development of Neuron AI Framework!\nPlease check out the [Contribution Guidelines](CONTRIBUTING.md) about how to proceed. Join us!\n\n## LICENSE\n\nThis bundle is licensed under the [MIT](LICENSE) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finspector-apm%2Fneuron-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finspector-apm%2Fneuron-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finspector-apm%2Fneuron-ai/lists"}