PHPackages                             ermirshehaj/neuron-ai - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. ermirshehaj/neuron-ai

ActiveLibrary[Framework](/categories/framework)

ermirshehaj/neuron-ai
=====================

PHP AI Framework with built-in observability.

118PHP

Since May 14Pushed 1y agoCompare

[ Source](https://github.com/ermiri/neuron-ai)[ Packagist](https://packagist.org/packages/ermirshehaj/neuron-ai)[ RSS](/packages/ermirshehaj-neuron-ai/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

[![Latest Stable Version](https://camo.githubusercontent.com/9bdfbdd47827b9691be6b64ac8ca92d86fb97f8727a1aa4f9e90f18ac78b50b7/68747470733a2f2f706f7365722e707567782e6f72672f696e73706563746f722d61706d2f6e6575726f6e2d61692f762f737461626c65)](https://packagist.org/packages/inspector-apm/neuron-ai)[![License](https://camo.githubusercontent.com/20dca889903efe0b6bafa5078e0f6c94f66a2a283b1c07cdbe95d082a4c5855d/68747470733a2f2f706f7365722e707567782e6f72672f696e73706563746f722d61706d2f6e6575726f6e2d61692f6c6963656e7365)](//packagist.org/packages/inspector-apm/neuron-ai)

> Before moving on, support the community giving a GitHub star ⭐️. Thank you!

[![](./docs/img/neuron-ai-php-framework.png)](./docs/img/neuron-ai-php-framework.png)

Requirements
------------

[](#requirements)

- PHP: ^8.1

Official documentation
----------------------

[](#official-documentation)

**[Go to the official documentation](https://neuron.inspector.dev/)**

Forum
-----

[](#forum)

You can post questions and feedback on the [Inspector Forum](https://github.com/inspector-apm/neuron-ai/discussions).

Examples
--------

[](#examples)

- [Install](#install)
- [Create an Agent](#create)
- [Talk to the Agent](#talk)
- [Supported LLM Providers](#providers)
- [Tools & Function Calls](#tools)
- [MCP server connector](#mcp)
- [Implement RAG systems](#rag)
- [Structured Output](#structured)
- [Observability](#observability)
- [Official Documentation](#documentation)

Install
-------

[](#install)

Install the latest version of the package:

```
composer require inspector-apm/neuron-ai

```

Create an Agent
---------------

[](#create-an-agent)

Neuron provides you with the Agent class you can extend to inherit the main features of the framework, and create fully functional agents. This class automatically manages some advanced mechanisms for you such as memory, tools and function calls, up to the RAG systems. You can go deeper into these aspects in the [documentation](https://docs.neuron-ai.dev). In the meantime, let's create the first agent, extending the `NeuronAI\Agent` class:

```
use NeuronAI\Agent;
use NeuronAI\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class YouTubeAgent extends Agent
{
    public function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    public function instructions(): string
    {
        return new SystemPrompt(
            background: ["You are an AI Agent specialized in writing YouTube video summaries."],
            steps: [
                "Get the url of a YouTube video, or ask the user to provide one.",
                "Use the tools you have available to retrieve the transcription of the video.",
                "Write the summary.",
            ],
            output: [
                "Write a summary in a paragraph without using lists. Use just fluent text.",
                "After the summary add a list of three sentences as the three most important take away from the video.",
            ]
        );
    }
}
```

The `SystemPrompt` class is designed to take your base instructions and build a consistent prompt for the underlying model reducing the effort for prompt engineering.

Talk to the Agent
-----------------

[](#talk-to-the-agent)

Send a prompt to the agent to get a response from the underlying LLM:

```
$agent = YouTubeAgent::make();

$response = $agent->run(new UserMessage("Hi, I'm Valerio. Who are you?"));
echo $response->getContent();
// I'm a friendly YouTube assistant to help you summarize videos.

$response = $agent->run(
    new UserMessage("Do you know my name?")
);
echo $response->getContent();
// Your name is Valerio, as you said in your introduction.
```

As 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).

Supported LLM Providers
-----------------------

[](#supported-llm-providers)

With Neuron you can switch between LLM providers with just one line of code, without any impact on your agent implementation. Supported providers:

- Anthropic
- Ollama (also available as an [embeddings provider](https://docs.neuron-ai.dev/components/embeddings-provider#ollama))
- OpenAI (also available as an [embeddings provider](https://docs.neuron-ai.dev/components/embeddings-provider#openai))
- Gemini

Tools & Function Calls
--------------------------

[](#tools--function-calls)

You can add the ability to perform concrete tasks to your Agent with an array of `Tool`:

```
use NeuronAI\Agent;
use NeuronAI\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class YouTubeAgent extends Agent
{
    public function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    public function instructions(): string
    {
        return new SystemPrompt(
            background: ["You are an AI Agent specialized in writing YouTube video summaries."],
            steps: [
                "Get the url of a YouTube video, or ask the user to provide one.",
                "Use the tools you have available to retrieve the transcription of the video.",
                "Write the summary.",
            ],
            output: [
                "Write a summary in a paragraph without using lists. Use just fluent text.",
                "After the summary add a list of three sentences as the three most important take away from the video.",
            ]
        );
    }

    public function tools(): array
    {
        return [
            Tool::make(
                'get_transcription',
                'Retrieve the transcription of a youtube video.',
            )->addProperty(
                new ToolProperty(
                    name: 'video_url',
                    type: 'string',
                    description: 'The URL of the YouTube video.',
                    required: true
                )
            )->setCallable(function (string $video_url) {
                // ... retrieve the video transcription
            })
        ];
    }
}
```

Learn more about Tools in the [documentation](https://docs.neuron-ai.dev/tools-and-function-calls).

MCP server connector
--------------------

[](#mcp-server-connector)

Instead of implementing tools manually, you can connect tools exposed by an MCP server with the `McpConnector` component:

```
use NeuronAI\Agent;
use NeuronAI\MCP\McpConnector;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class YouTubeAgent extends Agent
{
    public function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    public function instructions(): string
    {
        return new SystemPrompt(
            background: ["Act as an expert of SEO (Search Engine Optimization)."]
            steps: [
                "Analyze a text of an article.",
                "Provide suggestions on how the content can be improved to get a better rank on Google search."
            ],
            output: ["Structure your analysis in sections. One for each suggestion."]
        );
    }

    public function tools(): array
    {
        return [
            // Connect an MCP server
            ...McpConnector::make([
                'command' => 'npx',
                'args' => ['-y', '@modelcontextprotocol/server-everything'],
            ])->tools(),

            // Implement your custom tools
            Tool::make(
                'get_transcription',
                'Retrieve the transcription of a youtube video.',
            )->addProperty(
                new ToolProperty(
                    name: 'video_url',
                    type: 'string',
                    description: 'The URL of the YouTube video.',
                    required: true
                )
            )->setCallable(function (string $video_url) {
                // ... retrieve the video transcription
            })
        ];
    }
}
```

Learn more about MCP connector in the [documentation](https://docs.neuron-ai.dev/advanced/mcp-servers-connection).

Implement RAG systems
---------------------

[](#implement-rag-systems)

For RAG use case, you must extend the `NeuronAI\RAG\RAG` class instead of the default Agent class.

To create a RAG you need to attach some additional components other than the AI provider, such as a `vector store`, and an `embeddings provider`.

Here is an example of a RAG implementation:

```
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\VoyageEmbeddingProvider;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\PineconeVectoreStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class MyChatBot extends RAG
{
    public function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    public function embeddings(): EmbeddingsProviderInterface
    {
        return new VoyageEmbeddingProvider(
            key: 'VOYAGE_API_KEY',
            model: 'VOYAGE_MODEL'
        );
    }

    public function vectorStore(): VectorStoreInterface
    {
        return new PineconeVectoreStore(
            key: 'PINECONE_API_KEY',
            indexUrl: 'PINECONE_INDEX_URL'
        );
    }
}
```

Learn more about RAG in the [documentation](https://docs.neuron-ai.dev/rag).

Structured Output
-----------------

[](#structured-output)

For many applications, such as chatbots, Agents need to respond to users directly in natural language. However, there are scenarios where we need Agents to understand natural language, but output in a structured format.

One common use-case is extracting data from text to insert into a database or use with some other downstream system. This guide covers a few strategies for getting structured outputs from the agent.

```
use NeuronAI\StructuredOutput\SchemaProperty;

// Define the output structure with a PHP class, including validation constraints.
class Person
{
    #[SchemaProperty(description: 'The user name')]
    public string $name;

    #[SchemaProperty(description: 'What the user love to eat')]
    public string $preference;
}

// Talk to the agent requiring the structured output
$person = MyAgent::make()->structured(
    new UserMessage("I'm John and I like pizza!"),
    Person::class
);

echo $person->name ' like '.$person->preference;
// John like pizza
```

Learn more about Structured Output on the [documentation](https://docs.neuron-ai.dev/advanced/structured-output).

Observability
-------------

[](#observability)

Neuron offers a built-in integration with [Inspector.dev](https://inspector.dev) to monitor the performance of your agents and detect unexpected errors in real time.

You have to install the Inspector package based on your development environment. We provide integration packages for [PHP](https://github.com/inspector-apm/inspector-php), [Laravel](https://github.com/inspector-apm/inspector-laravel), [Symfony](https://github.com/inspector-apm/inspector-symfony), [CodeIgniter](https://github.com/inspector-apm/inspector-codeigniter), [Drupal](https://git.drupalcode.org/project/inspector_monitoring).

Attach the `AgentMonitoring` component to the agent to monitor the internal execution timeline in the Inspector dashboard. If the agent fires an error, you will be alerted in real-time. You can connect several notification channels like email, slack, discord, telegram, and more. Here is a code example in a legacy PHP script:

```
new NeuronAI\Observability\AgentMonitoring;

// The Inspector instance in your application
$inspector = new \Inspector\Inspector(
    new Configuration('YOUR-INGESTION-KEY')
);

// Attach monitoring to the Agent
$response = MyAgent::make()
    ->observe(
        new AgentMonitoring($inspector)
    )
    ->chat(...);
```

[![](./docs/img/neuron-observability.png)](./docs/img/neuron-observability.png)

> If you use a framework like Laravel, Symfony, or CodeIgniter, the connection is even easier, since you already have the Inspector instance in the container.

Learn more about Observability in the [documentation](https://docs.neuron-ai.dev/advanced/observability).

Official documentation
----------------------

[](#official-documentation-1)

[Go to the official documentation](https://neuron.inspector.dev/)**

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance37

Infrequent updates — may be unmaintained

Popularity8

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity15

Early-stage or recently created project

 Bus Factor1

Top contributor holds 94.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/98a677cf9f03b06c890523ed57bf5b31edc9d59890da0f3fa47c277a11b95ded?d=identicon)[ermiri](/maintainers/ermiri)

---

Top Contributors

[![ilvalerione](https://avatars.githubusercontent.com/u/13559278?v=4)](https://github.com/ilvalerione "ilvalerione (545 commits)")[![asterixcapri](https://avatars.githubusercontent.com/u/374856?v=4)](https://github.com/asterixcapri "asterixcapri (16 commits)")[![andrewbroberg](https://avatars.githubusercontent.com/u/7610285?v=4)](https://github.com/andrewbroberg "andrewbroberg (3 commits)")[![JanneDeVos](https://avatars.githubusercontent.com/u/75279277?v=4)](https://github.com/JanneDeVos "JanneDeVos (3 commits)")[![Maef](https://avatars.githubusercontent.com/u/7213542?v=4)](https://github.com/Maef "Maef (3 commits)")[![ermiri](https://avatars.githubusercontent.com/u/5099870?v=4)](https://github.com/ermiri "ermiri (2 commits)")[![iztok](https://avatars.githubusercontent.com/u/422789?v=4)](https://github.com/iztok "iztok (2 commits)")

### Embed Badge

![Health badge](/badges/ermirshehaj-neuron-ai/health.svg)

```
[![Health](https://phpackages.com/badges/ermirshehaj-neuron-ai/health.svg)](https://phpackages.com/packages/ermirshehaj-neuron-ai)
```

###  Alternatives

[laravel/telescope

An elegant debug assistant for the Laravel framework.

5.2k67.8M192](/packages/laravel-telescope)[spiral/roadrunner

RoadRunner: High-performance PHP application server and process manager written in Go and powered with plugins

8.4k12.2M84](/packages/spiral-roadrunner)[nolimits4web/swiper

Most modern mobile touch slider and framework with hardware accelerated transitions

41.8k177.2k1](/packages/nolimits4web-swiper)[laravel/dusk

Laravel Dusk provides simple end-to-end testing and browser automation.

1.9k36.7M259](/packages/laravel-dusk)[laravel/prompts

Add beautiful and user-friendly forms to your command-line applications.

708181.8M596](/packages/laravel-prompts)[cakephp/chronos

A simple API extension for DateTime.

1.4k47.7M121](/packages/cakephp-chronos)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)