@rexdug7005/nvidia-llama4/README.md

Integración de NVIDIA Llama4 con LangChain.js, con soporte para Tools Agent de n8n

# @rexdug7005/nvidia-llama4

Esta biblioteca permite integrar modelos de NVIDIA Llama4 con el ecosistema de LangChain.js, facilitando el uso de modelos como Llama4 de Meta en aplicaciones de procesamiento de lenguaje natural.

## Versión Actual: 0.4.1

En esta versión se añade soporte completo para herramientas (tools/agent) y mejoras en la detección y extracción de llamadas a herramientas en las respuestas del modelo.

## Repositorio

[GitHub: https://github.com/Alex66688/nvidia-llama4](https://github.com/Alex66688/nvidia-llama4)

## Instalación

```bash
npm install @rexdug7005/nvidia-llama4 
yarn add @rexdug7005/nvidia-llama4 
pnpm add @rexdug7005/nvidia-llama4 
```

## Requisitos

- Node.js >= 18
- Una clave API de NVIDIA

## Modelos de Chat

```typescript
import { ChatNvidiaLlama4, ChatNvidiaLlama4Input, ChatNvidiaLlama4CallOptions } from "@rexdug7005/nvidia-llama4";

// Creación del modelo de chat
const chatModel = new ChatNvidiaLlama4({
  apiKey: "tu-api-key-de-nvidia",
  model: "meta/llama-4-maverick-17b-128e-instruct",
  temperature: 0.7,
  maxTokens: 512
});

// Generación de respuesta simple
const respuesta = await chatModel.invoke("Traduce 'Hola mundo' al inglés");

// Uso con mensajes estructurados
import { HumanMessage, SystemMessage } from "@langchain/core/messages";
const messages = [
  new SystemMessage("Eres un asistente útil especializado en traducción"),
  new HumanMessage("Traduce 'Hola mundo' al inglés")
];
const chatResponse = await chatModel.invoke(messages);

// Streaming de respuestas
const stream = await chatModel.stream("Explica el concepto de inteligencia artificial");
for await (const chunk of stream) {
  console.log(chunk.content); // Muestra fragmentos de la respuesta conforme llegan
}
```

## Uso de Herramientas (Tools)

La biblioteca soporta el uso de herramientas (tools) con los modelos de chat, permitiendo que el modelo utilice funciones externas para realizar tareas específicas.

```typescript
import { ChatNvidiaLlama4 } from "@rexdug7005/nvidia-llama4";
import { z } from "zod";
import { StructuredTool } from "@langchain/core/tools";

// Definir una herramienta para obtener el clima
class GetWeatherTool extends StructuredTool {
  name = "get_current_weather";
  description = "Obtiene la información meteorológica actual";
  schema = z.object({
    location: z.string().describe("La ciudad para obtener el clima"),
  });

  async _call({ location }: z.infer<typeof this.schema>) {
    // Implementación real llamaría a una API del clima
    return `La temperatura en ${location} es de 22°C`;
  }
}

// Crear una instancia del modelo y la herramienta
const chatModel = new ChatNvidiaLlama4({
  apiKey: "tu-api-key-de-nvidia",
  model: "meta/llama-4-maverick-17b-128e-instruct"
});
const weatherTool = new GetWeatherTool();

// Vincular la herramienta al modelo
const chatModelWithTools = chatModel.bindTools([weatherTool]);

// Usar el modelo con herramientas
const response = await chatModelWithTools.invoke("¿Cuál es el clima en Barcelona?");

// La respuesta puede incluir llamadas a herramientas
console.log(response.content);
if (response.tool_calls && response.tool_calls.length > 0) {
  console.log("Herramientas usadas:", response.tool_calls);
}
```

También puedes utilizar múltiples herramientas y manejar conversaciones más complejas:

```typescript
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

// Definir más herramientas, por ejemplo:
class GetPopulationTool extends StructuredTool {
  name = "get_population";
  description = "Obtiene la población de una ciudad";
  schema = z.object({
    location: z.string().describe("La ciudad para obtener la población"),
  });

  async _call({ location }: z.infer<typeof this.schema>) {
    // Simulación
    return `La población de ${location} es de aproximadamente 1.6 millones de habitantes.`;
  }
}

// Vincular múltiples herramientas
const modelWithMultipleTools = chatModel.bindTools([
  new GetWeatherTool(),
  new GetPopulationTool()
]);

// Utilizar con una conversación compleja
const response = await modelWithMultipleTools.invoke([
  new SystemMessage("Utiliza las herramientas disponibles para proporcionar información precisa."),
  new HumanMessage("Compara el clima y la población de Madrid y Barcelona")
]);
```

## Modelos de Lenguaje (LLMs)

```typescript
import { NvidiaLlama4, NvidiaLlama4Input, NvidiaLlama4CallOptions } from "@rexdug7005/nvidia-llama4";

// Creación del modelo de texto
const llm = new NvidiaLlama4({
  apiKey: "tu-api-key-de-nvidia",
  model: "meta/llama-4-maverick-17b-128e-instruct",
  temperature: 0.5,
  topP: 0.9
});

// Generación de texto
const respuesta = await llm.invoke("Explica qué es la inteligencia artificial");

// Uso con imágenes (para modelos multimodales)
const respuestaMultimodal = await llm.invoke("¿Qué muestra esta imagen?", {
  images: ["data:image/jpeg;base64,/9j/4AAQSkZJRg..."]  // Imagen en base64
});

// Streaming de respuestas
for await (const chunk of await llm.stream("Escribe un poema sobre la tecnología")) {
  process.stdout.write(chunk); // Imprime cada fragmento según llega
}
```

## Embeddings

```typescript
import { NvidiaEmbeddings, NvidiaEmbeddingsParams } from "@rexdug7005/nvidia-llama4";

// Creación del modelo de embeddings
const embeddings = new NvidiaEmbeddings({
  apiKey: "tu-api-key-de-nvidia",
  model: "embd/llama-4-embd"
});

// Generar embeddings para un texto individual
const vectorQuery = await embeddings.embedQuery("Este es un texto de ejemplo");

// Generar embeddings para múltiples textos
const documentos = [
  "La inteligencia artificial es una rama de la informática.",
  "El aprendizaje automático es un subcampo de la IA.",
  "Las redes neuronales son modelos inspirados en el cerebro humano."
];
const vectoresDocumentos = await embeddings.embedDocuments(documentos);
```

## Integración con LangChain

```typescript
import { ChatNvidiaLlama4 } from '@rexdug7005/nvidia-llama4';
import { PromptTemplate } from '@langchain/core/prompts';
import { StringOutputParser } from '@langchain/core/output_parsers';
import { RunnableSequence } from '@langchain/core/runnables';

// Crear un modelo
const model = new ChatNvidiaLlama4({ 
  apiKey: "tu-api-key-de-nvidia",
  model: "meta/llama-4-maverick-17b-128e-instruct" 
});

// Crear una plantilla de prompt
const promptTemplate = PromptTemplate.fromTemplate(
  "Traduce el siguiente texto del español al {idioma}: {texto}"
);

// Crear una cadena (chain) de procesamiento
const chain = RunnableSequence.from([
  promptTemplate,
  model,
  new StringOutputParser()
]);

// Ejecutar la cadena
const resultado = await chain.invoke({
  idioma: "francés",
  texto: "Hola, ¿cómo estás?"
});
console.log(resultado);
```

## Documentación de API

Para más detalles sobre las clases, interfaces y métodos disponibles, consulta la documentación completa.

## Contribuir

Las contribuciones son bienvenidas. Para contribuir:

1. Haz un fork del repositorio en [https://github.com/Alex66688/nvidia-llama4](https://github.com/Alex66688/nvidia-llama4)
2. Crea una rama con tu nueva característica (`git checkout -b feature/amazing-feature`)
3. Haz commit de tus cambios (`git commit -m 'Añadir nueva característica'`)
4. Haz push a la rama (`git push origin feature/amazing-feature`)
5. Abre un Pull Request