🚀 Google Generative AI Chat API — Context Cache

Un servidor Express listo para chatear con Gemini usando Context Cache: sube tus fuentes una vez, crea un caché remoto y úsalo como contexto base en tus conversaciones. ✨

---

📚 Tabla de contenidos

• 🧠 Qué es y cómo funciona
• ⚙️ Instalación rápida
• 🔐 Configuración (.env)
• 🧪 Healthcheck
• 🧩 API (endpoints)
• 🛠️ CLI (comandos)
• 📦 Estructura sugerida
• 📘 Ejemplos
• ❓ FAQ y tips

---

🧩 API (endpoints)

1️⃣ Context Cache

POST /api/cache/setup

{
  "filePath": "string",
  "mimeType": "string",
  "displayName": "string",
  "model": "string",
  "ttlSeconds": "number",
  "systemInstruction": "string",
  "cacheDisplayName": "string"
}

Sube el archivo, espera el procesamiento, crea el caché remoto y guarda el nombre en cache.json

GET /api/cache

Información del caché guardado

DELETE /api/cache

Elimina la referencia local (no borra el caché remoto)

---

2️⃣ Chat

POST /api/chat

{
  "question": "string", // requerido
  "cache": "string", // opcional, nombre del caché
  "model": "string", // opcional, modelo a usar
  "files": [
    // opcional, rutas de archivos locales o URLs
    "data/cache_sources/mi-archivo.pdf"
  ]
}

Usa el caché como contexto base y puede adjuntar archivos adicionales (PDF, TXT, MD) como rutas locales o URLs.

---

3️⃣ Healthcheck

GET /health

Devuelve { status: 'ok' } si el servidor está activo.

• PORT=3000

Modelos: usa uno que soporte createCachedContent (por ejemplo models/gemini-2.5-pro).

---

🧪 Healthcheck

GET /health → { status: 'ok' }

---

🧩 API (endpoints)

1️⃣ Context Cache

POST /api/cache/setup

{
  "filePath": "string",
  "mimeType": "string",
  "displayName": "string",
  "model": "string",
  "ttlSeconds": "number",
  "systemInstruction": "string",
  "cacheDisplayName": "string"
}

Sube el archivo, espera el procesamiento, crea el caché remoto y guarda el nombre en cache.json

GET /api/cache

Información del caché guardado

DELETE /api/cache

Elimina la referencia local (no borra el caché remoto)

---

2️⃣ Chat

POST /api/chat

{
  "question": "string",
  "context": "string",
  "files": [
    {
      "path": "string",
      "mimeType": "string",
      "displayName": "string"
    }
  ]
}

Usa el caché como contexto base + contexto/archivos opcionales

🛠️ CLI (comandos)

Comando	Descripción	Uso
list-models	Lista modelos y métodos soportados	npm run list-models
setup-cache	Sube fuentes y crea un Context Cache	npm run setup-cache -- [dir] [displayName] [model] [ttl] [systemInstruction]
list-caches	Lista cachés remotos	npm run list-caches
delete-cache	Elimina un caché remoto por name o ID	npm run delete-cache -- cachedContents/XXX o npm run delete-cache -- XXX

Tip: usa npm run list-caches para copiar el campo name exacto.

---

📦 Estructura sugerida

.
├─ data/
│  └─ cache_sources/      # Tus fuentes (.pdf, .txt, .md, ...)
├─ src/
│  ├─ cli/                # Scripts CLI
│  └─ server.js           # Servidor Express
├─ cache.json             # Nombre del caché guardado
└─ .env                   # GEMINI_API_KEY

---

📘 Ejemplos

JSON (ruta local en el servidor):

curl -X POST http://localhost:3000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "¿Qué documentos faltan?",
    "context": "Embarque MX-001",
    "files": [{
      "path": "data/cache_sources/mi-archivo.pdf",
      "mimeType": "application/pdf",
      "displayName": "mi-archivo.pdf"
    }]
  }'

---

❓ FAQ y tips

• Asegúrate de que el modelo soporte createCachedContent.
• Si no tienes .env.example, crea .env y añade GEMINI_API_KEY.
• Puedes recrear el caché cuando caduque usando la CLI.