---
title: "El módulo de IA"
description: "Primera clase de IA en Nibiru — chat, embeddings, RAG, agentes — conectados a tu propio Ollama en neuronetz.ai. No se requieren APIs pagas."
---

Nibiru incluye un **módulo de IA** (`application/module/ai/`) que da a cada aplicación Nibiru una interfaz de IA de primera clase. El código PHP puede chatear con un LLM local, incrustar texto, ejecutar RAG sobre sus propios datos o ejecutar un agente con herramientas — todo sin enviar un solo byte a una API pagada.

El módulo está conectado a su propio [Ollama en neuronetz.ai](/es/ai/oracle/) por defecto, por lo que la inferencia se realiza en su hardware, en su red y bajo sus términos.

## Lo que obtienes

| Plugin | ¿Qué hace? | Una línea |
|---|---|---|
| `Chat` | Completaciones de chat, una o múltiples vueltas | `$ai->chat()->ask('…')` |
| `Embed` | Texto → vectores + ayudantes de coseno | `$ai->embed()->one('…')` |
| `Rag` | Ingesta + recuperación + chat basado en el contexto | `$ai->rag('docs')->ask('…')` |
| `Agent` | Bucle ReAct con herramientas | `$ai->agent()->withTools([…])->run('…')` |
| `Tool` | Base para tus propias herramientas personalizadas | `class MyTool extends Tool { … }` |
| `Ollama` | Transporte HTTP sin procesar a cualquier punto final compatible con Ollama | `(new Ollama($cfg))->chat(…)` |

## Hola, IA
```php
use Nibiru\Module\Ai\Ai;

$ai = new Ai();

echo $ai->chat()->ask('How do I scaffold a new module?');
// → "Run `./nibiru -m <name>`. This creates application/module/<name>/ with…"
```
Esa es toda la superficie de la API para el caso simple. Sin contenedor de inyección de dependencias, sin claves de API, sin instalación del SDK.

## Conectado por configuración

Cada complemento lee sus configuraciones desde `application/module/ai/settings/ai.ini`:
```ini
[AI]
ollama.base_url     = "https://api.neuronetz.ai"
chat.model          = "nibiru-coder:1.0"
chat.fallback_model = "qwen2.5-coder:14b"
chat.temperature    = 0.4
chat.max_tokens     = 1024
embed.model         = "nomic-embed-text"
rag.top_k           = 6
agent.max_iterations = 6
```
Sobrescritura por entorno: `ai.production.ini`, `ai.staging.ini`. El Registro de Nibiru los descubre automáticamente.

## Los cuatro casos de uso destacados

### 1. Chat — hablar con tu modelo
```php
$ai = new \Nibiru\Module\Ai\Ai();

// One-shot
echo $ai->chat()->ask('Explain MMVC in two sentences.');

// Multi-turn
$chat = $ai->chat();
$chat->user('How do I scaffold a module?');
$chat->user('And add Graylog hooks?');   // referrs to previous turn
echo $chat->complete();

// Override per call
echo $ai->chat()
    ->system('Answer in German.')
    ->model('qwen2.5-coder:14b')
    ->temperature(0.1)
    ->ask('Was ist ein Modul?');
```
El complemento `Chat` se cae automáticamente en `chat.fallback_model` si el modelo principal no está disponible — útil mientras sigues construyendo `nibiru-coder`.

### 2. Incorporar — texto en vectores
```php
$embed = $ai->embed();

$va = $embed->one('controller');
$vb = $embed->one('module');
$score = \Nibiru\Module\Ai\Plugin\Embed::cosine($va, $vb);
// → 0.78 (close concepts)
```
Almacenamiento compacto:
```php
$packed = \Nibiru\Module\Ai\Plugin\Embed::pack($vec);   // base64 string, 4 bytes/dim
$vec    = \Nibiru\Module\Ai\Plugin\Embed::unpack($packed);
```
### 3. RAG — ingesta, recuperación, anclaje
```php
$rag = $ai->rag('product-help');

// One-time ingestion
$rag->ingestDir(__DIR__ . '/help/');             // walks .md/.txt/.php
$rag->ingestText('FAQ entry…', ['source' => 'faq-12']);
$rag->ingestFile('/var/data/manual.pdf.txt');

// Then ask grounded questions
echo $rag->ask('How do I cancel my subscription?');
// → "Per the help docs, you can cancel in account → settings… [1]"
```
Almacenamiento: un archivo JSON por colección en `application/module/ai/cache/rag/<nombre>.json`. Reanudable, sin base de datos, se ajusta cómodamente a unos 10k fragmentos en memoria.

### 4. Agente — herramientas que actúan
```php
use Nibiru\Module\Ai\Plugin\Tools;

$ai = new \Nibiru\Module\Ai\Ai();

$agent = $ai->agent()->withTools([
    new Tools\PdoQuery(),    // read-only SQL
    new Tools\HttpGet(),     // fetch URLs
    new Tools\FileRead(),    // read project files
]);

echo $agent->run('How many active users registered last week?');
// → agent decides to call pdo_query with SELECT count(*) FROM users…
//   reads observation, writes a final answer.
```
El agente utiliza un bucle estilo ReAct: leer tarea → elegir herramienta → ejecutar → observar → repetir → respuesta final. El protocolo usa un simple `\`\`\`tool {...}\`\`\`` sentinel JSON que funciona en todos los modelos de Ollama — no se requieren APIs específicas de llamada a herramientas por modelo.

## Dónde vive
```
application/module/ai/
├── ai.php                    # main class implementing IModule
├── interfaces/ai.php         # contract
├── traits/ai.php             # cfg() helper
├── plugins/
│   ├── ollama.php            # raw transport
│   ├── chat.php              # chat completions
│   ├── embed.php             # embeddings + cosine + pack
│   ├── rag.php               # ingest + retrieve + grounded chat
│   ├── agent.php             # ReAct tool loop
│   ├── tool.php              # abstract base for custom tools
│   └── tools/
│       ├── pdoQuery.php      # read-only SQL
│       ├── httpGet.php       # HTTP GET
│       └── fileRead.php      # project-local file read
├── settings/ai.ini           # config
├── cache/rag/                # RAG vector index files (gitignored)
└── training/
    ├── Modelfile             # the nibiru-coder system prompt
    ├── build.sh              # one-command Modelfile → registered model
    ├── smoke-test.php        # verify the whole stack
    └── README.md             # training pipeline guide
```
## Por qué esto existe

PHP no tiene un "marco de IA" establecido como lo tienen Python con LangChain o JS con Vercel AI SDK. El módulo de IA de Nibiru llena ese vacío con la API más pequeña y afilada que pudimos escribir — tres capas (transporte → complemento → módulo), sin gráfica DI, sin instalación de SDK, sin facturación por token.

La filosofía de diseño:

- **Trae tu propio cerebro.** Ollama por defecto, Anthropic y OpenAI como opciones de reemplazo. Cambia proveedores a través de INI, nunca a través de código.
- **Un archivo JSON por colección RAG.** Sin base de datos vectorial. Seguro para reinicios. Grepable cuando estés depurando.
- **Las herramientas son clases PHP.** Extiende `Tool`, obtén un nombre + esquema + método execute. El agente se encarga del resto.
- **No hay APIs específicas de llamada a herramientas por modelo.** Una sola convención de JSON con marcas funciona en todas partes.

## Siguiente

- [Referencia del complemento de chat](/es/ai/modulo/chat/)
- [Referencia del complemento RAG](/es/ai/modulo/rag/)
- [Referencia del complemento de agente](/es/ai/modulo/agent/)
- [Entrenamiento nibiru-coder](/es/ai/modulo/training/)
