Neuron AI

Retrieval-Augmented Generation (RAG) in Neuron AI is implemented by extending the RAG class. A RAG system is composed of three core architectural components that must be defined within your class:

1. Vector Store: A component that stores document embeddings to enable semantic search (implements VectorStoreInterface).
2. Embeddings Provider: A component that converts raw text into vector embeddings (implements EmbeddingsProviderInterface).
3. Retrieval Strategy: A component that determines the logic for searching and ranking retrieved documents (implements RetrievalInterface).

To use RAG, you create a class that extends NeuronAI ag ag ag and overrides the provider(), embeddings(), and vectorStore() methods.

use NeuronAI\RAG\RAG;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\OpenAIEmbeddingProvider;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;
use NeuronAI\RAG\VectorStore\PineconeVectorStore;

class MyChatBot extends RAG
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: $_ENV['ANTHROPIC_API_KEY'],
            model: 'claude-3-5-sonnet-20241022',
        );
    }

    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']
        );
    }
}

Neuron AI workflows are built on an event-driven architecture where nodes communicate by passing typed events. A workflow follows a sequence like: StartEvent → Node1 → Event2 → Node2 → Event3 → Node3 → StopEvent.

To create a node, extend the Node base class and implement the __invoke magic method. The workflow automatically routes events to a node based on the type hint of the first parameter in the __invoke signature. Each node receives the event and the shared WorkflowState, processes the data, and returns a new Event (or StopEvent to finish).

use NeuronAI\Workflow\Node;
use NeuronAI\Workflow\Event;
use NeuronAI\Workflow\StartEvent;
use NeuronAI\Workflow\WorkflowState;

class ValidationNode extends Node
{
    // The workflow maps events to this node based on the StartEvent type hint
    public function __invoke(StartEvent $event, WorkflowState $state): ProcessEvent
    {
        $input = $state->get('input');
        $validated = $this->validate($input);
        $state->set('validated', $validated);
        return new ProcessEvent($validated);
    }

    private function validate(mixed $input): array
    {
        return ['valid' => true, 'data' => $input];
    }
}

Neuron AI uses a two-layer approach to ensure LLM responses are both correctly formatted and valid:

1. SchemaProperty (Generation Layer): An attribute used on class properties to define the JSON schema sent to the LLM. This guides the LLM on how to generate the data (e.g., providing descriptions, types, and constraints).
2. Validation Rules (Verification Layer): PHP attributes applied to properties to verify that the LLM's response actually meets your requirements. If validation fails, Neuron can automatically retry the request.

By combining these two layers, you can force the LLM to follow a specific structure and then programmatically ensure the content of that structure is correct.

use NeuronAI\\StructuredOutput\\SchemaProperty;
use NeuronAI\\StructuredOutput\\Validation\\Rules\\NotBlank;

class Person
{
    #[SchemaProperty(description: 'The user name.', required: true)]
    #[NotBlank]
    public string $name;
}

For complex semantic validation, use AgentJudge to let an AI agent evaluate the output based on specific criteria.

Reference-free evaluation

Evaluate based only on criteria (e.g., "be polite").

Reference-based evaluation

Compare the output against an expected answer provided in the dataset.

Few-shot calibration

Provide examples of inputs, outputs, scores, and reasoning to calibrate the judge's behavior.

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

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

// Reference-free
$this->assert(new AgentJudge(
    judge: $judge,
    criteria: 'Response should be helpful, polite, and address the customer\'s question directly',
    threshold: 0.7
), $output);

// Reference-based
$this->assert(new AgentJudge(
    judge: $judge,
    criteria: 'The response should convey the same meaning as the reference',
    threshold: 0.8,
    reference: $datasetItem['expected_answer']
), $output);

// With few-shot examples
$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);