Documentación

Inicio rápido

Genera el backend que nadie quiere escribir dos veces, y evita que se degrade mientras un equipo — o un agente — trabaja sobre él.

Correrlo en local

JFastFramework está en PyPI como pre-release. Con pip install jfastframework alcanza para usarlo; instala desde un checkout cuando pienses cambiar el framework mismo.

El ciclo local

Levanta los contenedores y espera a que estén sanos, aplica las migraciones, y recién entonces arranca la API, el worker de la cola y el frontend. Un comando para las cosas que uno hace cada mañana, en el orden que hace que las fallas aparezcan donde corresponde.

Arquitectura

Cada decisión aquí tiene un costo. Este documento nombra las dos caras.

Módulos y arquitecturas

Dos niveles de generación:

Contratos

AGENTS.md dice qué hacer. Un contrato dice qué está permitido, y algo lo verifica.

Inspeccionar y analizar

check es una línea de tu pipeline, no el pipeline: no corre ningún linter, ningún type checker ni ningún test — ver Qué NO chequea check.

Código compartido y eventos

Dos features, una misma idea: acoplamiento fácil de agregar, invisible una vez agregado, y caro de sacar después de que una segunda persona copió el patrón. Por eso los dos se verifican en vez de acordarse.

Almacenes de datos

Cada datastore es un plugin. Habilita lo que el servicio necesita, y el cliente, el health check y el contenedor llegan todos juntos.

RAG y búsqueda vectorial

Ingerir documentos, encontrar los pasajes que responden una pregunta y dárselos a un modelo con citas. El plugin rag hace la mitad de recuperación; el plugin llm hace la de responder y paga los embeddings.

Modelos de lenguaje

Chat, salida estructurada, visión y embeddings sobre cualquier API compatible con OpenAI, detrás de un tope de gasto que se sostiene entre workers.

Transacciones

Cuándo se confirman las escrituras de una request, en qué se convierte una escritura que falla, y cómo se evita que dos requests que compiten por la misma fila ganen las dos.

Colas y eventos

Dos cosas distintas, a propósito en dos plugins distintos -- y, entre los módulos de un mismo servicio, una tercera construida sobre la primera: los eventos de dominio locales, que no necesitan broker.

Llamar a otros servicios

jfastframework.http es el cliente con el que un servicio llama a sus hermanos. Existe para que cada servicio no escriba el suyo, y para que las cuatro cosas que todo cliente hecho a mano resuelve mal se decidan una sola vez: cuánto esperar, qué reintentar, cuándo dejar de llamar a un upstream que está caído, y cuántas llamadas dejar que se apilen detrás de uno lento.

Frontends

Dos maneras de poner una UI delante de un backend JFast. Elige según si quieres un paso de build o no.

Paquetes

Nada de este catálogo se instala por defecto. Un servicio que sirve JSON no debería cargar con numpy — y en cuanto lo hace, el grafo de plugins deja de describir lo que el servicio realmente necesita, que es la propiedad que hace que el grafo valga la pena.

Escribir un plugin

Un plugin es una clase con metadata y hasta cinco hooks opcionales. Nada más.

Workspaces

Un solo servicio no necesita workspace. En cuanto hay dos, aparecen tres preguntas que la configuración por servicio no puede responder:

Despliegue

Los artefactos de deploy se generan a partir del grafo de plugins, no se mantienen a mano. Deshabilitas un plugin y su contenedor desaparece del siguiente compose generado. Esa es toda la idea: la infraestructura no puede desviarse de lo que la aplicación realmente carga.

Telemetría

Los logs dicen qué hizo un servicio; las métricas, con qué frecuencia. Ninguno sigue un request por la API, su SQL, una llamada a un modelo, un segundo servicio y el job que encoló -- que es lo primero que hace falta cuando algo va lento en producción. El plugin telemetry hace eso con trazas de OpenTelemetry, exportadas por OTLP a cualquier cosa que lo hable: Jaeger, Grafana Tempo, Honeycomb, Datadog, un OpenTelemetry Collector.

Kubernetes

jfast init te pregunta si lo necesitas y escribe el árbol si dices que sí.

Resiliencia

Qué hace un servicio cuando algo de lo que depende deja de responder: cuánto espera, si reintenta, cuándo deja de preguntar, qué recibe el cliente y qué dice /ready. Todo viene encendido por defecto. Esta página lista los números, las razones detrás de ellos y los drills que los comprueban contra servidores reales.

Escalar

Cada afirmación de capacidad en esta página es un número de una corrida, con la máquina, los tamaños y el método al lado. Donde un número sería una suposición, la página lo dice en vez de darlo.

Nube

Tres cosas que un servicio necesita apenas sale de tu laptop: configuración que no puede vivir en un archivo, una forma de correr algo sin servidor, y una forma de llegar a un teléfono.

Migraciones y tests

Las dos vienen cableadas en cada servicio generado. Ninguna es algo que tengas que configurar.

Zonas horarias

El almacenamiento quedó resuelto en 0.1.0a4: UTCDateTime escribe UTC, lee UTC, y rechaza un datetime naive al escribir. Esta página trata la otra mitad — calcular con esos valores — que es donde un deploy multi-región falla de verdad.

Autenticación

Verificación de JWT, scopes, rotación de claves y revocación.

Cuentas

Usuarios, login con contraseña, roles y permisos: el almacén de usuarios que el plugin auth deja fuera a propósito, como un plugin que se activa.

Cifrado

Algunos secretos que guarda un servicio son datos de sus usuarios, y tiene que poder leerlos de vuelta: la contraseña que abre la firma electrónica de un cliente, un token de su banco. Un hash no sirve -- el valor se necesita en claro para usarlo -- y SecretStr solo lo mantiene fuera de los logs; la base sigue guardando el texto plano. jfastframework.encryption es para esos casos.

Límite de peticiones

Un endpoint de login sin rate limit es un blanco de credential stuffing. Este plugin es el límite, y vive en la aplicación y no en el edge.

Almacenamiento

Los archivos viven en un disco con nombre. Tu código escribe en "public" o "invoices"; que ese disco sea un directorio, un bucket de S3 o un contenedor de MinIO es configuración. El mismo handler funciona en desarrollo y en producción sin un solo cambio.

Multi-tenancy

Un solo deploy, muchos clientes, cada uno viendo solo sus propios datos.

Websockets

Un mensaje se dirige a una persona, no a un socket. Qué worker tiene abierta la conexión de esa persona no es algo que tu código deba saber.

Servicios políglotas

Un servicio JFast no es "un servicio escrito con JFast". Es un servicio que cumple este contrato. Esa distinción es toda la razón por la que un servicio en Go y uno en Python pueden estar detrás del mismo gateway, tomar puertos del mismo workspace, y ser expuestos por el mismo Caddyfile — nada de lo cual sabe ni le importa qué lenguaje los produjo.

Trabajar con agentes de IA

La premisa de este framework es que un agente escribiendo código en tu repositorio ya es normal, y que lo que lo hace sobrevivible no es un prompt mejor — son reglas que el agente no puede romper en silencio.

Skills para agentes

Una skill es una carpeta con un SKILL.md: instrucciones para una tarea, escritas para que un agente pueda ejecutarla sin reconstruir el contexto a partir del árbol de fuentes.

Madurez

Un solo número de versión no puede describir este repositorio con honestidad. El kernel está testeado, tipado y ejercitado por CI en cada push; el cliente de Kafka nunca habló con un broker. Llamar "0.7.0" a los dos no le decía nada al lector, y por eso el paquete vuelve a empezar en 0.1.0a1 y por eso la madurez se registra aquí, por subsistema.

Hoja de ruta

Las fases están ordenadas por dependencia, no por ambición. Cada una termina con algo usable; nada se entrega a medias dentro de la fase siguiente.

Actualizar

Compara la versión del framework que el proyecto fija contra la instalada, y reporta los cambios que hay en medio que este proyecto puede sentir de verdad.

Cambios

Formato: Keep a Changelog. Versionado: SemVer con identificadores de pre-release según PEP 440. Mientras la API esté en pre-alpha, los servicios fijan la versión exacta (jfastframework==0.1.0a5); un pin de release compatible (~=) empieza a tener sentido en 0.2.