Forem: Samuel Akopyan

What a ML Model Really Is (From a Mathematical Perspective)

Samuel Akopyan — Sat, 21 Mar 2026 12:23:00 +0000

When we talk about a model in machine learning, it helps to immediately drop all associations with “artificial intelligence” and complex abstractions.

At its core, a model is simply a function.

Nothing more, nothing less.

It takes some input data and returns a result. The only difference is that this function isn’t fixed — it has parameters that can be adjusted.

If you’re a PHP developer, this should feel very familiar. A model is essentially just a function or class method:

it takes inputs
performs some computation
returns a value

A Model as a Function

In its most general form, a model looks like this:

f(x) = ŷ

x — input data
ŷ — predicted output

The “hat” on ŷ is intentional: it’s not the true value, just an estimate.

Function as the Foundation of a Model

Let’s make it concrete.

Suppose we want to predict the price of an apartment based on its size. A simple linear model would look like this:

ŷ = w * x + b

This already is a complete model.

It says:

“The predicted price is the area multiplied by some coefficient, plus an offset.”

Now let’s translate that into PHP:

class LinearModel {
    private float $w;
    private float $b;

    public function __construct(float $w, float $b) {
        $this->w = $w;
        $this->b = $b;
    }

    public function predict(float $x): float {
        return $this->w * $x + $this->b;
    }
}

Example usage:

$model = new LinearModel(2.0, 0.0);
echo $model->predict(3.0);

// Result: 6
// Explanation: 2 * 3 + 0 = 6

From a PHP perspective, this is just a regular class.

From a machine learning perspective — this is a model.

Model Parameters

The key idea here is parameters.

In our example:

w — weight
b — bias

These are not inputs. They define how the model behaves.

Change them → you change the output.

It’s important to distinguish between:

Input (x) — comes from outside
Parameters (w, b) — live inside the model
Output (ŷ) — the prediction

In traditional programming, you hardcode parameters.

In machine learning, it’s the opposite:

The structure is fixed, but the parameters are learned automatically.

Error as a Measure of Quality

Now the key question:

How do we know if one set of parameters is better than another?

We introduce error (also called a loss function).

This is just another function that measures how wrong the model is.

A simple version:

ŷ - y

PHP version:

function error(float $yTrue, float $yPredicted): float {
    return $yPredicted - $yTrue;
}

Example:

echo error(yTrue: 10.0, yPredicted: 7.0);

// Result: -3
// Explanation: 7 - 10 = -3

In practice, we usually use squared error:

(ŷ - y)^2

function squaredError(float $yTrue, float $yPredicted): float {
    return ($yPredicted - $yTrue) ** 2;
}

Example:

echo squaredError(yTrue: 4.0, yPredicted: 6.0);

// Result: 4
// Explanation: (6 - 4)^2 = 4

Important detail:

Error depends on ŷ, which depends on model parameters.

So ultimately:
error is a function of the parameters.

Training = Minimizing Error

Now everything comes together.

We have:

a model (function with parameters)
data (inputs + correct outputs)
error (how wrong the prediction is)

Training is simply:

Finding parameter values that minimize error.

Even in PHP, you can imagine it like this:

$dataset = [
    [1.0, 2.0],
    [2.0, 4.0],
];

$model = new LinearModel(w: 0.0, b: 0.0);

foreach ($dataset as [$x, $yTrue]) {
    $yPredicted = $model->predict($x);
    $loss = squaredError($yTrue, $yPredicted);

    // In real ML, parameters would be updated here
}

Initial (bad) model:

$model = new LinearModel(w: 0.0, b: 0.0);
// y = 0 * x

// x = 1 → loss = 4
// x = 2 → loss = 16

After some improvement:

$model = new LinearModel(w: 0.8, b: 0.0);
// y = 0.8 * x

// x = 1 → loss = 1.44
// x = 2 → loss = 5.76

And so on — parameters are adjusted to reduce the loss.

The exact update method (gradient descent, etc.) is a separate topic.

But the core idea is simple:

We don’t tell the model the rules.
We tell it how wrong it is — and it improves.

Why This Matters

For a PHP developer, this perspective is crucial.

Machine learning does not replace programming.

It builds on the same foundations:

functions
parameters
computations

Let’s strip away the hype:

A model is just a function
Training is just optimization
Error is just another function

Once you see it this way, machine learning stops being mysterious.

It becomes engineering:

choosing the right function
defining the right loss
efficiently finding good parameters

Try It Yourself

You can run the code examples here:

👉 https://aiwithphp.org/books/ai-for-php-developers/examples/part-1/what-is-a-model

Что такое ML модель в математическом смысле

Samuel Akopyan — Sat, 21 Mar 2026 11:56:02 +0000

Как это выглядит для PHP-разработчика
Проще всего понять это через привычную аналогию.
Любая модель очень похожа на обычную функцию или метод:
есть входные аргументы
есть вычисления
есть возвращаемое значение

В самом общем виде модель записывается так: f(x) = ŷ, где
x - входные данные
ŷ - предсказание модели

Важно: это не истинное значение, а лишь попытка его угадать.

Функция как основа модели
Допустим, мы хотим предсказывать цену квартиры по её площади.
Самая простая модель - линейная: ŷ = w · x + b
Она говорит:
Цена ≈ площадь × коэффициент + сдвиг

PHP-реализация
class LinearModel {
    private float $w;
    private float $b;

    public function __construct(float $w, float $b) {
        $this->w = $w;
        $this->b = $b;
    }

    public function predict(float $x): float {
        return $this->w * $x + $this->b;
    }
}

Пример:

$model = new LinearModel(2.0, 0.0);
echo $model->predict(3.0);

// Результат: 6
// Объяснение: 2 * 3 + 0 = 6

С точки зрения PHP - это обычный класс.
С точки зрения машинного обучения - это уже модель.

Параметры модели
Ключевой момент - параметры.
В нашем случае это: w и b
Они не являются входными данными, но именно от них зависит поведение модели.
Важно чётко разделять:
входные данные (x) - приходят извне
параметры (w, b) - настраиваются
выход (ŷ) - результат

В классическом программировании параметры фиксированы.
В машинном обучении - наоборот: структура фиксирована, параметры подбираются автоматически.

Ошибка как мера качества
Как понять, хороша ли модель?
Для этого используется функция ошибки (loss function).
Она сравнивает:
предсказание (ŷ)
реальное значение (y)

и возвращает число - насколько модель ошиблась.

Простая ошибка
Например, самая простая функция потерь - разница между предсказанием и реальным значением: ŷ - y

function error(float $yTrue, float $yPredicted): float {
    return $yPredicted - $yTrue;
}

Пример:

echo error(yTrue: 10.0, yPredicted: 7.0);
// Результат: -3
// Объяснение: 7 - 10 = -3

Квадрат ошибки (чаще используется)
На практике чаще используют квадрат ошибки (Squared Error или SE), потому что он всегда положительный и сильнее наказывает большие промахи: (ŷ - y)²

function squaredError(float $yTrue, float $yPredicted): float {
    return ($yPredicted - $yTrue) ** 2;
}

Пример:

echo squaredError(yTrue: 4.0, yPredicted: 6.0);

// Результат: 4
// Объяснение: (6 - 4)^2 = 4

Почему именно квадрат:

всегда положительный
сильнее наказывает большие ошибки

Важное наблюдение
Ошибка зависит от ŷ.
А ŷ зависит от параметров (w, b).
👉 Значит, ошибка - это функция параметров модели.

Обучение как минимизация ошибки
Если собрать всё вместе:

модель - функция с параметрами
данные - пары (x, y)
ошибка - мера качества

👉 Обучение = подбор параметров, уменьшающих ошибку

Простейшая иллюстрация на PHP

$dataset = [
    [1.0, 2.0],
    [2.0, 4.0],
];

$model = new LinearModel(w: 0.0, b: 0.0);

foreach ($dataset as [$x, $yTrue]) {
    $yPredicted = $model->predict($x);
    $loss = squaredError($yTrue, $yPredicted);

    // здесь параметры должны обновляться,
    // чтобы уменьшить loss
}

До обучения

$model = new LinearModel(w: 0.0, b: 0.0);

// Результат:
// y = 0 * x
// x = 1 → loss = 4
// x = 2 → loss = 16

После частичного обучения

$model = new LinearModel(w: 0.8, b: 0.0);

// Результат:
// y = 0.8 * x
// x = 1 → loss = 1.44
// x = 2 → loss = 5.76

Параметры постепенно меняются так, чтобы ошибка уменьшалась.

Ключевая идея
Никто не «объясняет» модели правила.
Мы просто:

даём данные
считаем ошибку
уменьшаем её

Почему это важно для PHP-разработчика
Это понимание убирает магию.
Модель - это функция
Обучение - это оптимизация
Ошибка - обычная функция

Машинное обучение не противоречит программированию - оно продолжает его.

Что дальше
Когда это становится понятно, начинается настоящая инженерия:
какие функции использовать
какие ошибки выбирать
как оптимизировать параметры

Полезные материалы
Книга: https://apphp.gitbook.io/ai-for-php-developers
Онлайн-демо: https://aiwithphp.org/books/ai-for-php-developers/examples/part-1/what-is-a-model

AI for PHP Developers. Practical Use of TransformersPHP

Samuel Akopyan — Mon, 09 Feb 2026 21:22:28 +0000

AI in PHP: Not Theory, but a Real Starting Point

In my previous articles, I described at a fairly high level why AI seems to be everywhere, yet barely intersects with everyday PHP development. Not because PHP is "unsuitable", but because the conversation usually happens outside our tasks and our habitual way of thinking. And, of course, because there is very little material that explains AI specifically for PHP developers - their problems and their mindset.

After the publication, I was asked the same question several times, in different forms:

Okay, suppose that's true. Where do you actually start?

And this is probably the most interesting question I received. Below, I'll try to answer it.

About the "Entry Point"

When you hear "using AI in a project", your mind likely jumps to a lot of unnecessary things at once: infrastructure, model training, experiments, separate services, new roles in the team, and so on.

But honestly, in most PHP projects we simply don't need all that (even though figuring it out is a fascinating task in itself).

In practice, we do not need to:

train models from scratch
understand gradient descent
collect datasets, etc.

It's important to understand that AI ≠ Data Science. My friends, in most PHP projects no one trains models. Please remember this! At least when we're talking about applied PHP projects that use ready-made models, not research or model training.

What we actually need is to take an existing tool and carefully integrate it into the current logic of the application - just like we do with any other library.

And this is where things get interesting.

What Is TransformersPHP, and What Do You Do With It?

Everyone already knows about using LLMs via APIs. It's useful and convenient, but in that form AI remains something external - a service you send text to. What's inside is a black box.

At some point, I wanted to look at a more "down-to-earth" level: not text generation, but semantic representation: embeddings, classification, and search tasks. This is where most applied backend problems are actually solved - text search, comparison, automatic classification - not human–model dialogue.

And here it suddenly turned out that there are tools that let you do this directly in PHP, without a Python stack. One of them is TransformersPHP.

It's important to clarify right away: this is not an attempt to turn PHP into Python, nor a universal solution. It's a library for inference - using already trained models.

In my view, TransformersPHP is one of the most interesting and illustrative projects in the modern PHP ML ecosystem. Special thanks to its author, Kyrian Obikwelu, for creating and maintaining it.

In short, it's a library that allows you to use transformer models (BERT, RoBERTa, DistilBERT, and others) directly from PHP - without Python and without external APIs.

Essentially, it's a PHP-oriented wrapper around Hugging Face Transformers ideas, adapted for the PHP ecosystem and real-world use cases.

The Key Feature: Local Inference

Models are loaded and executed inside the PHP application itself (via ONNX Runtime). This opens up important architectural possibilities:

no network calls to LLM APIs
full control over data (important for privacy-sensitive environments)
predictable and stable request latency
offline operation (after the first run and model download)

TransformersPHP supports common NLP tasks such as embeddings, text classification, semantic similarity, and more.

What I Like Most

The most valuable feeling is the absence of context switching.

I stay in PHP. I write the same code. I deploy the same way. I use the same architectural approaches. Nothing changes.

In this setup, the model is not some "magical object", but just another data source. Unusual, yes - but no more mysterious than any other.

And that completely changes your attitude toward the topic. Don't you agree?

Running a Model in 10 Minutes

The first launch is critical.
If it's complicated, that's usually where everything ends.

With TransformersPHP, the feeling is the opposite: it's more like working with a regular dependency.

The full installation guide is available in the documentation.
For simplicity, we'll run everything in Docker with all dependencies included.

Yes, the Dockerfile looks large - but it's one-time infrastructure. The actual launch and first demo really take just a few minutes.

Requirements

PHP 8.1 or higher
Composer
PHP FFI extension
JIT compilation (optional, for performance)
Increased memory limit (for heavier tasks like text generation)

Project Structure

/demo/
  ├── app/
  │    ├── demo.php
  │    ├── semantic-search.php
  ├── docker/
  │    ├── Dockerfile
  ├── docker-composer.yaml
  ├── composer.json

Installation (Docker)

File: docker-compose.yml

networks:
  ai-for-php-developers:
    driver: bridge

services:
  app:
    build:
      context: .
      dockerfile: docker/Dockerfile
    volumes:
      - .:/var/www
    ports:
      - "8088:8088"
    command: php -S 0.0.0.0:8088 -t app
    networks:
      - ai-for-php-developers

File: docker/Dockerfile

FROM php:8.2-fpm

# ------------------------------
# Install system dependencies
# ------------------------------
RUN apt-get update && apt-get install -y \
    libzip-dev \
    zip \
    unzip \
    git \
    libxml2-dev \
    libcurl4-openssl-dev \
    libpng-dev \
    libonig-dev \
    && rm -rf /var/lib/apt/lists/*

# ------------------------------
# Install PHP extensions
# ------------------------------
RUN docker-php-ext-install zip pdo_mysql bcmath xml mbstring curl gd pcntl

# ------------------------------
# Enable FFI
# ------------------------------
RUN apt-get update && apt-get install -y \
    libffi-dev \
    pkg-config \
    && rm -rf /var/lib/apt/lists/*
RUN docker-php-ext-install ffi
RUN echo "ffi.enable=1" > /usr/local/etc/php/conf.d/ffi.ini

# ------------------------------
# Install ONNX Runtime
# ------------------------------
ENV ONNXRUNTIME_VERSION=1.17.1

RUN curl -L https://github.com/microsoft/onnxruntime/releases/download/v${ONNXRUNTIME_VERSION}/onnxruntime-linux-x64-${ONNXRUNTIME\_VERSION}.tgz \
    | tar -xz \
    && cp onnxruntime-linux-x64-${ONNXRUNTIME_VERSION}/lib/libonnxruntime.so* /usr/lib/ \
    && ldconfig \
    && rm -rf onnxruntime-linux-x64-${ONNXRUNTIME_VERSION}

# ------------------------------
# Install Composer
# ------------------------------
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www

# Copy existing application directory contents
COPY . /var/www

# Configure PHP
RUN echo "memory_limit = 512M" >> /usr/local/etc/php/conf.d/docker-php-ram-limit.ini
RUN echo "max_execution_time = 300" >> /usr/local/etc/php/conf.d/docker-php-max-execution-time.ini

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]

File: composer.json

{
  "type": "project",
  "minimum-stability": "stable",
  "prefer-stable": true,
  "require": {
    "codewithkyrian/transformers": "~0.6.2"
  },
  "config": {
    "allow-plugins": {
      "codewithkyrian/platform-package-installer": true
    }
  }
}

Run the Environment

docker compose build --pull
docker compose up -d
docker compose exec app /bin/bash -c "composer install"

The idea is simple: the example should run locally without manual environment setup.

Basic Demo Example

Let's start with the simplest task: sentiment analysis.
If everything above worked correctly, you can run the example below (note that the first run may take a few seconds):

docker compose exec app php app/demo.php

File: app/demo.php

require_once __DIR__ . '/../vendor/autoload.php';

use function Codewithkyrian\Transformers\Pipelines\pipeline;

// Dedicate a sentiment analysis pipeline
$classifier = pipeline('sentiment-analysis');

$out = $classifier(['I love transformers!']);
print_r($out);

$out = $classifier(['I hate transformers!']);
print_r($out);
The result is exactly what you'd expect.
I love transformers!
Array ( 
  [label] => POSITIVE 
  [score] => 0.99978870153427 
)

I hate transformers!
Array ( 
  [label] => NEGATIVE 
  [score] => 0.99863630533218 
)

The purpose of this example is purely psychological: to remove the barrier.
A model in PHP is just another object you can work with.

Architectural Role of TransformersPHP

This library does not compete with large LLM services like GPT or Claude. It covers a different, very important layer:

fast embeddings
local classification
semantic search
lightweight NLP without external dependencies

In combination with PHP, this makes perfect sense. PHP remains the core business-logic layer, while transformers become an embedded tool rather than a remote service.

TransformersPHP is a great example of how modern ML is gradually becoming less "foreign" to PHP and more native to its ecosystem - through careful engineering bridges like ONNX.

Real Case: Semantic Search Over Events

Tutorial examples are nice, but they get boring quickly. Let's look at a task that actually occurs in backend systems.

Run the example:

docker compose exec app php app/semantic-search.php

Scenario

We have events with short textual descriptions. A user searches for:

"sanctions against IT companies"
"space race among countries in the region"

These exact phrases may not appear in the data at all. Traditional keyword search starts to struggle: synonyms, morphology, different languages, hacks on top of hacks.

A Thought Experiment

Suppose we have an event feed like this:

new restrictions introduced against technology corporations
regional countries increase investments in satellite programs
escalation of political conflict in several provinces

Now the user searches: "space race among countries in the region".

None of those words must appear literally. And that's normal - people don't think the way systems store text.

Solution Idea

Instead of guessing words, we search by meaning - in an engineering sense:

event description → vector
user query → vector
find nearest vectors

Embeddings become a universal index of meaning.

Steps

Take events {id, title, description}
Compute embeddings only for description
Embed the user query
Find nearest vectors
Sort and return results

No model training. No complex infrastructure.
Event embeddings are computed once and stored anywhere.
Queries are embedded at search time.

And… voilà.
No model training.
No magic.
Just a different way to represent text.

Operation Logic

We'll place the operation logic in a separate class, SemanticEventSearch. This class doesn't claim to be the best code on the planet, and is written for demonstration purposes only - so we'll omit any comments on its quality.

final class SemanticEventSearch
{
    private string $model = 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
    private string $cachePath;
    private string $defaultQuery = 'санкции против IT-компаний';
    private int $topN;

    private ?string $query = null;

    /** @var list<array{id:int,title:string,description:string}> */
    private array $events;

    /** @var array<int, list<float|int>> */
    private array $eventEmbeddingsById = [];

    private $embedder;

    /**
     * Create a new semantic search instance.
     *
     * @param int $topN Number of results to return.
     */
    public function __construct(int $topN = 3)
    {
        $this->cachePath = __DIR__ . '/../embeddings.events.json';
        $this->events = [];
        $this->embedder = null;
        $this->topN = $topN;
    }

    /**
     * Inject events that will be indexed/searched.
     *
     * @param list<array{id:int,title:string,description:string}> $events
     * @return $this
     */
    public function setEvents(array $events): self
    {
        $this->events = $events;
        $this->eventEmbeddingsById = [];
        return $this;
    }

    /**
     * Set the embeddings model identifier.
     *
     * Switching model invalidates in-memory embeddings.
     *
     * @param string $model
     * @return $this
     */
    public function setModel(string $model): self
    {
        $this->model = $model;
        $this->embedder = null;
        $this->eventEmbeddingsById = [];
        return $this;
    }

    /**
     * Set the query to be searched.
     *
     * @param string $query
     * @return $this
     */
    public function setQuery(string $query): self
    {
        $q = trim($query);
        $this->query = $q === '' ? null : $q;
        return $this;
    }

    /**
     * Run the end-to-end semantic search pipeline (cache -> embed query -> score -> top-N).
     *
     * @return array{query:string,results:list<array{score:float,event:array{id:int,title:string,description:string}}>}
     * @throws RuntimeException If events are not set or embeddings output is unexpected.
     */
    public function run(): array
    {
        if (count($this->events) === 0) {
            throw new RuntimeException('Events list is empty. Call setEvents() before run().');
        }

        if ($this->embedder === null) {
            $this->embedder = pipeline('embeddings', $this->model);
        }

        $this->loadEmbeddingsFromCacheIfCompatible();
        $this->ensureAllEventEmbeddings();

        $query = $this->query ?? $this->defaultQuery;
        $queryVec = $this->embedText($query);

        $results = $this->search($queryVec);
        return [
            'query' => $query,
            'results' => $results,
        ];
    }

    /**
     * Compute an embedding vector for a single text.
     *
     * @param string $text
     * @return list<float|int>
     * @throws RuntimeException
     */
    private function embedText(string $text): array
    {
        $emb = ($this->embedder)($text, normalize: true, pooling: 'mean');
        if (!is_array($emb) || !isset($emb[0]) || !is_array($emb[0])) {
            throw new RuntimeException('Unexpected embeddings output format');
        }

        return $emb[0];
    }

    /**
     * Cosine similarity between two vectors.
     *
     * @param list<float|int> $a
     * @param list<float|int> $b
     * @return float
     */
    private function cosineSimilarity(array $a, array $b): float
    {
        $n = min(count($a), count($b));

        $dot = 0.0;
        $normA = 0.0;
        $normB = 0.0;

        for ($i = 0; $i < $n; $i++) {
            $x = (float) $a[$i];
            $y = (float) $b[$i];

            $dot += $x * $y;
            $normA += $x * $x;
            $normB += $y * $y;
        }

        if ($normA <= 0.0 || $normB <= 0.0) {
            return 0.0;
        }

        return $dot / (sqrt($normA) * sqrt($normB));
    }

    /**
     * Load a JSON file and decode to array.
     *
     * @param string $path
     * @return array|null
     */
    private function loadJsonFile(string $path): ?array
    {
        if (!is_file($path)) {
            return null;
        }

        $raw = file_get_contents($path);
        if ($raw === false) {
            return null;
        }

        $data = json_decode($raw, true);
        return is_array($data) ? $data : null;
    }

    /**
     * Encode and save data to JSON file.
     *
     * @param string $path
     * @param array $data
     * @throws RuntimeException
     */
    private function saveJsonFile(string $path, array $data): void
    {
        $json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
        if ($json === false) {
            throw new RuntimeException('Failed to encode JSON');
        }

        $ok = file_put_contents($path, $json);
        if ($ok === false) {
            throw new RuntimeException('Failed to write cache file: ' . $path);
        }
    }

    /**
     * Load cached event embeddings only if they were produced by the current model.
     *
     * @return void
     */
    private function loadEmbeddingsFromCacheIfCompatible(): void
    {
        $cached = $this->loadJsonFile($this->cachePath);

        if (!is_array($cached) || !isset($cached['model'], $cached['events']) || !is_array($cached['events'])) {
            return;
        }

        if ($cached['model'] !== $this->model) {
            return;
        }

        foreach ($cached['events'] as $row) {
            if (isset($row['id'], $row['embedding']) && is_array($row['embedding'])) {
                $this->eventEmbeddingsById[(int) $row['id']] = $row['embedding'];
            }
        }
    }

    /**
     * Ensure embeddings exist for all events and persist them to cache.
     *
     * @return void
     * @throws RuntimeException
     */
    private function ensureAllEventEmbeddings(): void
    {
        $missing = [];
        foreach ($this->events as $event) {
            $id = (int) $event['id'];
            if (!isset($this->eventEmbeddingsById[$id])) {
                $missing[] = $event;
            }
        }

        if (count($missing) === 0) {
            return;
        }

        foreach ($missing as $event) {
            $id = (int) $event['id'];
            $text = (string) $event['description'];

            $this->eventEmbeddingsById[$id] = $this->embedText($text);
        }

        $toCache = [
            'model' => $this->model,
            'events' => array_values(array_map(
                fn(array $event): array => [
                    'id' => (int) $event['id'],
                    'embedding' => $this->eventEmbeddingsById[(int) $event['id']],
                ],
                $this->events
            )),
        ];

        $this->saveJsonFile($this->cachePath, $toCache);
    }

    /**
     * Score all events against the query embedding and return the top-N results.
     *
     * @param list<float|int> $queryVec
     * @return list<array{score:float,event:array{id:int,title:string,description:string}}>
     */
    private function search(array $queryVec): array
    {
        $scored = [];

        foreach ($this->events as $event) {
            $id = (int) $event['id'];
            $score = $this->cosineSimilarity($queryVec, $this->eventEmbeddingsById[$id]);

            $scored[] = [
                'score' => $score,
                'event' => $event,
            ];
        }

        usort($scored, static fn(array $a, array $b): int => $b['score'] <=> $a['score']);

        return array_slice($scored, 0, $this->topN);
    }

    /**
     * Render results as plain text.
     *
     * @param string $query
     * @param list<array{score:float,event:array{id:int,title:string,description:string}}> $results
     * @return void
     */
    public function render(string $query, array $results): void
    {
        echo "Query: {$query}\n\n";
        foreach ($results as $row) {
            $event = $row['event'];
            $score = (float) $row['score'];

            echo "[" . number_format($score, 4) . "] #{$event['id']} {$event['title']}\n";
            echo "  {$event['description']}\n\n";
        }
    }
}

Data Preparing

Let's assume this is our data, collected from various sources. For simplicity, let's place it in an array.

$events = [
    [
        'id' => 1,
        'title' => 'Restrictions Against Technology Corporations',
        'description' => 'New economic measures have been introduced against major technology companies.',
    ],
    [
        'id' => 2,
        'title' => 'Development of Space Programs',
        'description' => 'Several countries in the region have increased funding for national satellite projects.',
    ],
    [
        'id' => 3,
        'title' => 'Escalation of Political Conflict',
        'description' => 'An escalation of politically motivated conflict has occurred in several provinces.',
    ],
    [
        'id' => 4,
        'title' => 'Restrictions Against the IT Sector',
        'description' => 'The government announced new restrictions for companies operating in the information technology sector.',
    ],
    [
        'id' => 5,
        'title' => 'Rising Inflation and Key Interest Rate Review',
        'description' => 'The central bank raised the key interest rate amid accelerating inflation and rising prices of imported goods.',
    ],
    [
        'id' => 6,
        'title' => 'Launch of a Small Business Support Program',
        'description' => 'Authorities announced preferential loans and tax incentives for small and medium-sized businesses in the regions.',
    ],
    [
        'id' => 8,
        'title' => 'Data Breach in Online Retail',
        'description' => 'An online retailer is investigating a leak of customers' personal data following the compromise of employee accounts.',
    ],
    [
        'id' => 9,
        'title' => 'Medical Breakthrough: New Diagnostic Method',
        'description' => 'Researchers presented a method for early disease diagnosis using biomarkers, significantly reducing analysis time.',
    ],
    [
        'id' => 10,
        'title' => 'Seasonal Increase in Illness Rates',
        'description' => 'Several cities have reported a rise in respiratory infections, with clinics increasing patient intake.',
    ],
    [
        'id' => 12,
        'title' => 'Drought and Risks to Agriculture',
        'description' => 'Due to prolonged drought, farmers predict lower crop yields, and support measures for agriculture are being discussed.',
    ],
    [
        'id' => 13,
        'title' => 'Final of a Major Sports Tournament',
        'description' => 'In the decisive match of the season, the team secured victory in extra time, setting a new attendance record.',
    ],
    [
        'id' => 14,
        'title' => 'Player Transfer and Squad Reinforcement',
        'description' => 'The club signed a new striker, aiming to strengthen its attacking line ahead of a series of derby matches.',
    ],
    [
        'id' => 15,
        'title' => 'New Rules for Marketplaces',
        'description' => 'The regulator proposed requirements for product labeling and commission transparency on online trading platforms.',
    ],
    [
        'id' => 17,
        'title' => 'Disruptions in Semiconductor Supply',
        'description' => 'Electronics manufacturers warned of chip supply delays due to export restrictions and factory overloads.',
    ],
    [
        'id' => 18,
        'title' => 'Opening of a Contemporary Art Festival',
        'description' => 'A contemporary art festival has opened in the capital, featuring exhibitions, performances, and artist lectures.',
    ],
    [
        'id' => 19,
        'title' => 'Major Deal in the Real Estate Market',
        'description' => 'An investment fund acquired a portfolio of commercial real estate, planning renovation and improved energy efficiency.',
    ],
    [
        'id' => 20,
        'title' => 'Ocean Research and New Findings',
        'description' => 'A scientific expedition collected data on ocean currents and water temperature, refining climate change forecasts.',
    ],
];

Run the example

It's simple here: just run our code and wait for the results.

require_once __DIR__ . '/../vendor/autoload.php';

use function Codewithkyrian\Transformers\Pipelines\pipeline;

final class SemanticEventSearch {...}

$events = [...];

$query = 'sanctions against IT companies';

$search = new SemanticEventSearch(topN: 3);
$search->setModel('Xenova/paraphrase-multilingual-MiniLM-L12-v2');
$search->setEvents($events);
$search->setQuery($query);
$out = $search->run();
$search->render($out['query'], $out['results']);

Result

The output matches by meaning, not words. The first result is the most suitable for the population with our request.

Query: sanctions against IT companies
[0.4288] #4 Restrictions against the IT sector
  The government announced new restrictions for companies operating in the IT industry.
[0.3356] #15 New rules for marketplaces
  The regulator proposed requirements for product labeling and commission transparency.
[0.2598] #8 Data breach in online retail
  An online store investigates a customer data leak after account compromise.

Production Use Cases

This already looks like a product approach, not an experiment.
And it has useful properties:

weak dependence on exact wording
works well with short texts
easily combined with classic filters (date, region, type)

This is not "AI for the sake of AI", but practical, explainable, debuggable logic.

Limitations and Caveats

This is not a silver bullet.

Models are large. Performance matters. Some problems are still better solved with plain SQL.

But that's a normal engineering discussion - about trade-offs, not magic or black boxes.

Where to Go Next

For me, TransformersPHP is a strong example that AI can be used directly in PHP projects without changing the stack or introducing Python.

In my open and free book "AI for PHP Developers", I explore similar cases: when it makes sense, how to choose models, and how not to turn a project into a collection of experimental features.

All examples can be downloaded and run using a ready-made Docker environment from GitHub repository:
https://github.com/apphp/ai-for-php-developers-examples

You can also run all examples from the book directly:
https://aiwithphp.org/books/ai-for-php-developers/examples

If the topic resonates - I'd be glad to discuss and get feedback.
Especially interesting to hear what tasks you already solve (or want to solve) with AI in PHP projects.

Machine Learning Ecosystem in PHP

Samuel Akopyan — Thu, 25 Dec 2025 15:02:19 +0000

The PHP Machine Learning Ecosystem: A Practical Overview

When people say “there is no machine learning in PHP”, they usually mix up two very different things.

It’s true that PHP is rarely used to train large neural networks from scratch. But PHP has been living comfortably for years in the world of model application, vector operations, statistics, classification, embeddings, and numerical computing.

The PHP ML ecosystem is not loud — but it is mature.

It consists of four layers:

Classical ML libraries
Mathematical foundations
Integration tools for modern ML systems
Integration with external ML services

Let’s walk through them step by step.

Classical Machine Learning in PHP

We’ll start with libraries that implement ML algorithms directly in PHP, without calling external services.

PHP-ML

Repository:
https://github.com/jorgecasas/php-ml
Status: Mostly unmaintained

PHP-ML is the traditional entry point into machine learning with PHP. It contains the full classic ML toolbox:

k-Nearest Neighbors
Linear and logistic regression
Naive Bayes
Support Vector Machines
Decision trees
k-means clustering

The philosophy of PHP-ML is important to understand. It does not try to compete with PyTorch or scikit-learn in performance. Its goal is clarity.

The code is easy to read, easy to debug, and easy to explain. From a learning and educational perspective, this is a huge advantage.

A typical use case looks like this:

You extract features from a database
Train a simple classification or regression model
Serialize it
Use it at runtime without any external ML service

The resulting code feels almost textbook-like — and that’s a feature, not a bug. You can reason about the model and explain the math behind it without hidden magic.

The example looks almost textbook:

use Phpml\Classification\KNearestNeighbors;

$classifier = new KNearestNeighbors();
$classifier->train($samples, $labels);

$result = $classifier->predict([3, 7]);

And this is, in fact, a huge plus. The code is transparent, the model can be debugged, and the mathematical meaning of the algorithm is easy to explain.

If PHP-ML is a textbook, then the next library is an engineering tool.

Rubix ML

Website & Repository:
https://github.com/RubixML
Status: Actively maintained

Rubix ML is a full-featured ML framework for PHP. It focuses on production-grade pipelines, not demos.

Key features include:

Classification, regression, clustering
First-class Dataset objects
Transformers and feature scaling
Model serialization
Reproducible pipelines

Let's see how this works in practice.
Let's say we have data for binary classification.

use Rubix\ML\Datasets\Labeled;
use Rubix\ML\Classifiers\KNearestNeighbors;

$samples = [
    [170, 65],
    [160, 50],
    [180, 80],
    [175, 70],
];

$labels = ['M', 'F', 'M', 'M'];

$dataset = new Labeled($samples, $labels);

$model = new KNearestNeighbors(3);
$model->train($dataset);

$prediction = $model->predict([[172, 68]]);

One important design decision stands out:
You don’t pass raw arrays into models — you work with structured datasets.

This enforces a mental shift from “script hacking” to “ML engineering”.

Rubix is often chosen when a model is not an experiment, but a long-lived part of a production system, where versioning, repeatability, and stability matter.

Linear Algebra and Numerical Foundations

All machine learning eventually boils down to vectors, matrices, and tensors. PHP has several solid options here.

RubixML/Tensor

Repository:
https://github.com/RubixML/Tensor
Status: Active

RubixML/Tensor is a low-level linear algebra library optimized specifically for ML workloads.

It provides:

Tensors and matrices
Element-wise operations
Decompositions and transformations

If Rubix ML is the brain, Tensor is the muscle.

This library is crucial when you care about predictable memory usage and performance, not just correctness.

MathPHP

Repository:
https://github.com/markrogoyski/math-php
Status: Active

MathPHP is a general-purpose mathematical library written in pure PHP.

It includes:

Linear algebra
Statistics
Probability distributions
Numerical methods

In ML projects, MathPHP is often used as a supporting foundation: distance metrics, normalization, statistical estimates, hypothesis testing.

It’s especially valuable because it implements math honestly — without hidden optimizations or abstractions.

NumPower

Repository:
https://github.com/RubixML/numpower
Status: Active

NumPower is a special case.

It’s a PHP extension for high-performance numerical computing, inspired by NumPy. It uses AVX2 instructions on x86-64 CPUs and supports CUDA for GPU computation.

This answers a common question:

“Can PHP do real scientific computing?”

Yes — if you’re willing to use extensions and specialized infrastructure.

NumPower is relevant when PHP is not just a web layer, but a computational engine.

NumPHP and SciPhp

NumPHP: https://numphp.org
SciPhp: https://sciphp.org Status: Unmaintained

These NumPy-inspired libraries are mostly of historical interest today. They show that scientific computing ideas in PHP existed long before the current AI hype.

Modern ML Integrations: Tokens, Embeddings, Data Pipelines

Modern ML rarely lives in isolation. Around every model, there’s infrastructure.

tiktoken-php

Repository:
https://github.com/yethee/tiktoken-php
Status: Active

tiktoken-php is a PHP port of OpenAI’s tokenizer.

It allows you to:

Count tokens
Split text correctly
Estimate request costs
Control context length

If you work with GPT, Claude, or Gemini from PHP, this library is almost mandatory.

Rindow Math Matrix

Repository:
https://github.com/rindow/rindow-math-matrix
Status: Active

A linear algebra library focused on ML and numerical methods, often used within the Rindow ecosystem.

A good choice if you want strict mathematical APIs and precise control over numerical behavior.

Flow PHP

Repository:
https://github.com/flow-php/flow
Status: Active

Flow PHP is not an ML library — it’s a data processing framework.

It handles:

ETL pipelines
Data transformations
Validation
Streaming workflows

In real ML systems, data preparation is often harder than modeling. Flow PHP fills the gap between “raw data exists” and “the model can consume it”.

Integration with External ML Services

The most common way to use ML in PHP today is inference via APIs.

LLM APIs: OpenAI, Anthropic, Gemini

PHP SDKs and HTTP clients allow PHP applications to consume:

Embeddings
Classification
Text generation
Summarization
Structured data extraction

Architecturally, this means:

The model lives elsewhere
PHP controls when and why it’s used

This plays perfectly to PHP’s strengths: queues, databases, caching, billing, UI, and orchestration.

ONNX Runtime and Model Inference

ONNX deserves special mention.

Models can be trained in Python, exported to ONNX, and executed from PHP via extensions or external runtimes.

This is a rare but powerful setup:
no Python in production, but full control over inference inside PHP applications.

Computer Vision and Signal Processing

PHP is not a leader here, but basic tooling exists.

OpenCV can be used via bindings or CLI calls, with PHP acting as the orchestration layer. This pattern is typical: PHP doesn’t do the heavy math — it coordinates it.

How to Read the PHP ML Ecosystem as a Whole

One key conclusion matters.

PHP is not a language for ML benchmarks or Kaggle competitions.

It’s a language for connecting machine learning to real products.

Its ML ecosystem prioritizes:

Code clarity
Integration
Data control
Predictable behavior

If you understand the math behind a model, PHP gives you enough tools to use it in production.

In that sense, PHP’s ML ecosystem is not weak — it’s honest and practical.

PHP and machine learning are about roles in a system:

Applying models
Working with embeddings and vectors
Classification and ranking
Orchestrating ML services
Connecting math with business logic

That’s why PHP’s ML ecosystem isn’t a monolith — it’s a precise toolbox.

And for many real-world systems, that’s exactly what you want.

For a broader view of the PHP machine learning ecosystem and ongoing experiments, you can explore Awesome PHP ML—a curated collection of libraries, tools, and projects focused on machine learning in PHP. It’s a great starting point for discovering what’s currently available and actively developed:
https://github.com/apphp/awesome-php-ml

Introducing PrettyPrint — a PHP array pretty-printer with Python-/PyTorch-style formatting

Samuel Akopyan — Sat, 22 Nov 2025 15:46:46 +0000

I'm excited to announce PrettyPrint, a small, zero-dependency PHP utility designed to format numeric arrays in a clean, readable style inspired by Python and the tensor-views you’ll see in PyTorch.

Whether you're doing ML experiments, debugging data pipelines, logging arrays, or building educational tools, PrettyPrint makes it easier to inspect array data in a structured way.

Why use PrettyPrint?

No extra dependencies - just pure PHP.

Supports aligned 2D tables, summarized tensor-style views (for larger arrays), 3D tensor with head/tail blocks, and flexible output options (labels, controlling newline behaviour, etc.).

Makes your array dumps more readable and visually helpful.

Quick Start & Examples

Installation

composer require apphp/pretty-print

Global helper functions

You can use the pprint() helper function for quick prints:

Print scalars/strings

pprint('Hello', 123, 4.56);
// Output:
// Hello 123 4.5600

1D / 2D examples

// Print multiple 1D rows aligned as a 2D table
pprint([1, 23, 456], [12, 3, 45]);
// Output:
// [[  1,  23, 456],
//  [12,   3,  45]]

Label + 2D matrix

pprint('Confusion matrix:', [[1,23], [456,7]]);
// Output:
// Confusion matrix:
// [[   1,  23],
//  [ 456,   7]]

Tensor / summarization example

$matrix = [
    [1, 2,  3,  4,  5],
    [6, 7,  8,  9, 10],
    [11,12, 13, 14, 15],
];
pprint($matrix);
// Output:
// tensor([
//   [  1,   2,   3,   4,   5],
//   [  6,   7,   8,   9,  10],
//   [ 11,  12,  13,  14,  15]
// ])

And for summarization (showing just head + tail of rows/cols):

pprint($matrix, headRows:1, tailRows:1, headCols:2, tailCols:2);
// Output:
// tensor([
//   [  1,   2,  ...,   4,   5],
//   ...,
//   [ 11,  12,  ...,  14,  15]
// ])

You can even print 3D tensor-like structures with summarised blocks:

$tensor3d = [
    [[1,2,3],[4,5,6]],
    [[7,8,9],[10,11,12]],
    [[13,14,15],[16,17,18]],
];
pprint($tensor3d, headB:1, tailB:1, headRows:1, tailRows:1, headCols:1, tailCols:1);
// Output:
// tensor([
//  [[ 1,  ...,  3],
//   [ 4,  ...,  6]],
//
//  ...,
//
//  [[13,  ..., 15],
//   [16,  ..., 18]]
// ])

Object-style usage

If you prefer, you can instantiate the printer as an object:

use Apphp\PrettyPrint\PrettyPrint;

$pp = new PrettyPrint();
$pp('Hello', 42);       // same as pprint('Hello', 42)

$pp($tensor3d, headB:2, tailB:1, headRows:1, tailRows:1, headCols:1, tailCols:1);
$pp('Metrics:', [[0.91, 0.02], [0.03, 0.88]]);

Options reference

Here are a few of the core options you can pass:

end (string) — line terminator (default: newline)
headB / tailB (ints) — number of 2D blocks shown for 3D tensors
headRows / tailRows — number of head/tail rows per slice with ellipsis between
headCols / tailCols — number of head/tail columns per slice with ellipsis between

Named-argument syntax (PHP 8+) is supported, or you can pass an array of options as last parameter.

Where it shines

ML/AI workflows: When you have numeric arrays or tensors in PHP (or imported from elsewhere) and want human-readable dumps.

Debugging & logging: Replace ad-hoc var_dump() or print_r() with structured, aligned table views.

Educational/teaching code: When showing matrix/tensor examples and you want a cleaner presentation.

CLI & scripts: For quick visual inspection of matrices/tensors in terminal output.

Final thoughts

I believe PrettyPrint fills a small but useful niche for PHP developers working with numeric data or coming from Python/PyTorch mindsets - offering readability, alignment, summarization, and minimal overhead.

Give it a spin:

GitHub: https://github.com/apphp/pretty-print
Packagist: https://packagist.org/packages/apphp/pretty-print

I'd love your feedback, suggestions for enhancements, or contributions — open an issue or PR and let’s make this tool even better together!

Happy coding!

Building a simple RAG system in PHP with the Neuron AI framework in one evening

Samuel Akopyan — Sat, 15 Nov 2025 20:58:11 +0000

RAG (Retrieval-Augmented Generation) is an AI method that combines a large language model (LLM) with an external knowledge base to produce more accurate, context-aware answers. The idea is simple: first we retrieve relevant information from documents or data sources, then we pass this information to an LLM to generate the final response. This approach reduces hallucinations, improves accuracy, and allows you to update the knowledge base without expensive retraining.

Today, we’ll look at how to build a basic RAG system in PHP (yes, really!) using the Neuron AI framework. This will be a small proof-of-concept: minimal, but fully functional.

Ready to generate something useful?

1. What RAG Is and Why You Need It

In short: RAG helps an AI system avoid guessing by fetching real data before generating an answer.

The classical flow has two steps:

Retrieval — find relevant document chunks using vector search.
Generation — create an answer using the retrieved data.

There are many variations of RAG — from simple “vector search + LLM” to complex systems with re-ranking, context caching, and chain-of-thought (better not use that in production). If you want a deep dive, the internet is full of good articles explaining the history and evolution of RAG (the approach started taking shape around 2020).

Typical Use Cases

internal chatbots for documentation search
voice assistants
helpdesk support bots
or simply impressing your colleagues

2. Why PHP and Neuron AI?

Good question.

Of course, you can build RAG in Python using LangChain, LlamaIndex, Milvus, Chroma, etc. There are plenty of tutorials. But if your whole web project already runs on PHP, why bring in Python just for vector search?

Neuron AI is a lightweight PHP framework that brings embeddings, LLMs, and even a local VectorStore into the PHP world. I wrote about it earlier, and this article continues with a real, practical example.

It’s simple, easy to integrate, and fits naturally into existing PHP applications — very much in the spirit of Laravel, but for AI.

3. What We’re Building

We’ll create an AI agent that can answer questions using your internal knowledge base.

Technically, we’ll build a basic RAG system that:

creates a vector store from documents
searches relevant chunks (returns the top-K closest vectors)
generates an answer using the retrieved data

Imagine you have internal Wiki or Confluence docs and want a bot that can answer questions about them. This is exactly what RAG was designed for — especially useful for newcomers who still see your documentation as “Terra Incognita”.

4. Step-by-Step with Code

4.1 Requirements

PHP 8.2+
Composer
Neuron AI (composer require neuron-ai/neuron)
LLM API key (OpenAI, etc.)

4.2 Why FileVectorStore?

For this example, we won’t use vector databases like Faiss or Pinecone. A simple FileVectorStore is enough — it stores everything in a .store file.

It’s not scalable, but perfect for demos or small local projects with a few thousand documents.

4.3 Installation and Setup

Install packages:

composer require neuron-ai/neuron
composer require openai-php/laravel

Project structure:

/demo/
  ├── store/
  │    ├── docs/
  ├── src/
  │    ├── Commands/
  │    ├── Classes/
  └── index.php

4.4 Preparing the Documents

Place four Markdown documents inside store/docs/:

company-culture.md
company-overview.md
services-portfolio.md
technical-expertise.md

They describe a company: culture, overview, services, and technical expertise.

4.5 Creating the VectorStore

Example class: src/Classes/PopulateVectorStore.php

namespace App\demo\src\Classes;
require_once __DIR__ . '/../../../../vendor/autoload.php';

use NeuronAI\RAG\DataLoader\FileDataLoader;
use OpenAI\Factory;

class PopulateVectorStore {
    public static function populate(): void {
        $vectorDir = __DIR__ . '/../../store';
        $storeFile = $vectorDir . '/demo.store';
        $metaFile = $vectorDir . '/demo.meta.json';

        // Ensure directory exists
        if (!is_dir($vectorDir)) {
            mkdir($vectorDir, 0755, true);
        }

        // Clear existing store
        file_put_contents($storeFile, '');

        // Initialize OpenAI client
        $apiKey ='<your-OPENAI_API_KEY-here>';
        if (!is_string($apiKey) || trim($apiKey) === '') {
            throw new \RuntimeException('OpenAI API key not configured. Ensure OPENAI_API_KEY is set.');
        }
        $client = (new Factory())
            ->withApiKey($apiKey)
            ->make();

        $model = 'text-embedding-3-small';

        // Probe expected dimension once
        $expectedDim = 1536;

        // Docs
        $documents = FileDataLoader::for($vectorDir . '/docs')->getDocuments();

        $written = 0;
        // Generate embeddings and write to store
        foreach ($documents as $document) {
            $content = $document->getContent();

            // Get embedding from OpenAI
            try {
                $response = $client->embeddings()->create([
                    'model' => $model,
                    'input' => $content,
                    'dimensions' => $expectedDim,
                ]);

                // SDK v0.12+ exposes embeddings via `$response->embeddings`
                if (isset($response->embeddings[0]->embedding)) {
                    $embedding = $response->embeddings[0]->embedding;
                } else {
                    // Fallback for array casting if SDK shape changes
                    $arr = method_exists($response, 'toArray') ? $response->toArray() : [];
                    if (isset($arr['data'][0]['embedding'])) {
                        $embedding = $arr['data'][0]['embedding'];
                    } else {
                        throw new \RuntimeException('Unable to parse embedding from OpenAI response');
                    }
                }
            } catch (\Throwable $e) {
                throw new \RuntimeException('Failed to generate embedding: ' . $e->getMessage());
            }

            // Normalize and validate embedding
            if (!is_array($embedding)) {
                echo "! Skipped document due to invalid embedding type.\n";
                continue;
            }
            $embedding = array_map(static function ($v) {
                return is_numeric($v) ? (float)$v : 0.0;
            }, $embedding);

            if (count($embedding) !== $expectedDim) {
                echo "! Skipped document due to dimension mismatch (got " . count($embedding) . ", expected $expectedDim).\n";
                continue;
            }

            // Write as JSON line to store file (strict JSONL)
            // FileVectorStore expects all fields at top level
            $jsonLine = json_encode([
                'embedding' => $embedding,
                'content' => $content,
                'sourceType' => $document->getSourceType(),
                'sourceName' => $document->getSourceName(),
                'id' => md5($content),
                'metadata' => [],
            ], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

            file_put_contents($storeFile, $jsonLine . "\n", FILE_APPEND);
            $written++;

            echo "✓ Added embedding ($written) for: " . $storeFile . " | " . str_replace("\n", ' ', substr(trim($content), 0, 70)) . "...\n";
        }

        // Write metadata file for consistency checks
        $meta = [
            'model' => $model,
            'dimension' => $expectedDim,
            'generatedAt' => date(DATE_ATOM),
            'count' => $written,
        ];
        file_put_contents($metaFile, json_encode($meta, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT));

        echo "\n✓ Vector store populated with $written documents (dimension: $expectedDim)\n";
    }
}

Run the script via index.php:

use App\demo\src\Classes\PopulateVectorStore;

require_once __DIR__ . '/src/Classes/PopulateVectorStore.php';

PopulateVectorStore::populate();

You should see logs like:

php app/demo/index.php
✓ Added embedding (1) for: /app/demo/src/Commands/../../store/demo.store | # Linx Team - Company Culture & Values  ## Core Values  ### Innovation...
✓ Added embedding (2) for: /app/demo/src/Commands/../../store/demo.store | ## Work Environment  ### Remote-Friendly We offer flexible work arrang...
✓ Added embedding (3) for: /app/demo/src/Commands/../../store/demo.store | ## Benefits  ### Competitive Compensation We offer competitive salarie...
✓ Added embedding (4) for: /app/demo/src/Commands/../../store/demo.store | # Linx Team - Company Overview  ## About Us Linx Team is a leading sof...
✓ Added embedding (5) for: /app/demo/src/Commands/../../store/demo.store | # Linx Team - Services & Portfolio  ## Services Offered  ### Custom So...
✓ Added embedding (6) for: /app/demo/src/Commands/../../store/demo.store | ### DevOps & Infrastructure Managing cloud infrastructure, implementin...
✓ Added embedding (7) for: /app/demo/src/Commands/../../store/demo.store | # Linx Team - Technical Expertise  ## Core Technologies  ### Backend D...
✓ Added embedding (8) for: /app/demo/src/Commands/../../store/demo.store | js** - React framework with server-side rendering  ### Cloud & DevOps ...

✓ Vector store populated with 8 documents (dimension: 1536)

Two new files will appear:

demo.meta.json — metadata
demo.store — actual vector entries

Let's take a look at demo.meta.json - everything is clear here.

{
    "model": "text-embedding-3-small",
    "dimension": 1536,
    "generatedAt": "2025-11-15T13:28:53+00:00",
    "count": 8
}

and in demo.store we will see the following:

{"embedding":[-0.02263086,-0.007472924,0.029841794,...],"content":"# Linx Team - ... ","sourceType":"files","sourceName":"company-culture.md","id":"28b40662dad319d6f5718881af03283b","metadata":[]}
{"embedding":[-0.023948364,0.009718814,0.06337647,...],"content":"## Work Enviro ... ","sourceType":"files","sourceName":"company-culture.md","id":"b96cd133b0df26e64b95acdad75c87dd","metadata":[]}
{"embedding":[-0.018617272,0.00053190015,0.095444225,...],"content":"## Benefits\n\n### ...","sourceType":"files","sourceName":"company-culture.md","id":"42041e1af0580a58ae07d6523649b1a9","metadata":[]}
{"embedding":[-0.04209091,-0.006933485,0.03687242,...],"content":"# Linx Team - Company ...","sourceType":"files","sourceName":"company-overview.md","id":"8622e016e3fbeccc8dc10bf9a3a851a6","metadata":[]}
{"embedding":[-0.026189856,-0.0032917524,0.05449412,...],"content":"# Linx Team - Services ...","sourceType":"files","sourceName":"services-portfolio.md","id":"acc30742cf9f55588db5275c4feba183","metadata":[]}
{"embedding":[0.0018354928,-0.009989895,0.04954025,...],"content":"### DevOps & ...","sourceType":"files","sourceName":"services-portfolio.md","id":"d32de0136fdd56991a8ab738c49558a2","metadata":[]}
{"embedding":[-0.06210507,-0.015794381,0.038876604,...],"content":"# Linx Team - ...","sourceType":"files","sourceName":"technical-expertise.md","id":"dff18ab4ded5f65154cdd6e81c49318c","metadata":[]}
{"embedding":[-0.02210143,0.016823476,0.038901344,...],"content":"js** - React framework ...","sourceType":"files","sourceName":"technical-expertise.md","id":"a167473a1d4eeac021fbe9bf2ccd0726","metadata":[]}

Each line in demo.store is a JSON object:

{
  "embedding": [...],
  "content": "....",
  "sourceType": "files",
  "sourceName": "company-culture.md",
  "id": "28b40662dad319d6f5718881af03283b",
  "metadata": []
}

Why 8 entries from 4 documents?

Because the documents are automatically split into chunks before generating embeddings. Each chunk gets its own vector.

Reasons:

embeddings work best on short, coherent text pieces
LLMs have token limits
retrieval becomes more precise

The dimension: 1536 value comes from the OpenAI embedding model (text-embedding-3-small).

4.6 Creating the ChatBot

Create the agent class: src/Commands/ChatBot.php.

<?php

namespace App\demo\src\Commands;
require_once __DIR__ . '/../../../../vendor/autoload.php';

use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAI\OpenAI;
use NeuronAI\RAG\Embeddings\EmbeddingsProviderInterface;
use NeuronAI\RAG\Embeddings\OpenAIEmbeddingsProvider;
use NeuronAI\RAG\RAG;
use NeuronAI\RAG\VectorStore\FileVectorStore;
use NeuronAI\RAG\VectorStore\VectorStoreInterface;

class ChatBot extends RAG
{
    private string $apiKey ='<your-OPENAI_API_KEY-here>';
    private string $model = 'gpt-4o-mini';

    protected function provider(): AIProviderInterface
    {
        if (!$this->apiKey) {
            throw new \Exception('OPENAI_API_KEY environment variable is not set');
        }

        return new OpenAI(
            $this->apiKey,
            $this->model,
        );
    }

    protected function embeddings(): EmbeddingsProviderInterface
    {
        if (!$this->apiKey) {
            throw new \Exception('OPENAI_API_KEY environment variable is not set');
        }

        return new OpenAIEmbeddingsProvider(
            key: $this->apiKey,
            model: 'text-embedding-3-small',
            dimensions: 1536
        );
    }

    protected function vectorStore(): VectorStoreInterface
    {
        $vectorDir = __DIR__ . '/../../store';

        // Ensure the vectors directory exists
        if (!is_dir($vectorDir)) {
            mkdir($vectorDir, 0755, true);
        }

        // Ensure the store file exists with at least one empty line to prevent parsing errors
        $storeFile = $vectorDir . '/demo.store';
        if (!file_exists($storeFile) || filesize($storeFile) === 0) {
            // Create an empty store file - FileVectorStore will populate it when documents are added
            file_put_contents($storeFile, '');
        }

        return new FileVectorStore(
            directory: $vectorDir,
            name: 'demo',
            topK: 3
        );
    }
}

Then update your index.php to run the chatbot:

use App\demo\src\Classes\PopulateVectorStore;
use App\demo\src\Commands\ChatBot;
use NeuronAI\Chat\Messages\UserMessage;

require_once __DIR__ . '/../../vendor/autoload.php';

// Populate the vector store if it doesn't exist
$storeFile = __DIR__ . '/store/demo.store';
if (!file_exists($storeFile) || filesize($storeFile) === 0) {
    PopulateVectorStore::populate();
    echo "Vector store populated successfully.\n";
} else {
    echo "Vector store found, start handling...\n";
}

$chatBot = ChatBot::make();
$response = $chatBot->chat(
    new UserMessage('How many employees and managers does the company have?')
);

echo "\n" . $response->getContent() . "\n";

Example output:

The company has over 27 employees and 2 managers, making a total of more than 29 team members.

Another example question

new UserMessage(
   'How many employees and managers does the company have? ' .
   'Provide links to most relevant documents.'
);

returns not only the answer but also recommended documents:

The company has over 27 employees and 2 managers.
For more detailed information, you can refer to the following documents:

Company Overview: company-overview.md
Company Culture: company-culture.md

About topK: 3

topK determines how many closest vectors to return from the vector store. More chunks = richer context, but also slower queries.

So, after all this, the final structure of the project looks like this:

/demo/
  ├── store/
  │    ├── docs/
  │    │    ├── company-culture.md
  │    │    ├── company-overview.md
  │    │    ├── services-portfolio.md
  │    │    ├── technical-expertise.md
  │    │    ├── ...
  │    ├── demo.meta.json
  │    ├── demo.store
  ├── src/
  │    ├── Commands/
  │    │    ├── ChatBot.php
  │    ├── Classes/
  │    │    ├── PopulateVectorStore.php
  └── index.php

5. What Can Be Improved

This was just a basic example. You can add:

real databases (PostgreSQL, Pinecone, Qdrant)
automatic indexing of new Wiki pages
caching for common questions
request logging for analytics and debugging

6. Advanced Version: Add Re-Ranking

For higher accuracy, add document re-ranking using a model like bge-reranker-base. Neuron AI supports this, and the improvement in answer quality is quite noticeable.

7. Modular Architecture: When You Need It

If RAG is just a small feature, keep things simple.
But if the project grows, separate:

VectorStoreService
EmbeddingPipeline
RAGPipeline
ChatController

This lets you switch components easily — e.g., move from OpenAI to Ollama, or from FileVectorStore to Qdrant.

8. Conclusion

RAG is not magic — it’s a clear, well-defined pattern.
Neuron AI finally lets PHP developers play with modern AI tools without switching to Python, Docker, or extra servers.

Yes, FileVectorStore is basic, but perfect for demos and local experiments. Once you understand the principles, you can integrate RAG into any PHP framework and upgrade the components whenever you’re ready.