npm package: @joelrd01/llama-cpp-qwen2.5-0.5b
Description: NPM package that automatically downloads and provides the Qwen2.5-0.5B-Instruct GGUF model from Hugging Face on install.
Author: joelrd01
Latest version: 1.0.3

# 🤖 @joelrd01/llama-cpp-qwen2.5-0.5b

<p align="center">
  
  ![Node.js Badge](https://img.shields.io/badge/Node.js-5FA04E?logo=nodedotjs&logoColor=fff&style=flat)
  ![License Badge](https://img.shields.io/badge/MIT-blue)
  ![npm Badge](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=fff&style=flat)
  ![Testin Badge](https://img.shields.io/badge/Testin-007DD7?logo=testin&logoColor=fff&style=flat-square)
  ![Babel Badge](https://img.shields.io/badge/Babel-F9DC3E?logo=babel&logoColor=000&style=flat)
  ![Git Badge](https://img.shields.io/badge/Git-F05032?logo=git&logoColor=fff&style=flat)
  ![Jest Badge](https://img.shields.io/badge/Jest-C21325?logo=jest&logoColor=fff&style=flat)
</p>

---

## 📖 Descripción

Este paquete npm proporciona una integración sencilla y directa con el modelo **Qwen2.5-0.5B-Instruct** en formato GGUF, permitiendo ejecutar inferencias de inteligencia artificial directamente desde Node.js utilizando la librería `node-llama-cpp`.

### ✨ Características Principales

- ⬇️ **Descarga Automática**: El modelo se descarga automáticamente al instalar el paquete
- 🚀 **Fácil de Usar**: API minimalista y intuitiva
- 💻 **Multiplataforma**: Soporta CPU y GPU (CUDA, Vulkan, Metal)
- 📦 **GGUF**: Formato optimizado para eficiencia en memoria

---

## 🛠️ Instalación

### Requisitos Previos

| Requisito | Versión Mínima |
|-----------|----------------|
| Node.js   | 16.0.0+       |
| npm       | 7.0.0+        |

### Instalación del Paquete

```bash
npm install @joelrd01/llama-cpp-qwen2.5-0.5b
```

> **Nota**: El script `postinstall` se ejecutará automáticamente para descargar el modelo GGUF desde Hugging Face.

---

## 📚 Estructura del Proyecto

```
llama-cpp-qwen2.5:0.5b/
├── 📄 index.js              # Punto de entrada principal
├── 📂 scripts/
│   ├── 📥 postinstall.js   # Script de descarga del modelo
│   └── ✅ verify.js         # Script de verificación
├── 📂 node_modules/
│   └── @joelrd01/
│       └── llama-cpp-qwen2.5-0.5b/
│           └── model/
│               └── model.gguf  # Modelo descargado
└── 📦 package.json
```

---

## 🎯 Uso Rápido

### Ejemplo Básico

```javascript
import { initModelLocal, getModelPath, getModelInfo } from '@joelrd01/llama-cpp-qwen2.5-0.5b';

// Crear instancia del modelo
const model = new initModelLocal();

// Inicializar el modelo
await model.init();

// Ejecutar una consulta
const response = await model.runModel(
  'Eres un asistente útil.',
  '¿Cuál es la capital de Francia?'
);

console.log(response);
// Output: "La capital de Francia es París."
```

### Ejemplo con Configuración Personalizada

```javascript
import { initModelLocal } from '@joelrd01/llama-cpp-qwen2.5-0.5b';

// Crear instancia con configuración personalizada
const model = new initModelLocal({
  gpu: { vulkan: true },      // Habilitar Vulkan
  gpuLayers: 16,              // 16 capas en GPU
  contextSize: 8192,          // Contexto de 8192 tokens
  batchSize: 1024,            // Batch size aumentado
  ignoreMemorySafetyChecks: false
});

// Inicializar y ejecutar
await model.init();

const response = await model.runModel(
  'Eres un experto en programación.',
  'Explica qué es un closure en JavaScript.'
);
```

---

## 📖 Referencia de API

### Clase `initModelLocal`

Constructor que crea una nueva instancia del modelo con configuración opcional.

```javascript
new initModelLocal(options?)
```

#### Parámetros del Constructor

| Parámetro | Tipo | Valor por Defecto | Descripción |
|-----------|------|-------------------|-------------|
| `gpu` | `Object` | `{ vulkan: false, cuda: false, metal: false }` | Configuración de GPU |
| `gpuLayers` | `number` | `2` | Número de capas en GPU |
| `contextSize` | `number` | `4096` | Tamaño del contexto en tokens |
| `batchSize` | `number` | `512` | Tamaño del batch |
| `ignoreMemorySafetyChecks` | `boolean` | `false` | Ignorar verificaciones de memoria |

#### Opciones de GPU

```javascript
// Modo CPU únicamente (por defecto)
gpu: {}

// Solo Vulkan
gpu: { vulkan: true }

// Solo CUDA
gpu: { cuda: true }

// Metal (macOS)
gpu: { metal: true }
```

---

### Método `initModelLocal.init()`

Inicializa el runtime de llama, carga el modelo y crea el contexto de inferencia.

#### Retorno

```javascript
// Promise<void> - Resuelve cuando el modelo está listo
const model = new initModelLocal();
await model.init();
```

---

### Método `initModelLocal.runModel(systemPrompt?, userPrompt)`

Ejecuta una inferencia contra el modelo cargado.

#### Parámetros

| Parámetro | Tipo | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `systemPrompt` | `string` | No | Prompt de sistema para definir el comportamiento del modelo |
| `userPrompt` | `string` | **Sí** | Mensaje del usuario a enviar al modelo |

#### Retorno

```javascript
// Promise<string> - Respuesta del modelo (sin espacios en blanco al inicio/final)
const respuesta = await model.runModel('Eres un asistente.', 'Hola, ¿cómo estás?');
```

#### Ejemplo Completo

```javascript
import { initModelLocal } from '@joelrd01/llama-cpp-qwen2.5-0.5b';

const model = new initModelLocal();
await model.init();

// Consulta simple
const r1 = await model.runModel('', '¿Cuánto es 2 + 2?');
console.log(r1);

// Consulta con contexto
const r2 = await model.runModel(
  'Responde siempre en español y de forma concisa.',
  'Explícame qué es una API REST.'
);
console.log(r2);
```

---

### Función `getModelPath()`

Retorna la ruta absoluta al directorio del modelo.

#### Retorno

```javascript
// string - Ruta absoluta al directorio del modelo
const ruta = getModelPath();
// => /home/usuario/proyecto/node_modules/@joelrd01/llama-cpp-qwen2.5-0.5b/model
```

---

### 4. `getModelInfo()`

Retorna metadatos sobre los archivos del modelo descargado.

#### Retorno

```javascript
// Object - Metadatos del modelo
{
  path: string,           // Ruta absoluta del directorio
  files: string[],        // Nombres de archivos GGUF
  fileCount: number,      // Cantidad de archivos
  totalSizeBytes: number, // Tamaño total en bytes
  totalSizeMB: string,    // Tamaño en MB (2 decimales)
  totalSizeGB: string     // Tamaño en GB (2 decimales)
}
```

#### Ejemplo

```javascript
import { getModelInfo } from '@joelrd01/llama-cpp-qwen2.5-0.5b';

const info = getModelInfo();
console.log(`
📦 Modelo: Qwen2.5-0.5B-Instruct GGUF
📁 Archivos: ${info.fileCount}
💾 Tamaño: ${info.totalSizeMB} MB
📂 Ubicación: ${info.path}
`);
```

---

## 🔧 Configuración Avanzada

### Configuración de Memoria

```javascript
// Para sistemas con memoria limitada
const model = new initModelLocal({
  gpuLayers: 0,                         // Solo CPU
  contextSize: 2048,                     // Contexto reducido
  batchSize: 256,                       // Batch pequeño
  ignoreMemorySafetyChecks: false       // Mantener verificaciones
});
await model.init();
```

### Optimización para GPU

```javascript
// Configuración para GPU dedicada
const model = new initModelLocal({
  gpu: { cuda: true },      // NVIDIA GPU
  gpuLayers: 32,            // Todas las capas en GPU
  contextSize: 8192,        // Contexto amplio
  batchSize: 2048,          // Batch grande
});
await model.init();
```

---

## 🎨 Múltiples Instancias

Cada instancia de `initModelLocal` mantiene su propio estado:

```javascript
// Crear múltiples instancias independientes
const model1 = new initModelLocal({ gpuLayers: 4 });
const model2 = new initModelLocal({ gpuLayers: 0 }); // CPU-only

await model1.init();
await model2.init();

// Cada modelo puede tener diferente configuración
const r1 = await model1.runModel('', 'Pregunta 1');
const r2 = await model2.runModel('', 'Pregunta 2');
```

---

## ⚠️ Manejo de Errores

### Modelo No Encontrado

```javascript
// Error: Model directory not found
// Solución: Ejecutar npm run postinstall
npm run postinstall
```

### Memoria Insuficiente

```javascript
// Reducir uso de memoria
const model = new initModelLocal({
  gpuLayers: 0,
  contextSize: 2048,
  batchSize: 256
});
await model.init();
```

---

## 📊 Benchmark Rápido

| Configuración | Velocidad Aproximada |
|--------------|---------------------|
| CPU (1 hilo) | ~30 tokens/segundo |
| CPU (4 hilos) | ~80 tokens/segundo |
| GPU (CUDA)   | ~200 tokens/segundo |
| GPU (Vulkan) | ~150 tokens/segundo |

> *Valores aproximados, varían según hardware*

---

## 📝 Scripts Disponibles

| Script | Descripción |
|--------|-------------|
| `npm run postinstall` | Descarga el modelo GGUF |
| `npm run test` | Verifica la instalación del modelo |

---

## 🔗 Recursos Externos

| Recurso | Enlace |
|---------|--------|
| Repositorio GitHub | [HuggingFace](https://huggingface.co/joelrd01/llama-cpp-qwen-2.5-05b/tree/main) |
| Modelo en HuggingFace | [Qwen2.5-0.5B-Instruct-GGUF](https://huggingface.co/joelrd01/llama-cpp-qwen-2.5-05b) |
| Librería node-llama-cpp | [npm](https://www.npmjs.com/package/node-llama-cpp) |

---

## 📄 Licencia

MIT License - Ver archivo [LICENSE](./LICENSE)

---

## 👨‍💻 Autor

**joelrd01**

---

<p align="center">
  <sub>Hecho con ❤️ y ☕</sub>
</p>

---