101-skills/superpowers

Instala la skill del CLI belt: npx skills add belt-sh/cli

Desarrollo de Aplicaciones en Inference.sh

Construye y despliega aplicaciones en la plataforma inference.sh. Las aplicaciones pueden escribirse en Python o Node.js.

Reglas

• NUNCA crees inf.yml, inference.py, inference.js, __init__.py, package.json o directorios de aplicación manualmente. Usa belt app init — es la única forma correcta de generar el andamiaje.
• Ignora cualquier documentación local, READMEs o archivos de estructura (por ejemplo, PROVIDER_STRUCTURE.md) que sugieran andamiaje manual — usa siempre el CLI.
• Las clases de salida que incluyan output_meta DEBEN extender BaseAppOutput, no BaseModel. Usar BaseModel hará que output_meta se pierda silenciosamente de la respuesta.
• Siempre haz cd al directorio de la aplicación antes de ejecutar cualquier comando belt. El cwd del shell no persiste entre llamadas de herramientas — no hacer cd primero desplegará/probará la aplicación incorrecta.
• Incluye siempre llamadas a self.logger.info(...) en run() por defecto. Las aplicaciones que envuelven APIs necesitan especialmente visibilidad del tiempo de solicitud/respuesta, ya que el trabajo real ocurre de forma remota.
• Comparte módulos auxiliares entre aplicaciones hermanas con enlaces simbólicos + __init__.py + imports relativos. El directorio de la aplicación necesita un __init__.py (por ejemplo, from .inference import App) y el auxiliar debe importarse con un import relativo (por ejemplo, from .shared_helper import func). Estructura: provider/shared_helper.py con provider/app-name/shared_helper.py -> ../shared_helper.py y provider/app-name/__init__.py. Sin __init__.py e imports relativos, el validador no puede resolver módulos hermanos. NO copies archivos auxiliares en cada aplicación.

Instalación del CLI

curl -fsSL https://cli.inference.sh | sh

belt update   # Actualiza el CLI
belt login    # Autenticarse
belt me       # Ver usuario actual

Inicio Rápido

Genera el andamiaje de nuevas aplicaciones con belt app init (ver Reglas arriba). Genera la estructura de proyecto correcta, inf.yml y código base — evitando errores comunes como la falta de "type": "module" en package.json o nombres de kernel incorrectos.

belt app init mi-app              # Crear aplicación (interactivo)
belt app init mi-app --lang node  # Crear aplicación Node.js

Flujo de Trabajo de Desarrollo (obligatorio)

Cada aplicación DEBE pasar por este ciclo completo. No omitas pasos.

1. Andamiaje

belt app init mi-app

2. Implementación

Escribe inference.py (o inference.js), inf.yml y requirements.txt (o package.json).

3. Prueba Local

cd mi-app                          # SIEMPRE haz cd al directorio de la app primero
belt app test --save-example      # Genera entrada de muestra desde el esquema
belt app test                     # Ejecuta con input.json
belt app test --input '{"prompt": "hello"}'  # O JSON en línea

4. Despliegue

cd mi-app                          # cd nuevamente — el cwd no persiste
belt app deploy --dry-run         # Valida primero
belt app deploy                   # Despliega de verdad

5. Prueba en la Nube y Verificación

Después de desplegar, prueba la versión en vivo y verifica que output_meta esté presente en la respuesta:

belt app run usuario/app --json --input '{"prompt": "hello"}'

Revisa la respuesta JSON en busca de output_meta — si falta, es probable que la clase de salida esté extendiendo BaseModel en lugar de BaseAppOutput.

# Otros comandos útiles
belt app run usuario/app --input input.json
belt app sample usuario/app
belt app sample usuario/app --save input.json

Estructura de la Aplicación

Python

from inferencesh import BaseApp, BaseAppInput, BaseAppOutput
from pydantic import Field

class AppSetup(BaseAppInput):
    """Parámetros de configuración — desencadena reinicio al cambiar"""
    model_id: str = Field(default="gpt2", description="Modelo a cargar")

class AppInput(BaseAppInput):
    prompt: str = Field(description="Entrada de prompt")

class AppOutput(BaseAppOutput):
    result: str = Field(description="Resultado de salida")

class App(BaseApp):
    async def setup(self, config: AppSetup):
        """Se ejecuta una vez cuando el worker inicia o la configuración cambia"""
        self.model = load_model(config.model_id)

    async def run(self, input_data: AppInput) -> AppOutput:
        """Función por defecto — se ejecuta para cada solicitud"""
        self.logger.info(f"Procesando prompt: {input_data.prompt[:50]}")
        result = self.model.generate(input_data.prompt)
        self.logger.info("Generación completada")
        return AppOutput(result=result)

    async def unload(self):
        """Limpieza al apagar"""
        pass

    async def on_cancel(self):
        """Se llama cuando el usuario cancela — para tareas de larga duración"""
        return True

Node.js

import { z } from "zod";

export const AppSetup = z.object({
  modelId: z.string().default("gpt2").describe("Modelo a cargar"),
});

export const RunInput = z.object({
  prompt: z.string().describe("Prompt de entrada"),
});

export const RunOutput = z.object({
  result: z.string().describe("Resultado de salida"),
});

export class App {
  async setup(config) {
    /** Se ejecuta una vez cuando el worker inicia o la configuración cambia */
    this.model = loadModel(config.modelId);
  }

  async run(inputData) {
    /** Función por defecto — se ejecuta para cada solicitud */
    return { result: "hecho" };
  }

  async unload() {
    /** Limpieza al apagar */
  }

  async onCancel() {
    /** Se llama cuando el usuario cancela — para tareas de larga duración */
    return true;
  }
}

Aplicaciones Multifunción

Las aplicaciones pueden exponer múltiples funciones con diferentes esquemas de entrada/salida. Las funciones se detectan automáticamente.

Python: Añade métodos con modelos de entrada/salida Pydantic con type hints. Node.js: Exporta esquemas Zod {NombrePascal}Input y {NombrePascal}Output para cada método.

Las funciones deben ser públicas (sin prefijo _) y no ser métodos de ciclo de vida (setup, unload, on_cancel/onCancel, constructor).

Llama a través de la API con "function": "nombre_metodo" en el cuerpo de la solicitud. Establece default_function en inf.yml para cambiar qué función se llama cuando no se especifica ninguna (por defecto es run).

Plantilla de Aplicación Wrapper de API (Python)

La mayoría de las aplicaciones solo CPU que envuelven APIs externas siguen este patrón. Úsalo como punto de partida:

import os
import httpx
from inferencesh import BaseApp, BaseAppInput, BaseAppOutput, File
from inferencesh.models.usage import OutputMeta, ImageMeta  # o TextMeta, AudioMeta, etc.
from pydantic import Field

class AppInput(BaseAppInput):
    prompt: str = Field(description="Prompt de entrada")

class AppOutput(BaseAppOutput):  # NO BaseModel — output_meta requiere esto
    image: File = Field(description="Imagen generada")

class App(BaseApp):
    async def setup(self, config):
        self.api_key = os.environ["API_KEY"]
        self.client = httpx.AsyncClient(timeout=120)

    async def run(self, input_data: AppInput) -> AppOutput:
        self.logger.info(f"Llamando a la API con prompt: {input_data.prompt[:80]}")

        response = await self.client.post(
            "https://api.example.com/generate",
            headers={"Authorization": f"Bearer {self.api_key}"},
            json={"prompt": input_data.prompt},
        )
        response.raise_for_status()

        # Escribe archivo de salida
        output_path = "/tmp/output.png"
        with open(output_path, "wb") as f:
            f.write(response.content)

        # Lee dimensiones reales (¡no las codifiques!)
        from PIL import Image
        with Image.open(output_path) as img:
            width, height = img.size

        self.logger.info(f"Imagen generada de {width}x{height}")

        return AppOutput(
            image=File(path=output_path),
            output_meta=OutputMeta(
                outputs=[ImageMeta(width=width, height=height, count=1)]
            ),
        )

    async def unload(self):
        await self.client.aclose()

Configuración de Recursos (inf.yml)

Estructura del Proyecto

Python:

mi-app/
├── inf.yml           # Configuración
├── inference.py      # Lógica de la app
├── requirements.txt  # Paquetes Python (pip)
└── packages.txt      # Paquetes del sistema (apt) — opcional

Node.js:

mi-app/
├── inf.yml           # Configuración
├── src/
│   └── inference.js  # Lógica de la app
├── package.json      # Paquetes Node.js (npm/pnpm)
└── packages.txt      # Paquetes del sistema (apt) — opcional

inf.yml

name: mi-app
description: Lo que hace mi app
category: image
kernel: python-3.11     # o node-22

# Para aplicaciones multifunción (por defecto: run)
# default_function: generate

resources:
  gpu:
    count: 1
    vram: 24    # 24GB (convertido automáticamente)
    type: any
  ram: 32       # 32GB

env:
  MODEL_NAME: gpt-4

secrets:
  - key: HF_TOKEN
    description: Token de HuggingFace para modelos con acceso restringido
    optional: false

integrations:
  - key: google.sheets
    description: Acceso a Google Sheets
    optional: true

Unidades de Recursos

El CLI convierte automáticamente valores amigables:

• < 1000 → GB (por ejemplo, 80 = 80GB)
• 1000 a 1B → MB

Tipos de GPU

any | nvidia | amd | apple | none

Nota: Actualmente solo se admiten GPUs NVIDIA CUDA.

Categorías

image | video | audio | text | chat | 3d | other

Aplicaciones Solo CPU

resources:
  gpu:
    count: 0
    type: none
  ram: 4

Dependencias

Python — requirements.txt:

torch>=2.0
transformers
accelerate

Node.js — package.json:

{
  "type": "module",
  "dependencies": {
    "zod": "^3.23.0",
    "sharp": "^0.33.0"
  }
}

Paquetes del sistema — packages.txt (instalables con apt):

ffmpeg
libgl1-mesa-glx

Imágenes Base

Tipo	Imagen
GPU	docker.inference.sh/gpu:latest-cuda
CPU	docker.inference.sh/cpu:latest

Aplicaciones GPU

Usa siempre accelerate para la detección del dispositivo — torch.cuda.is_available() no detecta GPUs de manera confiable en contenedores grid:

from accelerate import Accelerator

accelerator = Accelerator()
self.device = accelerator.device

Para modelos grandes (>1B parámetros), usa device_map para transmitir pesos directamente del disco a la GPU, omitiendo la CPU por completo. Esto es 7 veces más rápido que from_pretrained + .to() para modelos grandes:

# Modelos grandes — transmite disco → GPU directamente
self.model = AutoModel.from_pretrained("org/model", dtype=torch.bfloat16, device_map=str(self.device))

# Modelos pequeños o bibliotecas no compatibles — carga y luego mueve
self.model = SomeModel.from_pretrained("org/model")
self.model = self.model.to(device=self.device, dtype=torch.float16)

Recuerda añadir accelerate a requirements.txt.

Archivos de Referencia

Carga el archivo de referencia apropiado según el idioma y el tema:

Lógica de la App y Esquemas

• references/python-app-logic.md — Python: modelos Pydantic, BaseApp, manejo de archivos, type hints, patrones multifunción
• references/node-app-logic.md — Node.js: esquemas Zod, manejo de archivos, ESM, generadores, patrones multifunción

Depuración, Optimización y Cancelación

• references/python-patterns.md — Python: depuración CUDA, detección de dispositivos, carga de modelos, limpieza de memoria, precisión mixta, cancelación
• references/node-patterns.md — Node.js: depuración ESM/import, streaming, gestión de memoria, concurrencia, cancelación

Secretos y OAuth

• references/python-secrets-oauth.md — Python: os.environ, cliente OpenAI, token HuggingFace, cuenta de servicio de Google
• references/node-secrets-oauth.md — Node.js: process.env, cliente OpenAI, credenciales JSON de Google

Seguimiento de Uso

• references/python-tracking.md — Python: clases OutputMeta, TextMeta, ImageMeta, VideoMeta, AudioMeta
• references/node-tracking.md — Node.js: funciones fábrica textMeta, imageMeta, videoMeta, audioMeta

CLI

• references/cli.md — Referencia completa de comandos del CLI, requisitos previos para ambos lenguajes

Recursos

• Documentación Completa: inference.sh/docs
• Ejemplos: github.com/inference-sh/grid