README

SDK para integrar IA (LLM + RAG) directamente en aplicaciones PHP — sin Python, sin Node.js, sin microservicios.

Funciona con Modux, Laravel, Symfony, Slim, Mezzio, CodeIgniter y PHP puro.

Requisitos

• PHP 8.1 o superior
• Extensiones: curl, pdo, json
• Composer 2

Instalación

composer require cynchro/modux-ia

Eso es todo. Sin configuración adicional si usás variables de entorno.

Integración por framework

Modux

El módulo se auto-registra al boot. Solo agregá las variables de entorno y listo.

1. Instalar

composer require cynchro/modux-ia

2. Variables de entorno (.env)

AI_DRIVER=cloud
AI_CLOUD_PROVIDER=openai
AI_CLOUD_API_KEY=sk-...
AI_CLOUD_MODEL=gpt-4o-mini
RAG_STORE=sqlite
RAG_SQLITE_PATH=storage/ai/vectors.db

3. Usar en cualquier servicio o controller

El container de Modux inyecta DriverFactory y RAGEngine automáticamente:

use PhpAI\DriverFactory;
use PhpAI\RAG\RAGEngine;

class SoporteService
{
    public function __construct(
        private readonly DriverFactory $ai,
        private readonly RAGEngine     $rag,
    ) {}

    public function responder(string $pregunta): string
    {
        return $this->rag->ask($pregunta);
    }
}

Los endpoints listos para usar son:

POST /ia/chat      — chat con el LLM
POST /ia/ask       — pregunta con contexto RAG
POST /ia/ingest    — carga un documento al vector store
POST /ia/retrieve  — búsqueda semántica pura

Laravel

composer require cynchro/modux-ia

El ServiceProvider se autoregistra. Publicá la config si querés personalizarla:

php artisan vendor:publish --tag=modux-ia

use PhpAI\DriverFactory;
use PhpAI\RAG\RAGEngine;

class SupportController extends Controller
{
    public function __construct(
        private readonly DriverFactory $ai,
        private readonly RAGEngine     $rag,
    ) {}

    public function ask(Request $request): JsonResponse
    {
        $answer = $this->rag->ask($request->input('question'));
        return response()->json(['answer' => $answer]);
    }
}

Slim 4 / Mezzio / cualquier PSR-11

composer require cynchro/modux-ia cynchro/modux-ia-psr11

use DI\ContainerBuilder;
use PhpAI\Psr11\AIDefinitions;

$builder = new ContainerBuilder();
$builder->addDefinitions(AIDefinitions::get());
$container = $builder->build();

PHP puro

require 'vendor/autoload.php';

use PhpAI\Bootstrap;

// Zero config — lee todo desde variables de entorno
$ai = Bootstrap::fromEnv();

// O configuración explícita
$ai = Bootstrap::create([
    'driver' => 'cloud',
    'drivers' => [
        'cloud' => [
            'provider' => 'openai',
            'api_key'  => 'sk-...',
            'model'    => 'gpt-4o-mini',
        ],
    ],
    'rag' => ['sqlite_path' => __DIR__ . '/storage/vectors.db'],
]);

Variables de entorno

# Driver: local | cloud | cluster
AI_DRIVER=cloud

# Cloud (OpenAI, Groq, Together, Ollama...)
AI_CLOUD_PROVIDER=openai
AI_CLOUD_API_KEY=sk-...
AI_CLOUD_MODEL=gpt-4o-mini
AI_CLOUD_EMBEDDING_MODEL=text-embedding-3-small

# Local (llama.cpp)
LLAMA_SERVER_URL=http://127.0.0.1:8080
LLAMA_EMBED_URL=http://127.0.0.1:8081
LLAMA_MODEL=llama3
LLAMA_TIMEOUT=120

# Cluster (múltiples nodos llama.cpp)
AI_CLUSTER_NODES=http://node1:8080,http://node2:8080

# RAG — store: sqlite | qdrant
RAG_STORE=sqlite
RAG_SQLITE_PATH=storage/ai/vectors.db
RAG_CHUNK_SIZE=512
RAG_CHUNK_OVERLAP=64
RAG_TOP_K=4
QDRANT_URL=http://127.0.0.1:6333

Cambiar de driver es solo cambiar AI_DRIVER — el código de la aplicación no cambia.

Drivers disponibles

Providers cloud soportados

Uso

Chat

use PhpAI\Contracts\CompletionRequest;

$response = $factory->llm()->complete(new CompletionRequest(
    messages: [
        ['role' => 'system', 'content' => 'Sos un experto en PHP.'],
        ['role' => 'user',   'content' => '¿Qué es un trait?'],
    ],
    temperature: 0.7,
    maxTokens: 512,
));

echo $response->content;

Streaming (SSE)

header('Content-Type: text/event-stream');
header('Cache-Control: no-cache');

foreach ($factory->llm()->stream($request) as $token) {
    echo "data: " . json_encode(['token' => $token]) . "\n\n";
    ob_flush(); flush();
}
echo "data: [DONE]\n\n";

RAG — ingestar documentos

$rag = $factory->rag();

$rag->ingest(
    document: file_get_contents('manual.txt'),
    id:       'manual-v1',
    metadata: ['tipo' => 'manual'],
);

RAG — hacer preguntas

// Respuesta directa
$answer = $rag->ask("¿Cuál es el proceso de devolución?");

// Con filtro de metadata
$answer = $rag->ask(
    question: "¿Cómo configuro el sistema?",
    filter:   ['tipo' => 'manual'],
);

// Con system prompt personalizado
$answer = $rag->ask(
    question:     "¿Qué garantías tiene el producto?",
    systemPrompt: "Respondé de forma empática en no más de 3 oraciones.",
);

Búsqueda semántica pura

$chunks = $rag->retrieve("política de envíos internacionales");

foreach ($chunks as $chunk) {
    echo "[{$chunk['score']}] {$chunk['metadata']['content']}\n";
}

Embeddings

$vector  = $factory->embeddings()->embed("texto de ejemplo");
$vectors = $factory->embeddings()->embedBatch(["texto 1", "texto 2"]);

Vector store

# Levantar Qdrant con Docker
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

Driver local con llama.cpp

# Instalar llama.cpp
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp && cmake -B build && cmake --build build --config Release

# Descargar modelos
wget https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF/resolve/main/Llama-3.2-3B-Instruct-Q4_K_M.gguf -O models/llama3.gguf
wget https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf -O models/nomic-embed.gguf

# Levantar servidores
./build/bin/llama-server --model models/llama3.gguf --host 127.0.0.1 --port 8080 --ctx-size 4096
./build/bin/llama-server --model models/nomic-embed.gguf --host 127.0.0.1 --port 8081 --embedding --pooling mean

Estructura del SDK

src/
├── Bootstrap.php              Punto de entrada
├── Config.php                 Configuración con dot-notation y lectura de ENV
├── DriverFactory.php          Resuelve y cachea drivers por nombre
├── Contracts/
│   ├── LLMDriver.php          Interface de inferencia
│   ├── EmbeddingDriver.php    Interface de embeddings
│   ├── VectorStoreContract.php Interface de almacenamiento vectorial
│   ├── CompletionRequest.php  DTO de entrada al LLM
│   └── CompletionResponse.php DTO de salida del LLM
├── Http/
│   └── Client.php             HTTP client con soporte SSE streaming
├── Drivers/
│   ├── Cloud/CloudDriver.php  APIs OpenAI-compatible (OpenAI, Groq, etc.)
│   ├── Local/LocalDriver.php  llama.cpp HTTP server
│   └── Cluster/ClusterDriver.php Round-robin sobre múltiples nodos
├── RAG/
│   ├── TextChunker.php        Divide texto en chunks con overlap
│   └── RAGEngine.php          Orquesta ingest + retrieval + generación
└── Storage/
    ├── SqliteVectorStore.php  SQLite + cosine similarity en PHP
    └── QdrantVectorStore.php  Qdrant via HTTP API

packages/
├── psr11/                     cynchro/modux-ia-psr11
└── laravel/                   cynchro/modux-ia-laravel

Licencia

MIT