Redirected from /inspector-apm/neuron-ai
Neuron AI

https://github.com/neuron-core/neuron-ai
Admin
Neuron AI is a PHP framework designed for creating and orchestrating AI Agents, providing tools for...
Tokens:51,877
Snippets:609
Trust Score:7
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start development services

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/README.md

Use Docker Compose to spin up all services required by the CI environment.

```bash
# Start all services
docker compose up -d
```

--------------------------------

### Create a Basic Workflow in PHP

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-workflow-architect/SKILL.md

Instantiate a `Workflow` with a `WorkflowState` and add nodes. The `start()` method returns a handler to run the workflow.

```php
use NeuronAI\Workflow\Workflow;
use NeuronAI\Workflow\WorkflowState;
use NeuronAI\Workflow\StartEvent;
use NeuronAI\Workflow\StopEvent;

$state = new WorkflowState([
    'input' => $userData,
]);

$workflow = Workflow::make($state)
    ->addNodes([
        new ValidationNode(),
        new ProcessingNode(),
        new OutputNode(),
    ]);

$handler = $workflow->start();
$finalState = $handler->run();
$result = $finalState->get('result');
```

--------------------------------

### Toolkit Filtering Examples

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Shows how to control which tools are exposed from a toolkit using exclude(), only(), and with() methods for dynamic configuration.

```php
// Exclude specific tools
...MySQLToolkit::make($pdo)
    ->exclude([MySQLWriteTool::class]),

// Include only specific tools
...MySQLToolkit::make($pdo)
    ->only([MySQLSchemaTool::class, MySQLSelectTool::class]),

// Configure tools dynamically
...MyToolkit::make()
    ->with(ExpensiveTool::class, function (Tool $tool): Tool {
        $tool->setMaxRuns(1);  // Limit expensive operations
        return $tool;
    }),
```

--------------------------------

### Run test suite

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/README.md

Install dependencies and execute the PHPUnit test suite within the Docker container.

```bash
# Install dependencies and run tests
docker compose run --rm php composer update --prefer-stable
docker compose run --rm php vendor/bin/phpunit
```

--------------------------------

### Install Neuron AI

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/README.md

Use Composer to install the latest version of the Neuron AI package.

```bash
composer require neuron-core/neuron-ai
```

--------------------------------

### AgentJudge with Few-Shot Examples

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Enhance AgentJudge evaluations by providing few-shot examples for calibration. This helps the AI agent understand the desired output format and scoring for specific tasks.

```php
use NeuronAI\Evaluation\Assertions\AgentJudge;
use NeuronAI\Agent;

$judge = Agent::make()
    ->setInstructions('You are an expert evaluator for customer support responses.');

// With few-shot examples for calibration
$this->assert(new AgentJudge(
    judge: $judge,
    criteria: 'Rate the factual accuracy of the response',
    threshold: 0.7,
    examples: [
        [
            'input' => 'What is 2+2?',
            'output' => '2+2 equals 4',
            'score' => 1.0,
            'reasoning' => 'Mathematically correct and clear.',
        ],
    ]
), $output);
```

--------------------------------

### Dependency Injection with HasHttpClient

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/HttpClient/AGENTS.md

Example of using the `HasHttpClient` trait for dependency injection.

```APIDOC
## Dependency Injection

### Description
This section shows how to inject an `HttpClientInterface` implementation into a class using the `HasHttpClient` trait.

### Usage

```php
use YourNamespace\HttpClient\HasHttpClient;
use YourNamespace\HttpClient\GuzzleHttpClient;

class MyProvider {
    use HasHttpClient;

    public function __construct() {
        // Set a specific HTTP client implementation (e.g., GuzzleHttpClient)
        $this->setHttpClient(new GuzzleHttpClient());
    }

    // You can now use $this->getHttpClient() to access the client
    public function performRequest() {
        $request = new HttpRequest('GET', 'https://api.example.com/data');
        $response = $this->getHttpClient()->send($request);
        // Process response
    }
}
```
```

--------------------------------

### Required Property Logic Examples

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-structured-output/SKILL.md

Demonstrates how properties are determined as required or optional based on nullability, default values, and explicit SchemaProperty settings.

```php
class Example
{
    // Required - non-nullable, no default
    public string $firstName;

    // Optional - explicitly marked
    #[SchemaProperty(required: false)]
    public string $middleName;

    // Optional - nullable
    public ?string $lastName;

    // Optional - has default
    public string $country = 'US';
}
```

--------------------------------

### Connect Multiple MCP Servers

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/MCP/AGENTS.md

Integrate tools from multiple MCP servers into your agent. This example shows connecting to both a PostgreSQL database server and a file system server.

```php
protected function tools(): array
{
    return [
        // Database tools
        ...McpConnector::make([
            'command' => 'mcp-server-postgres',
            'args' => ['postgres://localhost/mydb'],
        ])->tools(),

        // File system tools
        ...McpConnector::make([
            'command' => 'mcp-server-filesystem',
            'args' => ['/home/user/documents'],
        ])->tools(),
    ];
}
```

--------------------------------

### Agent Execution Modes

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Agent/AGENTS.md

Examples for streaming responses and extracting structured output from an agent.

```php
// Streaming
foreach (YouTubeAgent::make()->stream($message) as $chunk) {
    echo $chunk;
}

// Structured output
$report = MyAgent::make()->structured($message, ReportSchema::class);
```

--------------------------------

### Tool Return Value: String

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Tools must return a string or a stringifiable value. This example shows a simple string return.

```php
// String
public function __invoke(string $query): string
{
    return "Result: {$query}";
}
```

--------------------------------

### Focused Schema Example (Good)

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-structured-output/SKILL.md

Create focused classes for specific data needs to simplify schema generation and improve LLM performance.

```php
// GOOD - Focused on what you need
class UserContact
{
    public string $name;
    public string $email;
}
```

--------------------------------

### Use Descriptive Property Names in Tool Creation

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Use descriptive names and provide detailed descriptions for tool properties to improve clarity and usability. The 'GOOD' example shows a more informative description including an example.

```php
// BAD
ToolProperty::make('query', PropertyType::STRING, 'Query', true)
```

```php
// GOOD
ToolProperty::make(
    name: 'query',
    type: PropertyType::STRING,
    description: 'Natural language search query. Be specific and include key terms.
    Example: "vacation policy for remote employees"',
    required: true
)
```

--------------------------------

### Create a Custom YouTube Agent

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Tools/AGENTS.md

Define a custom agent by extending the Agent class, specifying the AI provider, system instructions, and available tools. This example shows an agent specialized for summarizing YouTube videos.

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

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: env('ANTHROPIC_API_KEY'),
            model: 'claude-sonnet-4-6',
        );
    }

    public function instructions(): string
    {
        return (string) 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.',
                'After the summary add a list of three sentences as the most important takeaways.'
            ]
        );
    }

    protected function tools(): array
    {
        return [
            GetTranscriptionTool::make(env('SUPADATA_API_KEY')),
        ];
    }
}

// Usage
use NeuronAI\Chat\Messages\UserMessage;

$response = YouTubeAgent::make()->chat(
    new UserMessage('Summarize this: https://youtube.com/watch?v=...')
);
```

--------------------------------

### Return Structured JSON Data from Tools

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Structure the output of your tool as JSON to provide clear and consistent data. This example demonstrates returning success status, query details, count, and results.

```php
public function __invoke(string $query): string
{
    $results = $this->search($query);

    // Return structured JSON
    return json_encode([
        'success' => true,
        'query' => $query,
        'count' => count($results),
        'results' => $results,
    ]);
}
```

--------------------------------

### Testing MCP Integrations with FakeMcpTransport

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-test-engineer/SKILL.md

Demonstrates how to use FakeMcpTransport to simulate MCP server interactions for testing purposes. Includes examples for initialization handshake and tool calls.

```APIDOC
## Testing MCP Integrations

Use `FakeMcpTransport` to test code that interacts with MCP servers without running a real server.

### Example: Initialization Handshake

```php
use NeuronAI\Testing\FakeMcpTransport;

// ... inside a test method ...
$transport = new FakeMcpTransport(
    ['result' => ['capabilities' => [], 'serverInfo' => ['name' => 'test-server']]],
    ['result' => []]
);

$transport->connect();

// Simulate initialization handshake
$transport->send(['method' => 'initialize', 'params' => ['capabilities' => []]]);
$transport->receive(); // consume capabilities response

$transport->send(['method' => 'notifications/initialized']);
$transport->receive(); // consume ack

$transport->assertInitialized();
$transport->assertConnected();
```

### Example: Tool Call

```php
// ... inside a test method ...
$transport = new FakeMcpTransport(
    ['result' => ['tools' => [['name' => 'search', 'description' => 'Search']]]],
    ['result' => ['content' => [['type' => 'text', 'text' => 'Found 3 results']]]]
);

$transport->connect();

$transport->send(['method' => 'tools/list', 'params' => []]);
$transport->receive();

$transport->send(['method' => 'tools/call', 'params' => ['name' => 'search', 'arguments' => ['query' => 'test']]]);
$transport->receive();

$transport->assertToolsListCalled();
$transport->assertToolCalled('search');
$transport->assertSendCount(2);
$transport->assertReceiveCount(2);
```
```

--------------------------------

### Custom Agent with Anthropic Provider

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Providers/AGENTS.md

Example of creating a custom agent class that utilizes the Anthropic provider. Ensure ANTHROPIC_API_KEY is set in your environment.

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

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: env('ANTHROPIC_API_KEY'),
            model: 'claude-sonnet-4-6',
        );
    }

    public function instructions(): string
    {
        return (string) new SystemPrompt(
            background: ['You are a helpful AI assistant.'],
            steps: ['Answer questions accurately and concisely.'],
            output: ['Be friendly and professional.']
        );
    }
}

// Usage
$response = MyAgent::make()->chat(new UserMessage('Hello!'));
```

--------------------------------

### Using MCP Tools in Agent

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Integrates tools from an MCP server into an Agent. This example shows combining custom tools with tools from both stdio and HTTP MCP servers.

```php
class MyAgent extends Agent
{
    protected function tools(): array
    {
        return [
            // Custom tools
            new MyCustomTool(),

            // MCP server tools
            ...McpConnector::make([
                'command' => 'npx',
                'args' => ['-y', '@modelcontextprotocol/server-filesystem', '/data'],
            ])->tools(),

            // HTTP MCP server
            ...McpConnector::make([
                'url' => 'https://api.example.com/mcp',
                'token' => $_ENV['MCP_TOKEN'],
            ])->tools(),
        ];
    }
}
```

--------------------------------

### Custom RAG Agent Implementation

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/RAG/AGENTS.md

Extend the RAG class to create a custom agent. Define the AI provider, embeddings service, and vector store to be used. This example shows setting up an agent using Anthropic, OpenAI embeddings, and a FileVectorStore.

```php
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\OpenAIEmbeddings;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\FileVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class WorkoutTipsAgent extends RAG
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: env('ANTHROPIC_API_KEY'),
            model: 'claude-sonnet-4-6',
        );
    }

    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new OpenAIEmbeddings(
            key: env('OPENAI_API_KEY'),
            model: 'text-embedding-3-small',
        );
    }

    protected function vectorStore(): VectorStoreInterface
    {
        return new FileVectorStore(
            storage: storage_path('app/embeddings'),
        );
    }
}

// Usage
$response = WorkoutTipsAgent::make()->chat(
    new UserMessage('What are the best exercises for back pain?')
);
```

--------------------------------

### Company Knowledge Base RAG Configuration

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-rag-specialist/SKILL.md

Example configuration for a company knowledge base RAG bot using OpenAI embeddings and Pinecone vector store with hybrid search.

```php
class CompanyKnowledgeBot extends RAG
{
    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new OpenAIEmbeddingProvider(
            key: $_ENV['OPENAI_API_KEY'],
            model: 'text-embedding-3-small'
        );
    }

    protected function vectorStore(): VectorStoreInterface
    {
        return new PineconeVectorStore(
            key: $_ENV['PINECONE_API_KEY'],
            indexUrl: $_ENV['PINECONE_INDEX_URL']
        );
    }

    protected function retrieval(): RetrievalInterface
    {
        return new HybridSearch(k: 5, alpha: 0.7);
    }

    protected function instructions(): string
    {
        return (string) new SystemPrompt(
            background: [
                "You are a helpful assistant that answers questions",
                "about our company using the provided context.",
            ],
            constraints: [
                "Only use the provided context to answer.",
                "If the answer is not in the context, say you don't know.",
            ]
        );
    }
}
```

--------------------------------

### Compare Multiple Agents with Neuron Evaluator

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Implement an evaluator to compare outputs from multiple agents. Initialize agents in setUp, run them concurrently in run, and evaluate their similarity in evaluate. Requires a calculateSimilarity method and GreaterThanAssertion.

```php
public function setUp(): void
{
    $this->agentA = new AgentOne();
    $this->agentB = new AgentTwo();
}

public function run(array $datasetItem): mixed
{
    return [
        'agent_a' => $this->agentA->chat(...)->getContent(),
        'agent_b' => $this->agentB->chat(...)->getContent(),
    ];
}

public function evaluate(mixed $output, array $datasetItem): void
{
    $similarity = $this->calculateSimilarity(
        $output['agent_a'],
        $output['agent_b']
    );
    $this->assert(new GreaterThanAssertion(0.8), $similarity);
}
```

--------------------------------

### Integrate Neuron Evaluation with GitHub Actions

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Set up a GitHub Actions workflow to automatically run Neuron evaluations on push or pull request events. This includes checking out code, setting up PHP, installing dependencies, and executing the Neuron evaluation command.

```yaml
name: Evaluation Tests

on: [push, pull_request]

jobs:
    evaluate:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v3
            - name: Setup PHP
              uses: shivammathur/setup-php@v2
              with:
                  php-version: '8.2'
            - name: Install dependencies
              run: composer install
            - name: Run evaluations
              run: vendor/bin/neuron evaluation evaluators --verbose
              env:
                  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

--------------------------------

### JSON Dataset Example

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Example structure for a sentiment analysis JSON dataset. Each object should contain the input data and the expected output or criteria for evaluation.

```json
[
    {"text": "I love this!", "expected": "positive"},
    {"text": "This is bad.", "expected": "negative"}
]
```

--------------------------------

### Initialize LogObserver

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Observability/AGENTS.md

Instantiate the LogObserver using a PSR-3 compliant logger.

```php
new LogObserver($psrLogger)
```

--------------------------------

### Custom Assertion: GreaterThanAssertion

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Example of creating a custom assertion class that extends AbstractAssertion. This specific example checks if a numeric value is greater than a defined threshold.

```php
use NeuronAI\Evaluation\Assertions\AbstractAssertion;
use NeuronAI\Evaluation\AssertionResult;

class GreaterThanAssertion extends AbstractAssertion
{
    public function __construct(
        private readonly float $threshold
    ) {}

    public function evaluate(mixed $actual): AssertionResult
    {
        if (!is_numeric($actual)) {
            return AssertionResult::fail(
                0.0,
                'Expected numeric value, got ' . gettype($actual),
            );
        }

        if ($actual > $this->threshold) {
            return AssertionResult::pass(1.0);
        }

        return AssertionResult::fail(
            0.0,
            "Expected {$actual} to be greater than {$this->threshold}",
        );
    }
}
```

--------------------------------

### Alternative Provider Implementations

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Providers/AGENTS.md

Demonstrates how to configure different AI providers within an agent. Ensure the respective API keys are set in your environment.

```php
// OpenAI
use NeuronAI\Providers\OpenAI\OpenAI;

protected function provider(): AIProviderInterface
{
    return new OpenAI(
        key: env('OPENAI_API_KEY'),
        model: 'gpt-4o',
    );
}
```

```php
// Gemini
use NeuronAI\Providers\Gemini\Gemini;

protected function provider(): AIProviderInterface
{
    return new Gemini(
        key: env('GEMINI_API_KEY'),
        model: 'gemini-2.0-flash',
    );
}
```

```php
// Ollama (local)
use NeuronAI\Providers\Ollama\Ollama;

protected function provider(): AIProviderInterface
{
    return new Ollama(
        model: 'llama3.2',
    );
}
```

--------------------------------

### Streaming Responses

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/HttpClient/AGENTS.md

Example of how to process streaming responses using the `stream` method.

```APIDOC
## Streaming Responses

### Description
This section demonstrates how to consume streaming responses from the HTTP client.

### Usage

```php
// Assuming $client is an instance of HttpClientInterface
// and $request is a configured HttpRequest object

$stream = $client->stream($request);

foreach ($stream as $chunk) {
    // Process each chunk of the streaming response
    echo $chunk;
}
```

### `StreamInterface`
The `stream` method returns an object implementing `StreamInterface`, which allows iteration over the response chunks.
```

--------------------------------

### Qdrant Vector Store Configuration

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-rag-specialist/SKILL.md

Set up the Qdrant vector store using an API key, URL, and collection name.

```php
use NeuronAI\RAG\VectorStore\QdrantVectorStore;

new QdrantVectorStore(
    apiKey: $_ENV['QDRANT_API_KEY'],
    url: $_ENV['QDRANT_URL'],
    collection: 'my_collection'
);
```

--------------------------------

### Using Toolkits in an Agent

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Demonstrates how to include toolkits within an Agent. Use the spread operator (...) to unpack the tools from the toolkit instances.

```php
use NeuronAI\Agent\Agent;

class MyAgent extends Agent
{
    protected function tools(): array
    {
        return [
            // Use full toolkit
            ...CalculatorToolkit::make(),

            // Use toolkit with dependencies
            ...MySQLToolkit::make($this->pdo),
        ];
    }
}
```

--------------------------------

### Schema with Default Values

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-structured-output/SKILL.md

Example of a JSON schema generated from a class with default values.

```json
{
  "theme": {"type": "string", "default": "light"},
  "timeout": {"type": "integer", "default": 30},
  "debug": {"type": "boolean", "default": false}
}
```

--------------------------------

### Define System Prompt

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-agent-builder/SKILL.md

Use the SystemPrompt class to define agent background, operational steps, and output constraints.

```php
new SystemPrompt(
    background: [
        "You are a data analyst expert in creating reports.",
    ],
    steps: [
        "Analyze the user's request",
        "Query the database",
        "Generate a summary",
    ],
    output: [
        "Always cite your sources",
        "Never make up data",
    ]
)
```

--------------------------------

### Create Tool with Dependencies (Database Query)

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

This approach is suitable for tools that require external dependencies like a database connection. The dependencies are injected via the constructor, and the tool logic is implemented in the __invoke method.

```php
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;
use PDO;

class DatabaseQueryTool extends Tool
{
    public function __construct(protected PDO $pdo)
    {
        parent::__construct(
            name: 'query_users',
            description: 'Query user data from the database'
        );
    }

    protected function properties(): array
    {
        return [
            ToolProperty::make(
                name: 'email',
                type: PropertyType::STRING,
                description: 'User email to search for',
                required: false
            ),
            ToolProperty::make(
                name: 'limit',
                type: PropertyType::INTEGER,
                description: 'Maximum number of results',
                required: false
            ),
        ];
    }

    public function __invoke(?string $email = null, ?int $limit = 10): array
    {
        $query = "SELECT * FROM users";

        if ($email) {
            $query .= " WHERE email LIKE :email";
        }

        $query .= " LIMIT :limit";

        $stmt = $this->pdo->prepare($query);

        if ($email) {
            $stmt->bindValue(':email', "%{$email}%");
        }
        $stmt->bindValue(':limit', $limit, PDO::PARAM_INT);

        $stmt->execute();
        return $stmt->fetchAll(PDO::FETCH_ASSOC);
    }
}
```

--------------------------------

### Instantiate Empty FakeVectorStore and Set Results Later

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-test-engineer/SKILL.md

Create an empty FakeVectorStore and populate its search results programmatically using the setSearchResults() method.

```php
// Or create empty and set results later
$vectorStore = FakeVectorStore::make();
$vectorStore->setSearchResults([
    new Document('Relevant document content')
]);
```

--------------------------------

### Initialize a UserMessage with ContentBlocks

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Chat/AGENTS.md

Demonstrates creating a UserMessage containing both text and image content blocks.

```php
$message = new UserMessage([
    new TextContent('Analyze this:'),
    new ImageContent('https://...', SourceType::URL, MediaType::JPEG),
]);
```

--------------------------------

### Node Signature Example

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Workflow/AGENTS.md

Defines the signature for a node within the workflow, determining how it handles specific events and manages state.

```php
public function __invoke(SpecificEvent $event, WorkflowState $state): NextEvent
```

--------------------------------

### Tool Description Best Practice

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Illustrates the difference between a vague and a clear, actionable tool description. Clear descriptions help the LLM understand when and how to use a tool effectively.

```php
// BAD - Vague
description: 'Search function'

// GOOD - Clear and actionable
description: 'Search the company knowledge base for documents, FAQs, and policies.
Returns relevant excerpts with source URLs. Use this when the user asks about
company procedures, policies, or documented information.'
```

--------------------------------

### Combining SchemaProperty and Validation

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-structured-output/SKILL.md

Combine #[SchemaProperty] attributes with validation attributes to both guide LLM generation and enforce data constraints.

```php
class Rating
{
    // Both guide LLM AND validate output
    #[SchemaProperty(description: 'Rating from 1 to 5', min: 1, max: 5)]
    #[GreaterThan(0)]
    #[LowerThan(6)]
    public int $stars;
}
```

--------------------------------

### Create a Custom Tool

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Tools/AGENTS.md

Extend the base `Tool` class and implement required methods to define a new tool. Ensure the constructor sets the tool's name and description, and the `properties()` method defines its input parameters.

```php
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

class GetTranscriptionTool extends Tool
{
    public function __construct(protected string $apiKey)
    {
        parent::__construct(
            'get_transcription',
            'Retrieve the transcription of a YouTube video.'
        );
    }

    protected function properties(): array
    {
        return [
            new ToolProperty(
                name: 'video_url',
                type: PropertyType::STRING,
                description: 'The URL of the YouTube video.',
                required: true
            )
        ];
    }

    public function __invoke(string $video_url): string
    {
        // Your API call logic here
        return $transcription;
    }
}
```

--------------------------------

### Wire Up Workflow

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-workflow-architect/SKILL.md

Initializes and runs a workflow by adding nodes and setting the initial state. The `Workflow::make()` method creates a new workflow instance.

```php
$workflow = Workflow::make()
    ->addNodes([
        new AnalyzeImageForkNode(),
        new ExtractStructuredDataNode(),
        new GenerateDescriptionNode(),
        new MergeAnalysisNode(),
    ]);

$state = $workflow->init(new WorkflowState(['image_url' => 'https://example.com/photo.jpg']));
$result = $state->run();
```

--------------------------------

### Workflow Initialization and Event Streaming

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Workflow/AGENTS.md

Initializes a workflow with nodes and demonstrates how to stream events or retrieve the final state.

```php
$handler = Workflow::make($state)
    ->addNodes([new NodeA(), new NodeB()])
    ->init();

// Stream events
foreach ($handler->events() as $event) { ... }

// Or get final state
$finalState = $handler->run();
```

--------------------------------

### Connect Local MCP Server to Agent

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/MCP/AGENTS.md

Integrate local MCP tools by specifying the command and arguments for the MCP server. Ensure the command and arguments correctly launch your local MCP server process.

```php
use NeuronAI\Agent;
use NeuronAI\MCP\McpConnector;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: env('ANTHROPIC_API_API_KEY'),
            model: 'claude-sonnet-4-6',
        );
    }

    public function instructions(): string
    {
        return 'You are a helpful assistant with access to external tools.';
    }

    protected function tools(): array
    {
        return [
            // Local MCP server via stdio
            ...McpConnector::make([
                'command' => 'php',
                'args' => ['/path/to/mcp_server.php'],
            ])->tools(),
        ];
    }
}
```

--------------------------------

### Create Basic ToolProperty

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Define a simple property for a tool's input or output. Specify its name, type, a description, and whether it's required.

```php
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

// Basic property
new ToolProperty(
    name: 'query',
    type: PropertyType::STRING,
    description: 'Search query',
    required: true
);
```

--------------------------------

### Similarity Retrieval Strategy

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/RAG/AGENTS.md

Implement the `retrieval` method to define the retrieval strategy. This example uses `SimilarityRetrieval`, which requires resolved instances of the vector store and embeddings provider.

```php
use NeuronAI\RAG\RAG\Retrieval\SimilarityRetrieval;

protected function retrieval(): RetrievalInterface
{
    return new SimilarityRetrieval(
        vectorStore: $this->resolveVectorStore(),
        embeddingsProvider: $this->resolveEmbeddingsProvider()
    );
}
```

--------------------------------

### Instantiate FakeAIProvider using Static Constructor

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-test-engineer/SKILL.md

The static 'make' constructor provides a concise way to create a FakeAIProvider with a predefined sequence of responses.

```php
// Or use static constructor
$provider = FakeAIProvider::make(
    new AssistantMessage('Response 1'),
    new AssistantMessage('Response 2')
);
```

--------------------------------

### Configure FakeMiddleware to Throw Exception on Before Event

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-test-engineer/SKILL.md

Set up FakeMiddleware to simulate error conditions by configuring it to throw a specific exception when the 'before' event is triggered.

```php
// Configure exceptions for testing error handling
$middleware->setThrowOnBefore(new \Exception('Test exception'));
```

--------------------------------

### Manage Workflow State in PHP

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-workflow-architect/SKILL.md

Use `WorkflowState` to store and retrieve data across nodes. Supports setting, getting, checking existence, deleting, and retrieving subsets or all state.

```php
$state = new WorkflowState();

// Set values
$state->set('user_id', 123);
$state->set('data', ['key' => 'value']);

// Get values
$userId = $state->get('user_id');
$default = $state->get('missing_key', 'default_value');

// Check existence
if ($state->has('data')) {
    // Data exists
}

// Get subset of state
$subset = $state->only(['user_id', 'data']);

// Delete value
$state->delete('data');

// Get all state
$all = $state->all();
```

--------------------------------

### Agent Instructions - Explicit Tool Usage

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-debugger/SKILL.md

Provide explicit instructions to the agent about available tools and when to use them. This helps prevent the agent from ignoring tools.

```php
// Add explicit tool instruction
protected function instructions(): string
{
    return (string) new SystemPrompt(
        background: [
            "You have access to database tools to query user data.",
            "Use the search_user tool when asked about users.",
        ]
    );
}
```

--------------------------------

### Handle Errors Gracefully with JSON Responses

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Implement robust error handling by validating inputs and returning structured JSON error messages. This example checks for a valid URL format.

```php
public function __invoke(string $url): string
{
    if (!filter_var($url, FILTER_VALIDATE_URL)) {
        return json_encode([
            'success' => false,
            'error' => 'Invalid URL format',
            'hint' => 'Please provide a valid URL starting with http:// or https://'
        ]);
    }

    // ...
}
```

--------------------------------

### Gemini Embeddings Provider Configuration

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/RAG/AGENTS.md

Set up the Gemini embeddings provider by specifying your API key and the desired model. This example demonstrates how to implement the `embeddings` method in a custom RAG agent.

```php
use NeuronAI\RAG\Embeddings\GeminiEmbeddings;

protected function embeddings(): EmbeddingsProviderInterface
{
    return new GeminiEmbeddings(
        key: env('GEMINI_API_KEY'),
        model: 'text-embedding-004',
    );
}
```

--------------------------------

### Generate Agent and Tool Classes

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Console/AGENTS.md

Use these commands to generate boilerplate code for agents and tools using the `make:` commands.

```bash
php vendor/bin/neuron make:agent MyAgent
php vendor/bin/neuron make:tool MyTool
```

--------------------------------

### Pinecone Vector Store Configuration

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-rag-specialist/SKILL.md

Instantiate the Pinecone vector store. Requires API key and index URL from environment variables.

```php
use NeuronAI\RAG\VectorStore\PineconeVectorStore;

new PineconeVectorStore(
    key: $_ENV['PINECONE_API_KEY'],
    indexUrl: $_ENV['PINECONE_INDEX_URL'],
    environment: 'us-east-1-aws'
);
```

--------------------------------

### Manual Validation with Validator

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-structured-output/SKILL.md

Shows how to manually validate an object using the Validator class. This example creates a Person object with invalid data and then uses Validator::validate() to find and report any violations.

```php
use NeuronAI\StructuredOutput\Validation\Validator;

$person = new Person();
$person->name = '';
$person->age = -5;

$violations = Validator::validate($person);

if ($violations !== []) {
    foreach ($violations as $violation) {
        echo $violation . "\n";
    }
}

```

--------------------------------

### Pinecone Vector Store Configuration

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/RAG/AGENTS.md

Configure the Pinecone vector store by providing your API key, index name, and namespace. This is an example of implementing the `vectorStore` method within a custom RAG class.

```php
use NeuronAI\RAG\VectorStore\PineconeVectorStore;

protected function vectorStore(): VectorStoreInterface
{
    return new PineconeVectorStore(
        apiKey: env('PINECONE_API_KEY'),
        indexName: 'my-index',
        namespace: 'documents',
    );
}
```

--------------------------------

### Register Built-in Toolkits

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-agent-builder/SKILL.md

Add pre-built toolkits to the agent by returning them in the tools method.

```php
use NeuronAI\Tools\Toolkits\MySQL\MySQLToolkit;
use NeuronAI\Tools\Toolkits\Calculator\CalculatorToolkit;

protected function tools(): array
{
    return [
        MySQLToolkit::make(\DB::connection()->getPdo()),
        CalculatorToolkit::make(),
    ];
}
```

--------------------------------

### Test RAG System with Custom Evaluator

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Extend BaseEvaluator to test RAG systems. Initialize the RAG agent in setUp and define run and evaluate methods for testing. Use specific assertions like StringContainsAny and StringSimilarity.

```php
class RAGEvaluator extends BaseEvaluator
{
    public function setUp(): void
    {
        $this->rag = new MyRAGAgent();
    }

    public function run(array $datasetItem): mixed
    {
        return $this->rag->chat(
            new UserMessage($datasetItem['question'])
        )->getMessage()->getContent();
    }

    public function evaluate(mixed $output, array $datasetItem): void
    {
        $this->assert(new StringContainsAny($datasetItem['key_facts']), $output);
        $this->assert(new StringSimilarity(
            reference: $datasetItem['expected_answer'],
            embeddingsProvider: $this->embeddings,
            threshold: 0.7
        ), $output);
    }
}
```

--------------------------------

### Create a Custom Output Driver

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Evaluation/AGENTS.md

Implement EvaluationOutputInterface to handle evaluation summaries, allowing for dependency injection via the constructor.

```php
class DatabaseOutput implements EvaluationOutputInterface
{
    public function __construct(
        private readonly \PDO $pdo
    )
    {
    }

    public function output(EvaluatorSummary $summary): void
    {
        // Store in database
    }
}
```

```php
return [
    'output' => [
        new DatabaseOutput($container->get(\PDO::class)),
    ],
];
```

--------------------------------

### Initialize AI Providers

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-agent-builder/SKILL.md

Configure specific AI model providers by passing the required API keys and model identifiers.

```php
new Anthropic(
    key: $_ENV['ANTHROPIC_API_KEY'],
    model: 'claude-3-5-sonnet-20241022',
)
```

```php
new OpenAI(
    key: $_ENV['OPENAI_API_KEY'],
    model: 'gpt-4',
)
```

```php
new Ollama(
    baseUrl: 'http://localhost:11434',
    model: 'llama3',
)
```

--------------------------------

### Implement Custom Run Key Tracking

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Tools/AGENTS.md

Implement the `RunKeyInterface` and its `getRunKey()` method to enable parameter-aware tracking of tool runs. This is useful for tools where different input parameters should be considered distinct runs.

```php
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\HasRunKey;

class ReadFileTool extends Tool implements HasRunKey
{
    public function __construct()
    {
        parent::__construct(
            'read_file',
            'Read a portion of a file.'
        );
    }

    protected function properties(): array
    {
        return [
            ToolProperty::make('path', PropertyType::STRING, 'File path', true),
            ToolProperty::make('offset', PropertyType::INTEGER, 'Byte offset', true),
            ToolProperty::make('length', PropertyType::INTEGER, 'Bytes to read', true),
        ];
    }

    public function __invoke(string $path, int $offset, int $length): string
    {
        // Read file portion
        return file_get_contents($path, false, null, $offset, $length);
    }

    public function getRunKey(): string
    {
        // Track runs by path and offset, allowing different offsets
        return $this->getName() . ':' . $this->getInput('path') . ':' . $this->getInput('offset');
    }
}
```

--------------------------------

### Create a Custom Toolkit

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Tools/AGENTS.md

Group related tools by extending the AbstractToolkit class and defining the tools within the tools() method. This allows for better organization and reusability of tools within agents.

```php
use NeuronAI\Tools\Toolkits\AbstractToolkit;

class MyToolkit extends AbstractToolkit
{
    public function tools(): array
    {
        return [new ToolA(), new ToolB()];
    }
}

// In agent
protected function tools(): array
{
    return [
        new MyToolkit(),
    ];
}
```

--------------------------------

### Elasticsearch Vector Store Configuration

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-rag-specialist/SKILL.md

Initialize the Elasticsearch vector store with host addresses and an index name.

```php
use NeuronAI\RAG\VectorStore\ElasticsearchVectorStore;

new ElasticsearchVectorStore(
    hosts: ['http://localhost:9200'],
    index: 'documents'
);
```

--------------------------------

### Run Evaluations via CLI

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Evaluation/AGENTS.md

Execute evaluations using the vendor binary with optional verbosity and concurrency settings.

```bash
vendor/bin/neuron evaluation path/to/evaluators
vendor/bin/neuron evaluation --verbose path/to/evaluators
vendor/bin/neuron evaluation --concurrency=8 path/to/evaluators
```

--------------------------------

### Run development commands

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/AGENTS.md

Use these Composer commands to execute tests, format code, and perform static analysis.

```bash
composer test          # Run tests (PHPUnit)
composer format        # Fix code style (PHP CS Fixer)
composer analyse       # Static analysis (PHPStan level 5)
```

--------------------------------

### Create a Custom Agent Class

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Agent/AGENTS.md

Extend the Agent class to define custom providers, instructions, and tools for specific tasks.

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

class YouTubeAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: env('ANTHROPIC_API_KEY'),
            model: 'claude-sonnet-4-6',
        );
    }

    public function instructions(): string
    {
        return (string) 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.',
                'After the summary add a list of three sentences as the most important takeaways.',
            ]
        );
    }

    protected function tools(): array
    {
        return [
            GetTranscriptionTool::make(env('SUPADATA_API_KEY')),
        ];
    }
}

// Usage
use NeuronAI\Chat\Messages\UserMessage;

$response = YouTubeAgent::make()->chat(
    new UserMessage('Summarize this: https://youtube.com/watch?v=...')
);
```

--------------------------------

### Create an Agent

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/README.md

Generate a new agent class using the Neuron CLI and define its provider and instructions.

```bash
vendor/bin/neuron make:agent DataAnalystAgent
```

```php
<?php

namespace App\Neuron;

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

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

    protected function instructions(): string
    {
        return (string) new SystemPrompt(
            background: [
                "You are a data analyst expert in creating reports from SQL databases."
            ]
        );
    }
}
```

--------------------------------

### Applying Middleware to Workflow Execution

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/Workflow/AGENTS.md

Demonstrates how to wrap node execution with custom middleware for cross-cutting concerns like logging or performance monitoring.

```php
$workflow->middleware(NodeClass::class, new LoggingMiddleware());
$workflow->globalMiddleware(new PerformanceMiddleware());
```

--------------------------------

### SchemaProperty Constructor Arguments

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-structured-output/SKILL.md

Illustrates the available arguments for the SchemaProperty attribute, which control JSON schema generation for LLM prompts.

```php
#[SchemaProperty(
    string $title = null,        // Property title in JSON schema
    string $description = null,  // Property description (guides LLM)
    bool $required = null,       // Override required status
    int $min = null,             // Minimum value (numbers) or items (arrays)
    int $max = null,             // Maximum value (numbers) or items (arrays)
    int $minLength = null,       // Minimum string length
    int $maxLength = null,       // Maximum string length
    array $anyOf = null,         // Array of allowed class/enum types
)]
```

--------------------------------

### Evaluation Output Configuration: Config File

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Configure evaluation output drivers by creating an 'evaluation.php' file. Specify drivers like ConsoleOutput or JsonOutput with their respective configurations.

```php
<?php

use NeuronAI\Evaluation\Output\ConsoleOutput;
use NeuronAI\Evaluation\Output\JsonOutput;

return [
    'output' => [
        // Simple driver (no options)
        ConsoleOutput::class,

        // Driver with options (class as key)
        JsonOutput::class => [
            'path' => 'evaluation-results.json',
        ],
    ],
];
```

--------------------------------

### ConsoleOutput Driver Configuration

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Configure the ConsoleOutput driver for detailed output, especially for failures. Set the 'verbose' option to true to enable detailed input/output logging.

```php
ConsoleOutput::class => ['verbose' => true]
```

--------------------------------

### Pre-populate FakeVectorStore with Search Results

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-test-engineer/SKILL.md

Use FakeVectorStore to mock RAG system interactions. Pre-populate it with Document objects that simulate search results.

```php
use NeuronAI\Testing\FakeVectorStore;
use NeuronAI\RAG\Document;

// Pre-populate with search results
$vectorStore = new FakeVectorStore([
    new Document('France is a country in Europe. Its capital is Paris.'),
    new Document('Germany is a country in Europe. Its capital is Berlin.'),
]);
```

--------------------------------

### Run All Tests

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-test-engineer/SKILL.md

Execute all tests in the project using the composer test command.

```bash
composer test
```

--------------------------------

### Instantiate FakeEmbeddingsProvider using Static Constructor

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-test-engineer/SKILL.md

The static 'make' constructor offers a shorthand for creating a FakeEmbeddingsProvider instance.

```php
// Use static constructor
$embeddings = FakeEmbeddingsProvider::make();
```

--------------------------------

### Basic Calculator Toolkit

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Defines a basic toolkit for mathematical operations. Extend AbstractToolkit and implement provide() to return tool instances.

```php
use NeuronAI\Tools\Toolkits\AbstractToolkit;

class CalculatorToolkit extends AbstractToolkit
{
    public function guidelines(): ?string
    {
        return "This toolkit allows you to perform mathematical operations.
        You can use these functions to solve mathematical expressions
        step by step to calculate the final result.";
    }

    public function provide(): array
    {
        return [
            SumTool::make(),
            SubtractTool::make(),
            MultiplyTool::make(),
            DivideTool::make(),
        ];
    }
}
```

--------------------------------

### Use HttpClient with HasHttpClient Trait

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/src/HttpClient/AGENTS.md

Shows how to integrate the HttpClient into a class using the HasHttpClient trait and setting a specific implementation like GuzzleHttpClient during construction.

```php
class MyProvider {
    use HasHttpClient;

    public function __construct() {
        $this->setHttpClient(new GuzzleHttpClient());
    }
}
```

--------------------------------

### StringStartsWith Assertion in PHP

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-evaluation-engineer/SKILL.md

Asserts that the output string begins with a specified prefix. Useful for validating formatted output or greetings.

```php
$this->assert(new StringStartsWith('Hello'), $output);
```

--------------------------------

### Define Multi-step Execution Plan

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/AGENTS.md

Use this format to structure complex tasks into verifiable steps.

```text
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

--------------------------------

### Create Weather Tool by Extending Tool Class

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-tool-creator/SKILL.md

Use this method for complex tools requiring structured properties and a dedicated class. It defines properties like location and units, and the core logic within the __invoke method.

```php
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

class WeatherTool extends Tool
{
    public function __construct()
    {
        parent::__construct(
            name: 'get_weather',
            description: 'Get the current weather for a location. Returns temperature, conditions, and humidity.'
        );
    }

    protected function properties(): array
    {
        return [
            ToolProperty::make(
                name: 'location',
                type: PropertyType::STRING,
                description: 'The city and country, e.g., "Paris, France"',
                required: true
            ),
            ToolProperty::make(
                name: 'units',
                type: PropertyType::STRING,
                description: 'Temperature units: "celsius" or "fahrenheit"',
                required: false,
                enum: ['celsius', 'fahrenheit']
            ),
        ];
    }

    public function __invoke(string $location, ?string $units = 'celsius'): string
    {
        // Your API call or logic here
        $weatherData = $this->fetchWeather($location, $units);

        return json_encode($weatherData);
    }

    private function fetchWeather(string $location, string $units): array
    {
        // Implementation...
        return [
            'location' => $location,
            'temperature' => 22,
            'units' => $units,
            'conditions' => 'sunny',
        ];
    }
}
```

--------------------------------

### Load Multiple Files from Directory

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-rag-specialist/SKILL.md

Employ DirectoryLoader to load all documents from a specified directory.

```php
use NeuronAI\RAG\DocumentLoader\DirectoryLoader;

$loader = new DirectoryLoader('/path/to/documents');
$documents = $loader->load();
```

--------------------------------

### Enable Parallel Tool Execution

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-agent-builder/SKILL.md

Toggle parallel tool calls; requires the pcntl extension.

```php
$agent->parallelToolCalls(true);
```

--------------------------------

### Generate Agent Boilerplate via CLI

Source: https://github.com/neuron-core/neuron-ai/blob/3.x/skills/neuron-agent-builder/SKILL.md

Use the Neuron CLI to scaffold a new agent class.

```bash
vendor/bin/neuron make:agent MyCustomAgent
```
Tokens:
Raw