Cómo Procesar PDFs Gratis con Formmy SDK en Node.js

Introducción

En este tutorial aprenderás a usar Formmy SDK para procesar documentos PDF y extraer su contenido de forma completamente gratuita usando el modo DEFAULT. Formmy es una plataforma RAG (Retrieval-Augmented Generation) que maneja todo el procesamiento de documentos por ti.

¿Qué es Formmy?

Formmy es un servicio que convierte documentos (PDF, DOCX, XLSX) en contenido estructurado y te permite hacer búsquedas semánticas sobre ellos. Piensa en ello como un asistente que:

1. Lee tus documentos
2. Extrae el contenido de manera inteligente
3. Te permite hacer preguntas sobre ese contenido

Requisitos Previos

• Node.js instalado (versión 16 o superior)
• Un editor de código (VS Code, Sublime, etc.)
• Una cuenta en Formmy (registrarse en https://www.formmy.app)

Paso 1: Obtener tus Credenciales

1. Ve a https://www.formmy.app
2. Crea una cuenta o inicia sesión
3. Copia tu API Key (comienza con sk_live_ o sk_test_)
4. Copia tu Chatbot ID (un identificador único para tu base de conocimientos)

Paso 2: Configurar el Proyecto

Crea un nuevo directorio para tu proyecto:

mkdir formmy-demo
cd formmy-demo

Inicializa un proyecto Node.js:

npm init -y

Actualiza el package.json para usar módulos ES:

{
  "name": "formmy-agent-demo",
  "version": "1.0.0",
  "description": "Demostración básica del uso de formmy-sdk",
  "type": "module",
  "main": "agent.js",
  "scripts": {
    "start": "node agent.js",
    "dev": "node --watch agent.js"
  },
  "keywords": ["formmy", "rag", "agent", "demo"],
  "author": "",
  "license": "MIT",
  "dependencies": {
    "dotenv": "^16.4.5",
    "formmy-sdk": "^1.0.4"
  }
}

Instala las dependencias:

npm install

Paso 3: Configurar Variables de Entorno

Crea un archivo .env en la raíz del proyecto:

# Formmy SDK Credentials
FORMMY_API_KEY=sk_live_TU_API_KEY_AQUI
CHATBOT_ID=tu_chatbot_id_aqui

Reemplaza los valores con tus credenciales reales.

Paso 4: Crear el Script

Crea un archivo agent.js con el siguiente código:

#!/usr/bin/env node
import { Formmy } from 'formmy-sdk';
import dotenv from 'dotenv';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
import fs from 'fs';

// Cargar variables de entorno
dotenv.config();

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Colores para la consola
const colors = {
  reset: '\x1b[0m',
  bright: '\x1b[1m',
  green: '\x1b[32m',
  blue: '\x1b[34m',
  yellow: '\x1b[33m',
  cyan: '\x1b[36m',
  red: '\x1b[31m',
};

function log(message, color = 'reset') {
  console.log(`${colors[color]}${message}${colors.reset}`);
}

async function main() {
  try {
    // Configuración
    const apiKey = process.env.FORMMY_API_KEY;
    const chatbotId = process.env.CHATBOT_ID;

    if (!apiKey || !chatbotId) {
      throw new Error('Faltan variables de entorno: FORMMY_API_KEY o CHATBOT_ID');
    }

    log('\n🤖 Formmy SDK Agent - Demo Básica\n', 'bright');
    log('═'.repeat(50), 'cyan');

    // Inicializar el SDK
    log('\n📦 Inicializando Formmy SDK...', 'blue');
    const parser = new Formmy({
      apiKey,
      debug: false,
      timeout: 60000, // 1 minuto
    });
    log('✅ SDK inicializado correctamente', 'green');

    // ============================================
    // PASO 1: Subir y procesar documento
    // ============================================
    log('\n📄 PASO 1: Subir y procesar documento', 'bright');
    log('─'.repeat(50), 'cyan');

    const docPath = join(__dirname, 'documento.pdf');

    // Verificar si el documento existe
    if (!fs.existsSync(docPath)) {
      log(`⚠️  El archivo ${docPath} no existe. Créalo primero.`, 'yellow');
      log('💡 Coloca cualquier PDF con el nombre "documento.pdf" en este directorio', 'yellow');
      return;
    }

    log(`📁 Archivo: ${docPath}`, 'cyan');
    log('⏳ Subiendo documento con modo DEFAULT (0 créditos - GRATIS)...', 'yellow');

    const job = await parser.parse(docPath, 'DEFAULT');

    log(`✅ Job creado: ${job.id}`, 'green');
    log(`📊 Estado inicial: ${job.status}`, 'cyan');

    // Esperar a que se complete el procesamiento
    log('\n⏳ Esperando a que se complete el procesamiento...', 'yellow');

    const completedJob = await parser.waitFor(job.id, {
      interval: 2000, // Verificar cada 2 segundos
      maxWaitTime: 300000, // Máximo 5 minutos
      onProgress: (progressJob) => {
        log(`   📍 Estado: ${progressJob.status}`, 'cyan');
      }
    });

    log('\n✅ Procesamiento completado!', 'green');
    log(`📝 Páginas procesadas: ${completedJob.pageCount || 'N/A'}`, 'cyan');
    log(`💰 Créditos usados: ${completedJob.creditsUsed}`, 'cyan');
    log(`⏱️  Tiempo de procesamiento: ${completedJob.processingTime || 'N/A'}ms`, 'cyan');

    if (completedJob.markdown) {
      log('\n📄 Contenido extraído (primeros 500 caracteres):', 'blue');
      log(completedJob.markdown.substring(0, 500) + '...', 'reset');

      // Guardar el resultado completo en un archivo
      const outputPath = join(__dirname, 'resultado.md');
      fs.writeFileSync(outputPath, completedJob.markdown);
      log(`\n💾 Contenido completo guardado en: ${outputPath}`, 'green');
    }

    // ============================================
    // Resumen final
    // ============================================
    log('\n\n✅ DEMO COMPLETADA EXITOSAMENTE', 'bright');
    log('═'.repeat(50), 'cyan');
    log('\n💡 El SDK de Formmy permite:', 'blue');
    log('   • Procesar documentos automáticamente', 'cyan');
    log('   • Extraer contenido estructurado', 'cyan');
    log('   • Realizar búsquedas semánticas', 'cyan');
    log('   • Generar respuestas inteligentes\n', 'cyan');

  } catch (error) {
    log('\n❌ ERROR:', 'red');

    if (error.name === 'AuthenticationError') {
      log('🔑 Error de autenticación. Verifica tu API Key.', 'red');
    } else if (error.name === 'InsufficientCreditsError') {
      log(`💳 Créditos insuficientes. Necesitas: ${error.required}, Tienes: ${error.available}`, 'red');
    } else if (error.name === 'TimeoutError') {
      log(`⏱️  Timeout: El procesamiento tomó más de ${error.duration}ms`, 'red');
    } else if (error.name === 'ValidationError') {
      log(`⚠️  Error de validación: ${error.message}`, 'red');
    } else {
      log(`${error.message}`, 'red');
      if (error.stack) {
        log(`\n${error.stack}`, 'reset');
      }
    }

    process.exit(1);
  }
}

// Ejecutar el agente
main();

Paso 5: Agregar un Documento PDF

Coloca cualquier archivo PDF en el directorio del proyecto con el nombre documento.pdf.

Por ejemplo, puedes usar:

• Un PDF de tu curriculum
• Una factura
• Un artículo académico
• Cualquier documento que quieras procesar

Paso 6: Ejecutar el Demo

Ejecuta el script:

npm start

Verás una salida como esta:

🤖 Formmy SDK Agent - Demo Básica

══════════════════════════════════════════════════

📦 Inicializando Formmy SDK...
✅ SDK inicializado correctamente

📄 PASO 1: Subir y procesar documento
──────────────────────────────────────────────────
📁 Archivo: /ruta/documento.pdf
⏳ Subiendo documento con modo DEFAULT (0 créditos - GRATIS)...
✅ Job creado: 68fba48330d1611dfbf2c08c
📊 Estado inicial: PENDING

⏳ Esperando a que se complete el procesamiento...
   📍 Estado: PROCESSING
   📍 Estado: COMPLETED

✅ Procesamiento completado!
📝 Páginas procesadas: N/A
💰 Créditos usados: 0
⏱️  Tiempo de procesamiento: 0.24ms

📄 Contenido extraído (primeros 500 caracteres):
[Contenido de tu PDF aquí...]

💾 Contenido completo guardado en: /ruta/resultado.md

✅ DEMO COMPLETADA EXITOSAMENTE
══════════════════════════════════════════════════

💡 El SDK de Formmy permite:
   • Procesar documentos automáticamente
   • Extraer contenido estructurado
   • Realizar búsquedas semánticas
   • Generar respuestas inteligentes

¿Qué Acaba de Pasar?

1. Inicialización: El SDK se conectó a Formmy con tus credenciales
2. Upload: Tu PDF se subió al servicio
3. Procesamiento: Formmy extrajo el texto del PDF
4. Resultado: Obtienes el contenido en formato markdown (guardado en resultado.md)
5. Costo: 0 créditos gracias al modo DEFAULT

Modos de Procesamiento Disponibles

Formmy ofrece 4 modos de procesamiento:

DEFAULT - 0 créditos (GRATIS)

• Características: Extracción básica de texto
• Uso recomendado: Pruebas, documentos simples
• Ideal para: Experimentar con el SDK sin costo

COST_EFFECTIVE - 1 crédito/página

• Características: Extracción AI rápida
• Uso recomendado: Producción económica
• Ideal para: Aplicaciones con presupuesto limitado

AGENTIC - 3 créditos/página

• Características: Tablas estructuradas, mejor calidad
• Uso recomendado: Documentos de negocios
• Ideal para: Facturas, reportes, contratos

AGENTIC_PLUS - 6 créditos/página

• Características: OCR avanzado, imágenes, máxima precisión
• Uso recomendado: PDFs complejos, escaneados
• Ideal para: Documentos escaneados, con imágenes o baja calidad

Para cambiar el modo, simplemente modifica esta línea en agent.js:

// Modo gratuito
const job = await parser.parse(docPath, 'DEFAULT');

// O modo premium
const job = await parser.parse(docPath, 'AGENTIC');

Próximos Pasos

Una vez que domines el procesamiento básico, puedes explorar:

1. Búsquedas RAG: Hacer preguntas sobre tus documentos
2. Upload de texto directo: Agregar contenido sin archivos
3. Integración con LlamaIndex: Crear agentes inteligentes
4. Batch processing: Procesar múltiples documentos

Solución de Problemas

Error: "Faltan variables de entorno"

• Verifica que el archivo .env existe
• Confirma que las variables están correctamente configuradas

Error de autenticación

• Verifica tu API Key en la plataforma de Formmy
• Asegúrate de usar sk_live_ para producción o sk_test_ para pruebas

El archivo PDF no se encuentra

• Asegúrate de que el PDF se llama documento.pdf
• Verifica que está en el mismo directorio que agent.js

Conclusión

¡Felicidades! Ahora sabes cómo procesar PDFs de forma gratuita con Formmy SDK. Este es solo el comienzo - Formmy puede hacer mucho más que solo extraer texto.

Recursos

• Documentación oficial: https://www.formmy.app/docs
• Plataforma: https://www.formmy.app
• npm package: https://www.npmjs.com/package/formmy-sdk

Código Completo

Puedes encontrar el código completo de este tutorial en GitHub: [enlace al repositorio]

---

¿Te gustó este tutorial? Déjanos saber qué otros temas te gustaría que cubramos.