How to use a PHP RAG AI Library to Improve a Chatbot Application Using the Package PHP Nano RAG: Learn and ask questions using AI with RAG

Recommend this page to a friend!

Download

Info

Example

Files

Install with Composer

Download

Reputation

Support forum

Blog

Links

Last Updated		Ratings				Unique User Downloads		Download Rankings
2025-12-17 (2 days ago)		Not yet rated by the users				Total: Not yet counted		Not yet ranked

Version		License		PHP version		Categories
`php-nano-rag` 1		MIT/X Consortium ...		8		Databases, Chat, Artificial intelligence, P...

Description

Author

Rodrigo Faustino

This package implements an application that can learn and let users ask questions using artificial intelligence improved using Retrieval-Augmented Generation (RAG).

It provides a Web application that lets users ask questions using chat prompts and answers using Ollama artificial client improved with knowledge also provided by the users.

The knowledge database uses files with data stored in the JSON format.

The application also allows users:

- Clear the knowledge database

- Clear the user chat session

- Upload a new knowledge database file

In Portuguese:

Este componente pode servir para criar um sistema de recomenda��o de produtos ou um chatbot inteligente no seu site PHP sem instalar nada no servidor.

Nano RAG � uma biblioteca PHP de c�digo aberto que implementa uma arquitetura de Gera��o Aumentada por Recupera��o (RAG - Retrieval-Augmented Generation) utilizando puramente PHP e armazenamento em arquivos locais (JSON).

O projeto foi desenhado para ambientes onde bancos de dados vetoriais complexos (como Pinecone ou Milvus) n�o est�o dispon�veis.

Rodrigo Faustino

Performance

Level

Name:	Rodrigo Faustino `<contact>`
Classes:	43 packages by Rodrigo Faustino
Country:	Brazil
Age:	42
All time rank:	2330	158 in Brazil
Week rank:	1

Level 1

Innovation award

Nominee: 25x

Winner: 6x

Instructions

Please read this document to learn how to setup and understand the chatbot application that uses artificial intelligence and retrieval-augmented generation to provide better answers to user questions.

Example


<?php

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



use NanoRag\LlmClient\OllamaClient;

use NanoRag\VectorDb\Memory;

use NanoRag\RagEngine\ShortTermMemory;

use NanoRag\RagEngine\Brain;



set_time_limit(300); 



$dbFile = 'knowledge_base.json';



$llm = new OllamaClient(embedModel: 'nomic-embed-text', chatModel: 'llama3.2');

$longTerm = new Memory($dbFile); 

$shortTerm = new ShortTermMemory();

$brain = new Brain($llm, $longTerm, $shortTerm);



$message = '';

$answer = '';



if (isset($_POST['action'])) {

    if ($_POST['action'] === 'clear_db') {

        if (file_exists($dbFile)) unlink($dbFile);

        $message = '<div class="alert alert-danger">Mem�ria de Longo Prazo (Arquivos) apagada.</div>';

        header("Refresh:1; url=index.php"); 

    }

    if ($_POST['action'] === 'clear_chat') {

        $shortTerm->clear(); // Limpa apenas a sess�o

        $message = '<div class="alert alert-info">Mem�ria de Curto Prazo (Chat) reiniciada.</div>';

    }

}



if (isset($_FILES['txt_file']) && $_FILES['txt_file']['error'] === UPLOAD_ERR_OK) {



    $content = file_get_contents($_FILES['txt_file']['tmp_name']);

    $chunks = preg_split('/\n\s*\n/', $content);

    foreach ($chunks as $chunk) {

        if (strlen(trim($chunk)) > 20) {

            $brain->learn($chunk, ['source' => $_FILES['txt_file']['name']]);

        }

    }

    $message = '<div class="alert alert-success">Arquivo aprendido!</div>';

}



if (isset($_POST['question']) && !empty($_POST['question'])) {

    $answer = $brain->ask($_POST['question']);

}



$chatHistory = $shortTerm->getFullHistory();

?>



<!DOCTYPE html>

<html lang="pt-BR">

<head>

    <meta charset="UTF-8">

    <title>Nano RAG - Agente Conversacional</title>

    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet">

    <style>

        .chat-container { height: 500px; overflow-y: auto; background: #f8f9fa; padding: 20px; border: 1px solid #ddd; border-radius: 8px; }

        .msg { margin-bottom: 15px; padding: 10px 15px; border-radius: 15px; max-width: 80%; }

        .msg-user { background-color: #0d6efd; color: white; margin-left: auto; text-align: right; border-bottom-right-radius: 2px; }

        .msg-assistant { background-color: #e9ecef; color: #333; margin-right: auto; text-align: left; border-bottom-left-radius: 2px; }

        .source-tag { font-size: 0.7em; color: #ccc; display: block; margin-top: 5px; }

#rag-loader-overlay {

    position: fixed;

    top: 0;

    left: 0;

    width: 100%;

    height: 100%;

    background: rgba(10, 25, 47, 0.85); 

    backdrop-filter: blur(5px);

    z-index: 9999;

    justify-content: center;

    align-items: center;

    flex-direction: column;

}



.neural-orbit-loader {

    position: absolute;

    top: 28%;

    left: 45%;

    width: 120px;

    height: 120px;

}



.brain-core {

    position: absolute;

    top: 50%;

    left: 50%;

    width: 40px;

    height: 40px;

    background: radial-gradient(circle, #00f2fe 0%, #4facfe 100%); 

    border-radius: 50%;

    transform: translate(-50%, -50%);

    box-shadow: 0 0 30px #00f2fe, 0 0 50px #4facfe; 

    animation: corePulse 2s ease-in-out infinite;

}



.orbit-ring {

    position: absolute;

    top: 0;

    left: 0;

    width: 100%;

    height: 100%;

    border-radius: 50%;

    border: 2px solid rgba(0, 242, 254, 0.1); 

    animation: ringRotate 3s linear infinite;

}



.data-node {

    position: absolute;

    width: 15px;

    height: 15px;

    background: #a855f7; 

    border-radius: 50%;

    box-shadow: 0 0 15px #a855f7;

}

.node-1 { top: 0; left: 50%; transform: translate(-50%, -50%); }

.node-2 { bottom: 0; left: 50%; transform: translate(-50%, 50%); background: #ff0080; box-shadow: 0 0 15px #ff0080; } /* Rosa */

.node-3 { left: 0; top: 50%; transform: translate(-50%, -50%); }

.loading-text {

    position: absolute;

    top: 18%;

    left: 43%;

    margin-top: 30px;

    color: #fff;

    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;

    font-weight: 300;

    letter-spacing: 2px;

    animation: textFade 2s ease-in-out infinite;

}

@keyframes corePulse {

    0%, 100% { transform: translate(-50%, -50%) scale(1); opacity: 1; }

    50% { transform: translate(-50%, -50%) scale(1.2); opacity: 0.8; }

}



@keyframes ringRotate {

    0% { transform: rotate(0deg); }

    100% { transform: rotate(360deg); }

}

@keyframes textFade {

    0%, 100% { opacity: 0.7; }

    50% { opacity: 1; }

}

    </style>

</head>



<body class="p-4">





<div class="container">

    <div class="row">

        <div class="col-md-4">

            <h3>? Nano Brain</h3>

            <div class="card mb-3">

                <div class="card-body">

                    <h6>Status da Mem�ria</h6>

                    <ul>

                        <li><strong>Longo Prazo:</strong> <?php echo $brain->getLongTermMemorySize(); ?> vetores</li>

                        <li><strong>Curto Prazo:</strong> <?php echo $brain->getShortTermMemoryCount(); ?> mensagens</li>

                    </ul>

                </div>

            </div>



            <form method="post" enctype="multipart/form-data" class="mb-3">

                <label>Adicionar Conhecimento (.txt)</label>

                <input type="file" name="txt_file" class="form-control mb-2" required>

                <button type="submit" class="btn btn-sm btn-primary w-100">Ensinar</button>

            </form>



            <hr>

            

            <form method="post" class="d-flex gap-2">

                <button type="submit" name="action" value="clear_chat" class="btn btn-sm btn-outline-secondary flex-fill">Limpar Chat</button>

                <button type="submit" name="action" value="clear_db" class="btn btn-sm btn-outline-danger flex-fill">Apagar Arquivos</button>

            </form>

            <?php echo $message; ?>

        </div>



        <div class="col-md-8">

            <div class="chat-container mb-3" id="chatBox">

                <?php if (empty($chatHistory)): ?>

                    <p class="text-center text-muted mt-5">Inicie a conversa...</p>

                <?php else: ?>

                    <?php foreach ($chatHistory as $msg): ?>

                        <div class="msg msg-<?php echo $msg['role']; ?>">

                            <strong><?php echo $msg['role'] === 'user' ? 'Voc�' : 'Nano AI'; ?>:</strong><br>

                            <?php echo nl2br(htmlspecialchars($msg['content'])); ?>

                        </div>

                    <?php endforeach; ?>

                <?php endif; ?>

            </div>



            <form method="post">

                <div class="input-group">

                    <input type="text" name="question" class="form-control" placeholder="Pergunte algo ou pe�a um resumo..." autofocus>

                    <button class="btn btn-success">Enviar</button>

                </div>

            </form>

        </div>

    </div>

</div>

<div id="rag-loader-overlay">

    <div class="neural-orbit-loader">

        <div class="brain-core"></div>

        <div class="orbit-ring">

            <div class="data-node node-1"></div>

            <div class="data-node node-2"></div>

            <div class="data-node node-3"></div>

        </div>

    </div>

    <div class="loading-text">PROCESSANDO RAG...</div>

</div>

<script>

   

    var chatBox = document.getElementById("chatBox");

    if(chatBox) {

        chatBox.scrollTop = chatBox.scrollHeight;

    }

    const loader = document.getElementById('rag-loader-overlay');

    const loadingText = loader.querySelector('.loading-text');



    function showLoader(text) {

        loadingText.innerText = text;

        loader.style.display = 'flex';

    }



    const uploadForm = document.querySelector('form[enctype="multipart/form-data"]');

    if (uploadForm) {

        uploadForm.addEventListener('submit', function() {

            showLoader('ASSIMILANDO CONHECIMENTO...');

        });

    }



    const questionInput = document.querySelector('input[name="question"]');

    if (questionInput) {

        const chatForm = questionInput.closest('form');

        if (chatForm) {

            chatForm.addEventListener('submit', function() {

                if (questionInput.value.trim() !== '') {

                    showLoader('ACESSANDO MEM�RIA & GERANDO RESPOSTA...');

                }

            });

        }

    }

    

    const clearForms = document.querySelectorAll('form:not([enctype])');

    clearForms.forEach(form => {

        form.addEventListener('submit', function(e) {

            if (e.submitter && e.submitter.name === 'action') {

                 showLoader('LIMPANDO DADOS...');

            }

        });

    })

setTimeout(() => {

    loader.style.display = 'none';

}, 2000);

</script>

</body>

</html>

Details

Nano RAG for PHP

Nano RAG � uma biblioteca PHP de c�digo aberto que implementa uma arquitetura de Gera��o Aumentada por Recupera��o (RAG - Retrieval-Augmented Generation) utilizando puramente PHP e armazenamento em arquivos locais (JSON).

O projeto foi desenhado para ambientes onde bancos de dados vetoriais complexos (como Pinecone ou Milvus) n�o est�o dispon�veis, permitindo a cria��o de Agentes de IA com mem�ria persistente e contextual em servidores de hospedagem compartilhada.

Parte 1: Guia de Instala��o e Uso

Pr�-requisitos do Sistema

PHP 8.2 ou superior.
Composer para gerenciamento de depend�ncias.
Ollama rodando localmente ou em um servidor acess�vel via rede.

Configura��o do Ollama

O Nano RAG depende do Ollama para processamento de linguagem natural. Voc� precisa instalar o servidor e dois modelos espec�ficos: um para gerar vetores (Embeddings) e outro para o chat (LLM).

Baixe e instale o Ollama em ollama.com.
Abra seu terminal e execute os seguintes comandos para baixar os modelos necess�rios:

ollama pull nomic-embed-text ollama pull llama3.2

Nota: Voc� pode utilizar outros modelos, mas deve atualizar a configura��o na instancia��o da classe OllamaClient.

Instala��o da Biblioteca

Na raiz do seu projeto, execute a instala��o das depend�ncias (atualmente configurado para autoload PSR-4):

composer install

Para iniciar a interface web de demonstra��o:

Inicie um servidor PHP local: php -S localhost:8000
Acesse no navegador: http://localhost:8000

Como Utilizar

O sistema opera atrav�s de um fluxo de ingest�o (aprendizado) e consulta (chat).

1. Ingest�o de Dados (Aprendizado)

Para que a IA responda sobre seus dados, voc� deve "ensinar" o sistema enviando arquivos de texto (.txt). * O sistema l� o arquivo. * O texto � dividido em fragmentos menores (chunks). Cada fragmento � convertido em um vetor matem�tico e salvo naMem�ria de Longo Prazo*.

2. Realizando Consultas

Ao fazer uma pergunta, o sistema utiliza uma Camada de Aten��o para decidir se deve buscar a resposta nos arquivos que voc� enviou ou no hist�rico da conversa atual.

Parte 2: Aspectos T�cnicos e Arquitetura

O Nano RAG diferencia-se por sua arquitetura modular inspirada em processos cognitivos, dividida em tr�s pilares principais gerenciados por um orquestrador central.

1. O C�rebro (Brain Class)

A classe Brain atua como o controlador central. Ela n�o armazena dados, mas orquestra o fluxo de informa��es entre o cliente LLM (Ollama), as mem�rias e a camada de decis�o. � respons�vel por receber o input do usu�rio e devolver a resposta final processada.

2. Mem�ria de Longo Prazo (Long-Term Memory)

Fun��o: Armazenamento persistente de fatos e conhecimento "cristalizado".
Implementa��o: Utiliza arquivos JSON locais (`knowledge_base.json`).
T�cnica: Armazena o texto original junto com seu Embedding Vector.
Recupera��o: Utiliza o algoritmo de Similaridade de Cosseno para encontrar matematicamente qual texto no banco de dados � mais pr�ximo da pergunta do usu�rio. Funciona como uma biblioteca est�tica.

3. Mem�ria de Curto Prazo (Short-Term Memory)

Fun��o: Manter o contexto da conversa atual (sess�o), permitindo que a IA entenda refer�ncias como "ele", "aquilo" ou "a resposta anterior".
Implementa��o: Baseada em sess�es PHP (`$_SESSION`), mas enriquecida com vetores.
Diferencial: Diferente de arrays simples, esta mem�ria armazena o vetor de cada mensagem trocada. Isso permite que o sistema busque no hist�rico n�o apenas por ordem cronol�gica, mas por relev�ncia sem�ntica.

4. Camada de Aten��o (Attention Layer)

Este � o componente mais complexo do sistema, atuando como um filtro l�gico (Gatekeeper) antes de acionar a Intelig�ncia Artificial. Ela resolve o problema de alucina��o evitando enviar contexto irrelevante para o modelo.

A camada de aten��o decide dinamicamente a estrat�gia de resposta: Estrat�gia Retrieval:* Se a pergunta do usu�rio tem alta similaridade matem�tica com dados do JSON, a aten��o foca na Mem�ria de Longo Prazo. Estrat�gia Contextual:* Se a pergunta se conecta semanticamente com a frase anterior, a aten��o foca na Mem�ria de Curto Prazo. Estrat�gia Meta-Analysis:* Se o usu�rio pergunta sobre a pr�pria conversa (ex: "O que eu perguntei antes?", "Resuma o chat"), a camada ignora a matem�tica e recupera o hist�rico linear bruto, simulando uma mem�ria sequencial.

Conceitos Fundamentais: Vetores e Embeddings

Para que o PHP realize buscas sem�nticas sem um banco de dados externo, utilizamos o conceito de Embeddings.

O que � um Embedding? � uma representa��o num�rica de um texto. O modelo `nomic-embed-text` transforma uma frase como "O PHP � uma linguagem de script" em uma lista de 768 n�meros flutuantes (ex: `[0.123, -0.542, 0.991, ...]`).
Por que isso � necess�rio? Computadores n�o entendem significado, apenas n�meros. Ao transformar texto em n�meros, podemos calcular a dist�ncia geom�trica entre duas frases. * A frase "Eu gosto de ma��" ter� um vetor matematicamente muito pr�ximo de "Adoro frutas". * A frase "Eu gosto de ma��" ter� um vetor distante de "O servidor caiu".

O Nano RAG calcula essas dist�ncias nativamente em PHP para determinar o que � relevante para responder ao usu�rio.

Files (15)

File	Role	Description
`src` (3 directories)
`tests` (5 files)
`composer.json`	Data	Auxiliary data
`index.php`	Example	Example script
`knowledge_base.json`	Data	Auxiliary data
`README.md`	Doc.	Documentation

Files (15)

src

File	Role	Description
`LlmClient` (1 file)
`RagEngine` (3 files)
`VectorDb` (2 files)

Files (15)

src

LlmClient

File	Role	Description
`OllamaClient.php`	Class	Class source

Files (15)

src

RagEngine

File	Role	Description
`AttentionLayer.php`	Class	Class source
`Brain.php`	Class	Class source
`ShortTermMemory.php`	Class	Class source

Files (15)

src

VectorDb

File	Role	Description
`MathUtils.php`	Class	Class source
`Memory.php`	Class	Class source

Files (15)

tests

File	Role	Description
`test_phase2.php`	Example	Example script
`test_phase3.php`	Example	Example script
`test_phase4.php`	Example	Example script
`texto sobre php para upload.txt`	Doc.	Documentation
`texto sobre psicologia para upload.txt`	Doc.	Documentation