DEV Community: Martin Palopoli

Del repo a producción con un solo comando: cómo Fitz hace del deployment una feature del lenguaje

Martin Palopoli — Thu, 11 Jun 2026 13:57:00 +0000

Un recorrido por la historia de deployment de Fitz — healthchecks, secrets como tipos opacos, observability con OpenTelemetry, Dockerfiles autogenerados y fitz deploy. Production-ready no es una checklist, es sintaxis.

La historia de deployment que la mayoría de los lenguajes no cuenta

El primer 80% de un servicio es divertido: rutas, types, lógica de negocio, tests. El último 20% es la parte que efectivamente entrega la cosa, y ahí es donde todo el mundo pega con cinta cinco herramientas distintas:

Una librería de healthcheck estilo psutil porque Kubernetes quiere /healthz.
python-decouple o pydantic-settings para env vars, más tu propia clase Secret que con suerte no termina en logs.
opentelemetry-instrumentation-fastapi más opentelemetry-exporter-otlp-proto-http más opentelemetry-instrumentation-sqlalchemy más cualquiera sea la combinación correcta de versiones este mes.
Un Dockerfile copiado de un post de blog, con tres cosas mal para tu setup.
Un docker-compose.yml que está bien excepto por el env var que tiene que venir de .env.production.
Un Makefile o justfile con los comandos reales, o un YAML de CI que hace el equivalente.

Llevo diez años haciendo esto en cada proyecto. Es la parte donde el lenguaje deja de ayudarte. Fitz se niega a hacer eso. Deployment está en el lenguaje.

Acá está el stack completo de producción en Fitz, y qué reemplaza cada pieza.

Health checks como decoradores

@server(43928)
fn main() => 0

@healthz
fn liveness() -> Bool => true

@readyz
async fn readiness(db: DbConn) -> Bool {
    return match db.exec("SELECT 1").await {
        Ok(_) => true,
        Err(_) => false,
    }
}

/healthz y /readyz se auto-montan en el router HTTP. Nada para importar, ninguna librería para configurar. El return value de la función determina el HTTP status (200 si true, 503 si false). Kubernetes contento.

El compilador también hace cumplir el shape: la función retorna Bool o Result<Bool>, toma un DbConn si lo necesita (el runtime lo inyecta). Si te olvidás del @readyz entero, el endpoint de readiness simplemente no existe — no hay librería que "casi configures" mal.

En Python:

# requirements.txt: starlette-healthcheck, pyhealthcheck, ...
from healthcheck import HealthCheck
health = HealthCheck()
def db_check():
    try:
        db.execute("SELECT 1")
        return True, "ok"
    except Exception as e:
        return False, str(e)
health.add_check(db_check)
app.add_route("/healthz", health.run)  # acordate de montarlo

En Fitz:

@readyz
async fn readiness(db: DbConn) -> Bool {
    return match db.exec("SELECT 1").await { Ok(_) => true, Err(_) => false }
}

Eso es todo. Misma semántica, sin librería, sin paso de mounting, sin docs que tenés que volver a leer.

Secrets como tipos opacos

El bug que más vi en código de producción: alguien loguea la password, la API key, el JWT secret. El logger entrega a Loki / Splunk / Sentry / lo que sea. El secret está ahora en logs de producción. Todo el mundo está de acuerdo en que esto es malo. Nadie tiene una buena respuesta en las librerías estándar — os.environ["FOO"] es solo un string. pydantic.SecretStr existe pero tenés que opt-in en todos lados y la gente se olvida.

Fitz hace de los secrets un tipo de primera clase:

let JWT_SECRET: Secret<Str> = secret("JWT_SECRET")
let DB_URL: Secret<Str> = secret("DATABASE_URL")
let LOG_LEVEL: Str = config("LOG_LEVEL", "info")

Tres cosas siguen del hecho de que Secret<T> sea un tipo:

print(JWT_SECRET) imprime `""`*. El trait Display redacta el valor.
La serialización JSON redacta. log.info("config", { jwt: JWT_SECRET }) envía "jwt": "***" a tu sistema de observability.
Hay exactamente una forma de exponer el valor: JWT_SECRET.expose(). Explícita, grepeable. El code review puede auditar cada call site en segundos.

config("LOG_LEVEL", "info") es el hermano no-secret. Mismo lookup de env var, mismo default, tipo Str plano — sin redacción porque no es sensible. El sistema de tipos hace la distinción obvia en lugar de depender de convenciones de nombres.

Combinado con el migrator (Parte 2), los secrets de Postgres viven en Secret<Str> desde el momento en que entran al binario hasta que se entregan al driver. No hay variable string con la password dando vueltas.

Observability con un solo env var

Tracing y métricas son las partes de observability de producción que todo el mundo quiere y nadie quiere configurar. El SDK Python de OpenTelemetry actualmente te pide que:

Instales opentelemetry-api, opentelemetry-sdk, el exporter para tu protocolo, y un paquete de instrumentation por cada librería que uses.
Configures el tracer provider, el meter provider, los resource attributes, el sampler.
Lo enganches en un hook de startup.
Esperes que ninguna de las versiones de esos paquetes se haya roto entre releases de Python.

En Fitz:

OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318 ./mybin

Esa es la integración. Cada request HTTP abre un span que exporta a OTLP. El span lleva http.method, http.target (template de la ruta, no path con params), http.status_code, duration_ms. El trace_id y span_id se propagan a cada log.info(...) adentro del handler — cuando grepeás Jaeger por trace_id, encontrás cada log line relacionado en todos los servicios al instante.

Cuando el env var no está seteado: cero overhead, cero llamadas de red, ninguna tarea de exporter corriendo.

Podés opt-out por ruta:

@server(observability=false)
fn main() => 0

Podés agregar spans explícitos adentro de la lógica de negocio:

@trace(name="process_order")
@metric(name="orders")
async fn process(order: Order) -> Result<Receipt> {
    let validated = validate(order)?
    let charged = charge(validated).await?
    return Ok(receipt_for(charged))
}

@trace abre un tracing::info_span!. @metric registra un histograma <name>_duration_seconds y un counter <name>_calls_total, populados al hacer drop del scope de la función — funciona con paths return explícitos, sin código muerto.

Las métricas también se exponen en /metrics (formato Prometheus) si lo activás:

@server(prometheus=true)
fn main() => 0

Para tiendas OpenTelemetry-native, el exporter OTLP envía también las métricas — ambos backends funcionan.

Logs estructurados con auto-correlación

log.info("user.signup", {
    user_id: user.id,
    email: user.email,
    plan: "free",
})

Eso emite una línea JSON a stderr con timestamp, level, msg, los fields explícitos, y automáticamente el trace_id/span_id del request HTTP actual. Sin llamada a tracer.get_current_span(). El wrapper HTTP setea el contexto; el logger lo lee. Correlacionás logs y traces por trace_id sin pensar en eso.

Si valores Secret<T> aparecen en los kwargs, se redactan antes de serializar. No hay forma de loguear accidentalmente un secret salvo escribir .expose() explícito.

Pretty-print en dev, JSON en producción:

$ ./mybin
2026-06-05 14:23:11 INFO http.access method=GET target=/users/{id} status=200 duration_ms=12 trace_id=ab12cd34...
2026-06-05 14:23:11 INFO user.lookup user_id=42 found=true

$ FITZ_LOG_FORMAT=json ./mybin
{"timestamp":"2026-06-05T14:23:11Z","level":"INFO","msg":"http.access","method":"GET","target":"/users/{id}","status":200,"duration_ms":12,"trace_id":"ab12cd34..."}

El happy path de Loki/Datadog/Splunk es el mismo JSON estés usando OpenTelemetry o no. Ningún agente re-parsea prefijos.

Feature flags como decorador

Los feature flags estilo unleash/launchdarkly son normalmente una llamada de servicio por evaluación. Para la mayoría de los proyectos, la respuesta correcta es mucho más simple: una flag en tu config, un override por env var, un 404 si la flag está off.

@flag("new-checkout")
@post("/v2/checkout")
fn v2_checkout(body: Cart) -> Receipt { ... }

Dos fuentes:

Sección [flags] en fitz.toml — defaults compile-time horneados al binario.
Env vars FITZ_FLAG_<NAME> — override runtime sin recompilar.

Default es false (fail-safe). Cuando la flag está off, el handler HTTP/WS retorna 404 — y la ruta está gateada antes de que corran los middlewares y la auth, así que no gastás ciclos en algo que el user no puede alcanzar de todas formas.

Adentro de la lógica de negocio:

if flag("show-experimental-banner") {
    show_banner()
}

flags.list() enumera flags conocidas (config + env). flags.is_enabled("name") es el alias.

El modelo no está tratando de reemplazar a LaunchDarkly. Está tratando de eliminar la excusa para commitear if user.id == 42 y gatear features para testing. Servicio de feature flags real cuando necesitás targeting, porcentajes, audit log. Flags built-in cuando solo querés un kill switch.

Dockerfile generado de tu AST

fitz docker init

Lee tu main.fitz y escribe tres archivos:

Dockerfile — multi-stage. El builder usa la imagen toolchain de Fitz. La stage de runtime es gcr.io/distroless/cc-debian12 (o python:3.12-slim-bookworm si hay un from python import ... en tu código — distroless no puede hostear CPython).
.dockerignore — defaults que matchean los smell tests (target/, .git/, .env*, __pycache__/).
docker-compose.yml — tu app más la infraestructura que necesita. db.connect(...) en tu código agrega postgres:16-alpine con healthcheck y volumen pgdata. @server(8080) setea EXPOSE 8080. @cron agrega restart: unless-stopped. Healthcheck contra /healthz porque hay un decorador @healthz.

La detección es AST-only (~50ms). No ejecuta tu programa, no toca el disco, no probe ports. Lee el árbol sintáctico, busca decoradores y calls landmarks, llena el template correcto.

Esta es la parte de deployment que tuve mal en cada proyecto: el Dockerfile que está casi bien pero no tiene libpq para Postgres, el compose que está casi bien pero montea el volumen equivocado. fitz docker init lo agarra bien la primera vez porque el AST le dice qué necesitás.

Los archivos se commitean. Editalos cuando los necesites:

$ fitz docker init        # generar
$ # editás Dockerfile, editás docker-compose.yml — son archivos normales
$ git add Dockerfile docker-compose.yml .dockerignore
$ git commit

fitz docker build es el wrapper fino que corre docker build -t <pkg-name>:latest . con el working directory correcto.

fitz deploy

# Build de imagen y push al registry (saltá el push con --no-push).
fitz deploy docker --tag mycorp/api:v1

# Levantá el stack compose local (con -d por default; --no-detach para foreground).
fitz deploy compose

Estos no son herramientas nuevas. Son wrappers finos sobre docker build/docker push y docker compose up. El punto no es inventar un sistema de deploy; el punto es que el comando de deploy existe en la misma toolchain que fitz build. No tenés que mantener un deploy.sh al lado de tu código.

Targets en el MVP: docker y compose. Targets explícitamente fuera del MVP: fly, railway, k8s. Para esos, corré flyctl deploy / railway up / kubectl apply directo — ya son buenas herramientas, Fitz no necesita re-envolverlas. Si aparece demanda por un target específico más adelante, se puede agregar — el helper crate son ~430 líneas.

Cómo se ve end-to-end

Un servicio real en Fitz hoy:

@server(8080, prometheus=true)
fn main() => 0

let DB_URL: Secret<Str> = secret("DATABASE_URL")
let JWT_SECRET: Secret<Str> = secret("JWT_SECRET")
let db = db.connect(DB_URL.expose())

@healthz
fn liveness() -> Bool => true

@readyz
async fn readiness() -> Bool {
    return match db.exec("SELECT 1").await { Ok(_) => true, Err(_) => false }
}

@table("users")
type User { @primary id: Int, email: Str, name: Str, role: Str }

@auth_provider
fn check_token(headers: Map<Str, Str>) -> Result<User> { /* verify JWT */ }

@authenticated
@get("/me")
fn me(user: User) -> User => user

@trace(name="charge")
@metric(name="charges")
@requires("billing")
@post("/charge")
async fn charge(body: ChargeRequest, user: User) -> Result<Receipt> {
    log.info("charge.attempt", { user_id: user.id, amount: body.amount })
    let receipt = stripe_charge(body).await?
    return Ok(receipt)
}

@cron("0 0 3 * * *", retry={max: 5, backoff: "exponential"}, store=db)
async fn cleanup_expired_tokens() {
    auth.cleanup_expired(db).await?
}

Lo deployás:

fitz docker init    # genera Dockerfile + compose con postgres + healthcheck
git add . && git commit -m "deploy setup"
fitz deploy docker --tag mycorp/api:v1

En producción:

docker run --rm \
  -e DATABASE_URL=postgres://... \
  -e JWT_SECRET=... \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 \
  -p 8080:8080 \
  mycorp/api:v1

Ese binario:

Auto-montea /healthz, /readyz, /openapi.json, /docs, /metrics, /asyncapi.json.
Exporta cada request HTTP como span OpenTelemetry con trace_id propagado a logs.
Valida JWTs con passwords hasheadas Argon2id.
Corre cleanup scheduled con retry persistente sobre las tablas fitz_cron_jobs/fitz_cron_runs.
Redacta cada Secret<T> de logs, JSON responses, y fields estructurados.
Maneja SIGTERM gracefully (drainando requests, después exit).
Compila a ~18 MB de binario nativo.

Escribiste ~50 líneas de código de negocio. El resto es el lenguaje haciendo lo que el lenguaje debería hacer.

Lo que todavía no está acá (honesto)

Te dije la verdad en la Parte 1: un solo dev. La historia de deployment tiene gaps conocidos:

fitz deploy fly / fitz deploy railway / fitz deploy k8s no están construidos. Usá flyctl deploy o railway up o kubectl apply directo. Los CLIs nativos son excelentes — Fitz no necesita re-envolverlos hoy.
Config de sidecar log shipping en el compose generado. Si querés Fluent Bit / Vector / Loki Promtail cableado, editá el compose a mano. El autogen cubre el shape del programa, no el backend de observability.
Limits de CPU/memoria en compose. El MVP no los setea — deploys de producción (compose stack a un server) deberían agregar deploy.resources.limits.
SBOM / firma de imagen. No se autogenera. La imagen es output de docker build. Firmá con cosign si lo necesitás.

Todo lo demás de arriba está en v0.15.0 hoy, con tests, con paridad bit-a-bit fitz run ↔ fitz build, con ejemplos en los docs.

Por qué importa

El split 80/20 que describí al principio — 80% código divertido, 20% pegoteo de producción — es un impuesto sobre cada lenguaje diseñado antes de 2015. Los lenguajes que diseñaron para producción desde el día uno (Go es el ejemplo obvio) cambiaron otras cosas para llegar ahí. Fitz está tratando de mantener el feel gradual-typed, expression-rich, async-first de Python — y aún así taxar producción con cero peso extra.

Si pasaste por una semana de deploy y sentiste "esto no debería requerir cinco pestañas de Stack Overflow", ese es el sentimiento al que estoy construyendo para eliminar.

Probalo:

# Linux / macOS / WSL
curl -sSf https://thegreekman76.github.io/fitz/install.sh | sh

# Windows (PowerShell)
irm https://thegreekman76.github.io/fitz/install.ps1 | iex

# Reabrí la terminal, después:
fitz new mi-api-prod --http
cd mi-api-prod
# Editá main.fitz para sumar @healthz, @table, una ruta HTTP
fitz docker init
fitz deploy compose

Para VSCode (recomendado — hover con tipos, autocomplete, signature help): bajá el fitz-lang-<plataforma>.vsix desde la página de releases y code --install-extension fitz-lang-<plataforma>.vsix --force. El Language Server viene incluido.

Vas a tener un servicio con healthchecks, observability, y Docker compose en tu proyecto en menos de cinco minutos. Avisame qué se rompió.

Repo: github.com/Thegreekman76/fitz
Docs y curso: thegreekman76.github.io/fitz
Capítulo de la guía sobre deployment: thegreekman76.github.io/fitz/guide/#35-deployment
Roadmap: docs/roadmap.md
CHANGELOG: CHANGELOG.md
Issues: github.com/Thegreekman76/fitz/issues

Hasta la próxima.

From repo to production in one command: how Fitz makes deployment a language feature

Martin Palopoli — Thu, 11 Jun 2026 13:56:33 +0000

A walk through the deployment story of Fitz — healthchecks, secrets as opaque types, OpenTelemetry observability, autogenerated Dockerfiles, and fitz deploy. Production-ready isn't a checklist, it's syntax.

The deployment story most languages don't tell

The first 80% of a service is fun: routes, types, business logic, tests. The last 20% is the part that ships the thing, and that's where everyone tapes together five different tools:

Some psutil-style healthcheck library because Kubernetes wants /healthz.
python-decouple or pydantic-settings for env vars, plus your own Secret class that hopefully doesn't end up in logs.
opentelemetry-instrumentation-fastapi plus opentelemetry-exporter-otlp-proto-http plus opentelemetry-instrumentation-sqlalchemy plus whatever the right combo of versions is this month.
A Dockerfile copy-pasted from a blog post, with three things wrong for your setup.
A docker-compose.yml that's right except for the env var that has to come from .env.production.
A Makefile or justfile with the actual commands, or a CI YAML that does the equivalent.

I've done this every project for ten years. It's the part where the language stops helping you. Fitz refuses to do that. Deployment is in the language.

Here's the full production stack in Fitz, and what each piece replaces.

Health checks as decorators

@server(43928)
fn main() => 0

@healthz
fn liveness() -> Bool => true

@readyz
async fn readiness(db: DbConn) -> Bool {
    return match db.exec("SELECT 1").await {
        Ok(_) => true,
        Err(_) => false,
    }
}

/healthz and /readyz auto-mount on the HTTP router. There's nothing to import, no library to configure. The return value of the function determines the HTTP status (200 if true, 503 if false). Kubernetes is happy.

The compiler also enforces shape: the function returns Bool or Result<Bool>, takes a DbConn if it needs one (the runtime injects it). If you forget @readyz entirely, the readiness endpoint just doesn't exist — there's no library to "almost configure" wrong.

In Python:

# requirements.txt: starlette-healthcheck, pyhealthcheck, ...
from healthcheck import HealthCheck
health = HealthCheck()
def db_check():
    try:
        db.execute("SELECT 1")
        return True, "ok"
    except Exception as e:
        return False, str(e)
health.add_check(db_check)
app.add_route("/healthz", health.run)  # remember to mount it

In Fitz:

@readyz
async fn readiness(db: DbConn) -> Bool {
    return match db.exec("SELECT 1").await { Ok(_) => true, Err(_) => false }
}

That's it. Same semantics, no library, no mount step, no docs you have to re-read.

Secrets as opaque types

The bug I've seen the most in production code: somebody logs the password, the API key, the JWT secret. The logger ships to Loki / Splunk / Sentry / whatever. The secret is now in production logs. Everyone agrees this is bad. Nobody has a good answer in stock libraries — os.environ["FOO"] is just a string. pydantic.SecretStr exists but you have to opt in everywhere and people forget.

Fitz makes secrets a first-class type:

let JWT_SECRET: Secret<Str> = secret("JWT_SECRET")
let DB_URL: Secret<Str> = secret("DATABASE_URL")
let LOG_LEVEL: Str = config("LOG_LEVEL", "info")

Three things follow from Secret<T> being a type:

print(JWT_SECRET) prints `""`*. The Display trait redacts the value.
JSON serialization redacts. log.info("config", { jwt: JWT_SECRET }) ships "jwt": "***" to your observability system.
There's exactly one way to expose the value: JWT_SECRET.expose(). Explicit, grep-able. Code review can audit every call site in seconds.

config("LOG_LEVEL", "info") is the non-secret sibling. Same env var lookup, same default, plain Str type — no redaction because it's not sensitive. The type system makes the distinction obvious instead of relying on naming conventions.

Combined with the migrator (Part 2), Postgres secrets live in Secret<Str> from the moment they enter the binary until they're handed to the driver. There's no string variable holding the password sitting around.

Observability with one env var

Tracing and metrics are the parts of production observability that everyone wants and nobody wants to set up. The Python OpenTelemetry SDK currently requires you to:

Install opentelemetry-api, opentelemetry-sdk, the exporter for your protocol, and one instrumentation package per library you use.
Configure the tracer provider, the meter provider, the resource attributes, the sampler.
Wire it up in a startup hook.
Hope none of the versions of those packages broke between Python releases.

In Fitz:

OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318 ./mybin

That's the integration. Every HTTP request opens a span that exports to OTLP. The span carries http.method, http.target (route template, not path with params), http.status_code, duration_ms. The trace_id and span_id are propagated to every log.info(...) inside the handler — when you grep Jaeger by trace_id, you instantly find every related log line across services.

When the env var is not set: zero overhead, zero network calls, no exporter task running.

You can opt out per route:

@server(observability=false)
fn main() => 0

You can add explicit spans inside business logic:

@trace(name="process_order")
@metric(name="orders")
async fn process(order: Order) -> Result<Receipt> {
    let validated = validate(order)?
    let charged = charge(validated).await?
    return Ok(receipt_for(charged))
}

@trace opens a tracing::info_span!. @metric registers a <name>_duration_seconds histogram and a <name>_calls_total counter, populated on drop of the function scope — works with explicit return paths, no dead code.

Metrics also expose at /metrics (Prometheus format) if you opt in:

@server(prometheus=true)
fn main() => 0

For OpenTelemetry-native shops, the OTLP exporter sends metrics too — both backends work.

Structured logs with auto-correlation

log.info("user.signup", {
    user_id: user.id,
    email: user.email,
    plan: "free",
})

That emits a JSON line to stderr with timestamp, level, msg, the explicit fields, and automatically the trace_id/span_id of the current HTTP request. No tracer.get_current_span() call. The HTTP wrapper sets the context; the logger reads it. You correlate logs and traces by trace_id without thinking about it.

If Secret<T> values appear in the kwargs, they're redacted before serialization. There is no way to accidentally log a secret short of writing .expose() explicitly.

Pretty-printed in dev, JSON in production:

$ ./mybin
2026-06-05 14:23:11 INFO http.access method=GET target=/users/{id} status=200 duration_ms=12 trace_id=ab12cd34...
2026-06-05 14:23:11 INFO user.lookup user_id=42 found=true

$ FITZ_LOG_FORMAT=json ./mybin
{"timestamp":"2026-06-05T14:23:11Z","level":"INFO","msg":"http.access","method":"GET","target":"/users/{id}","status":200,"duration_ms":12,"trace_id":"ab12cd34..."}

The Loki/Datadog/Splunk happy path is the same JSON whether you're using OpenTelemetry or not. No agent re-parses prefixes.

Feature flags as a decorator

Feature flags from unleash/launchdarkly are usually a service call per evaluation. For most projects, the right answer is much simpler: a flag in your config, an env var override, a 404 if the flag is off.

@flag("new-checkout")
@post("/v2/checkout")
fn v2_checkout(body: Cart) -> Receipt { ... }

Two sources:

[flags] section in fitz.toml — compile-time defaults baked into the binary.
FITZ_FLAG_<NAME> env vars — runtime override without recompiling.

Default is false (fail-safe). When the flag is off, the HTTP/WS handler returns 404 — and the route is gated before middleware and auth run, so you don't waste cycles on something the user can't reach anyway.

Inside business logic:

if flag("show-experimental-banner") {
    show_banner()
}

flags.list() enumerates known flags (config + env). flags.is_enabled("name") is the alias.

The model isn't trying to replace LaunchDarkly. It's trying to remove the excuse for committing if user.id == 42 to gate features for testing. Real feature flag service when you need targeting, percentages, audit log. Built-in flags when you just want a kill switch.

Dockerfile generated from your AST

fitz docker init

Reads your main.fitz and writes three files:

Dockerfile — multi-stage. The builder uses the Fitz toolchain image. The runtime stage is gcr.io/distroless/cc-debian12 (or python:3.12-slim-bookworm if there's a from python import ... in your code — distroless can't host CPython).
.dockerignore — defaults that match the smell tests (target/, .git/, .env*, __pycache__/).
docker-compose.yml — your app plus the infrastructure it needs. db.connect(...) in your code adds postgres:16-alpine with a healthcheck and a pgdata volume. @server(8080) sets EXPOSE 8080. @cron adds restart: unless-stopped. Healthcheck against /healthz because there's an @healthz decorator.

The detection is AST-only (~50ms). It doesn't run your program, doesn't poke at the disk, doesn't probe ports. It reads the syntax tree, looks for landmark decorators and calls, fills in the right template.

This is the part of deployment that I've gotten wrong every project: the Dockerfile that's almost right but doesn't have the libpq for Postgres, the compose that's almost right but mounts the wrong volume. fitz docker init gets it right the first time because the AST tells it what you need.

The files are committed. Edit them when you need to:

$ fitz docker init        # generate
$ # edit Dockerfile, edit docker-compose.yml — these are normal files
$ git add Dockerfile docker-compose.yml .dockerignore
$ git commit

fitz docker build is the thin wrapper that runs docker build -t <pkg-name>:latest . with the right working directory.

fitz deploy

# Build the image and push to a registry (skip the push with --no-push).
fitz deploy docker --tag mycorp/api:v1

# Bring up the compose stack locally (with -d by default; --no-detach for foreground).
fitz deploy compose

These are not new tools. They're thin wrappers over docker build/docker push and docker compose up. The point isn't to invent a deploy system; the point is that the deploy command exists in the same toolchain as fitz build. You don't have to maintain a deploy.sh next to your code.

Targets in the MVP: docker and compose. Targets explicitly not in the MVP: fly, railway, k8s. For those, run flyctl deploy / railway up / kubectl apply directly — they're already good tools, Fitz doesn't need to re-wrap them. If demand appears for a specific target later, it can be added — the helper crate is ~430 lines.

What it looks like end-to-end

A real service in Fitz today:

@server(8080, prometheus=true)
fn main() => 0

let DB_URL: Secret<Str> = secret("DATABASE_URL")
let JWT_SECRET: Secret<Str> = secret("JWT_SECRET")
let db = db.connect(DB_URL.expose())

@healthz
fn liveness() -> Bool => true

@readyz
async fn readiness() -> Bool {
    return match db.exec("SELECT 1").await { Ok(_) => true, Err(_) => false }
}

@table("users")
type User { @primary id: Int, email: Str, name: Str, role: Str }

@auth_provider
fn check_token(headers: Map<Str, Str>) -> Result<User> { /* JWT verify */ }

@authenticated
@get("/me")
fn me(user: User) -> User => user

@trace(name="charge")
@metric(name="charges")
@requires("billing")
@post("/charge")
async fn charge(body: ChargeRequest, user: User) -> Result<Receipt> {
    log.info("charge.attempt", { user_id: user.id, amount: body.amount })
    let receipt = stripe_charge(body).await?
    return Ok(receipt)
}

@cron("0 0 3 * * *", retry={max: 5, backoff: "exponential"}, store=db)
async fn cleanup_expired_tokens() {
    auth.cleanup_expired(db).await?
}

Deploy it:

fitz docker init    # generates Dockerfile + compose with postgres + healthcheck
git add . && git commit -m "deploy setup"
fitz deploy docker --tag mycorp/api:v1

In production:

docker run --rm \
  -e DATABASE_URL=postgres://... \
  -e JWT_SECRET=... \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 \
  -p 8080:8080 \
  mycorp/api:v1

That binary:

Auto-mounts /healthz, /readyz, /openapi.json, /docs, /metrics, /asyncapi.json.
Exports every HTTP request as an OpenTelemetry span with trace_id propagated to logs.
Validates JWTs with Argon2id-hashed passwords.
Runs scheduled cleanup with persistent retry over the fitz_cron_jobs/fitz_cron_runs tables.
Redacts every Secret<T> from logs, JSON responses, and structured fields.
Handles SIGTERM gracefully (draining requests, then exit).
Compiles to ~18 MB of native binary.

You wrote ~50 lines of business code. The rest is the language doing what the language should do.

What's not in here yet (honest)

I told you the truth in Part 1: one developer. The deployment story has known gaps:

fitz deploy fly / fitz deploy railway / fitz deploy k8s are not built. Use flyctl deploy or railway up or kubectl apply directly. The native CLIs are excellent — Fitz doesn't need to re-wrap them today.
Sidecar log shipping config in the generated compose. If you want Fluent Bit / Vector / Loki Promtail wired in, edit the compose by hand. The autogen covers the program shape, not the observability backend.
CPU/memory limits in compose. The MVP doesn't set them — production deploys (compose stack to a server) should add deploy.resources.limits.
SBOM / image signing. Not auto-generated. The image is just docker build output. Sign with cosign if you need it.

Everything else above is in v0.15.0 today, with tests, with bit-for-bit fitz run ↔ fitz build parity, with examples in the docs.

Why it matters

The 80/20 split I described at the top — 80% fun code, 20% production stapling — is a tax on every language designed before 2015. The languages that designed for production from day one (Go is the obvious example) traded other things to get there. Fitz is trying to keep the gradual-typed, expression-rich, async-first feel of Python — and still tax production with zero extra weight.

If you've gone through a deploy week and felt "this should not require five Stack Overflow tabs", that's the feeling I'm building toward removing.

Try it:

# Linux / macOS / WSL
curl -sSf https://thegreekman76.github.io/fitz/install.sh | sh

# Windows (PowerShell)
irm https://thegreekman76.github.io/fitz/install.ps1 | iex

# Reopen the terminal, then:
fitz new my-prod-api --http
cd my-prod-api
# Edit main.fitz to add @healthz, @table, an HTTP route
fitz docker init
fitz deploy compose

For VSCode (recommended — hover with types, autocomplete, signature help): grab the fitz-lang-<platform>.vsix from the releases page and code --install-extension fitz-lang-<platform>.vsix --force. The Language Server is bundled.

You'll have a service with healthchecks, observability, and Docker compose in your project in under five minutes. Let me know what broke.

Repo: github.com/Thegreekman76/fitz
Docs and course: thegreekman76.github.io/fitz
Guide chapter on deployment: thegreekman76.github.io/fitz/guide/#35-deployment
Roadmap: docs/roadmap.md
CHANGELOG: CHANGELOG.md
Issues: github.com/Thegreekman76/fitz/issues

Until the next one.

Construí tu primera API con Fitz: un acortador de URLs con Postgres y auth en 30 minutos

Martin Palopoli — Tue, 09 Jun 2026 10:12:08 +0000

Tutorial paso a paso por Fitz. Arrancamos desde fitz new, terminamos con un binario nativo corriendo en Docker. Sin dependencias externas. Sin pip install. Solo Postgres tipado, auth con JWT, y OpenAPI auto-generado.

Qué vamos a construir

Un acortador de URLs con las cuatro cosas que toda API real necesita:

Endpoints HTTP para crear, redirigir, y ver stats.
Persistencia en Postgres para los links y el contador de clicks.
Autenticación con JWT — solo los usuarios logueados pueden crear URLs cortas.
Un binario nativo con fitz build, listo para meter en un contenedor.

Tamaño final: ~120 líneas de Fitz. Sin requirements.txt. Sin package.json. Sin cargo add. Solo fitz y Postgres.

Vas a salir con:

POST /login → cambiá credenciales por un JWT.
POST /shorten (requiere auth) → devuelve el código corto.
GET /{code} → redirige a la URL original e incrementa el contador.
GET /stats/{code} (requiere auth) → muestra clicks y fecha de creación.
Un schema OpenAPI 3.1 auto-generado en /openapi.json.
La UI de Scalar en /docs para probar desde el browser.

Vamos.

Setup (2 minutos)

Instalá Fitz:

# Linux / macOS / WSL
curl -sSf https://thegreekman76.github.io/fitz/install.sh | sh

# Windows (PowerShell)
irm https://thegreekman76.github.io/fitz/install.ps1 | iex

O bajá un binario pre-compilado desde releases.

Extensión VSCode (fuertemente recomendada para este tutorial — te da hover con tipos, autocomplete, signature help, format on save): desde la misma página de releases bajá el fitz-lang-<plataforma>.vsix que matchee tu OS e instalalo:

code --install-extension fitz-lang-<plataforma>.vsix --force

El Language Server viene incluido adentro del .vsix — no hace falta instalarlo aparte. Recargá VSCode una vez después del install.

Reabrí la terminal para que el cambio de PATH aplique, después verificá:

fitz --version
# fitz 0.15.0

También vas a necesitar un Postgres corriendo. Lo más rápido es Docker:

docker run -d --name pg-shortener \
  -e POSTGRES_PASSWORD=demo \
  -e POSTGRES_DB=shortener \
  -p 5432:5432 \
  postgres:16

Ahora creá el proyecto:

fitz new url-shortener --http
cd url-shortener

El flag --http templatea un main.fitz con @get + @server ya cableados. Abrí main.fitz y arrancamos a editar.

Paso 1 — Hello world HTTP

Reemplazá main.fitz con este mínimo:

@server(8080)
fn main() => 0

@get("/health")
fn health() -> Str => "ok"

Corrélo:

fitz dev

fitz dev watchea el archivo y respawnea ante cada guardado — es el equivalente Fitz de uvicorn --reload. En otra terminal:

curl localhost:8080/health
# ok

Abrí http://localhost:8080/docs en el browser. Ya tenés una UI de Scalar con el GET /health documentado. Sin magia de decoradores-que-registran-rutas, sin app.include_router(...). El compilador lee el AST y genera el schema.

Paso 2 — Modelar el dominio

Un Link es el código corto, la URL original, el contador, y el dueño.

type Link {
    @primary id: Int,
    code: Str,
    target_url: Str,
    user_email: Str,
    clicks: Int,
    created_at: Str,
}

El decorador @primary lo marca como primary key. Int es i64 en el binario generado, bigint en Postgres. El ORM entiende esto porque el tipo se lee en el compilador — no en tiempo de ejecución.

Pero todavía no le dijimos a Fitz que este type es una tabla Postgres. Agregamos @table:

@table("links")
type Link {
    @primary id: Int,
    code: Str,
    target_url: Str,
    user_email: Str,
    clicks: Int,
    created_at: Str,
}

Ahora Link.all(db), Link.insert(db, l), Link.where(...), .preload(...) etc. existen sobre este tipo. El checker valida estáticamente que cualquier closure adentro de .where(...) solo referencie campos que existen. Los typos mueren en compile time, no en producción.

Paso 3 — Conectarse a Postgres

db.connect(url) abre un pool de conexiones. Lo hacemos una vez al boot:

let DB_URL = env_or("DATABASE_URL", "postgres://postgres:demo@localhost:5432/shortener")
let db = db.connect(DB_URL)

env_or es un built-in: lee la variable de entorno, fallback al default si no está. Útil para dev local + Docker sin condicionales.

También necesitamos que la tabla exista. La herramienta correcta acá son las migraciones de schema — Fitz trae fitz db diff y fitz db migrate built-in. Declarás la tabla como un type @table, y dejás que el migrator haga el SQL:

@table("links")
type Link {
    @primary id: Int,
    code: Str,
    target_url: Str,
    user_email: Str,
    clicks: Int = 0,
    created_at: Str = "",
}

La primera vez:

$ fitz db diff
+ CREATE TABLE links (
+     id BIGSERIAL PRIMARY KEY,
+     code TEXT NOT NULL,
+     target_url TEXT NOT NULL,
+     user_email TEXT NOT NULL,
+     clicks BIGINT NOT NULL DEFAULT 0,
+     created_at TEXT NOT NULL DEFAULT ''
+ );

$ fitz db migrate
✓ aplicada migration_20260530_links.sql

fitz db diff lee los types @table de tu código, introspecciona la DB viva, computa el SQL necesario para sincronizarlas, y emite un archivo de migración idempotente. fitz db migrate aplica las migraciones no aplicadas en orden. Mismo modelo que Alembic, pero con los types como fuente de verdad en lugar de archivos SQL separados que tenés que mantener alineados a mano.

Cuando después agregás name: Str al Link, fitz db diff emite ALTER TABLE links ADD COLUMN name TEXT NOT NULL. Re-ejecutás fitz db migrate. Sin DDL escrito a mano.

Para este tutorial, ejecutá fitz db diff + fitz db migrate una vez antes de levantar el server.

Paso 4 — Crear + redirigir

Dos endpoints. Lo interesante es cuán compactos son:

type ShortenRequest { target_url: Str }
type ShortenResponse { code: Str, short_url: Str }

@post("/shorten")
async fn shorten(db: DbConn, req: ShortenRequest, user: User) -> ShortenResponse {
    let code = generar_codigo()
    let link = Link {
        id: 0,
        code: code,
        target_url: req.target_url,
        user_email: user.email,
        clicks: 0,
        created_at: "",  // el default de la DB lo completa
    }
    Link.insert(db, link).await
    return ShortenResponse {
        code: code,
        short_url: "http://localhost:8080/{code}",
    }
}

Tres cosas para notar:

El parámetro db: DbConn — el runtime inyecta la conexión automáticamente. Fitz se da cuenta por el tipo que viene del pool global.
El parámetro user: User — viene de la auth, que cableamos en el próximo paso. El compilador valida estáticamente que el handler tenga @authenticated.
id: 0 — sentinel que le dice al ORM "es el primer insert, ignorá el campo, dejá que BIGSERIAL lo asigne". El ORM omite el campo del INSERT automáticamente.

La redirección:

@get("/{code}")
async fn redirect(db: DbConn, code: Str) -> Result<HttpResponse> {
    let link: Link = match Link.where(fn(l) => l.code == code).first(db).await {
        Ok(l) => l,
        Err(_) => return Err("no encontrado"),
    }
    // incrementar el contador sin bloquear la redirección
    spawn(incrementar_clicks(db, link.id))
    return Ok(redirect_to(link.target_url))
}

@background
async fn incrementar_clicks(db: DbConn, link_id: Int) {
    Link.where(fn(l) => l.id == link_id)
        .update(db, { "clicks": "clicks + 1" })
        .await
}

La closure fn(l) => l.code == code se traduce a SQL parametrizado en compile time: WHERE code = $1. No hay eval, ni string concat, ni riesgo de SQL injection. La variable code se convierte en un bind param.

spawn(incrementar_clicks(...)) es fire-and-forget — la respuesta sale sin esperar. El decorador @background autoriza a la función a ser invocada desde un spawn. Es un cerco-de-intención: nada se va a un scheduler en background por accidente.

Paso 5 — Auth con JWT

Tres piezas: el tipo User, el @auth_provider, y el endpoint de /login.

type User { email: Str, name: Str }
type LoginRequest { email: Str, password: Str }
type LoginResponse { token: Str }

let JWT_SECRET = env_or("JWT_SECRET", "demo-secret-cambiame")
let DEMO_HASH = hash.password("demo123")

@auth_provider
fn check_token(headers: Map<Str, Str>) -> Result<User> {
    let auth: Str = match headers.get("authorization") {
        Ok(v) => v,
        Err(_) => return Err("falta Authorization"),
    }
    let parts = auth.split(" ")
    if (parts.len() != 2 or parts[0] != "Bearer") {
        return Err("se esperaba 'Bearer <token>'")
    }
    let claims = jwt.decode(parts[1], JWT_SECRET)?
    return Ok(User { email: claims["email"], name: claims["name"] })
}

@post("/login")
fn login(creds: LoginRequest) -> LoginResponse {
    if (creds.email != "ada@example.com") {
        return 401 { "error": "credenciales inválidas" }
    }
    if (not hash.verify(creds.password, DEMO_HASH)) {
        return 401 { "error": "credenciales inválidas" }
    }
    let claims = { "email": creds.email, "name": "Ada" }
    return LoginResponse { token: jwt.encode(claims, JWT_SECRET) }
}

Qué está pasando:

hash.password(...) es Argon2id (la recomendación de OWASP para hashing de passwords en 2026). Al boot del programa hasheamos el password demo "demo123" — en producción esto sería una query SQL.
jwt.encode(...) firma con HS256 por default. Los claims son un Map<Str, Str>.
@auth_provider es el singleton global del programa. El checker exige un solo @auth_provider por programa y que los handlers @authenticated referencien un tipo User válido.
El operador ? sobre jwt.decode(...)? propaga el error hacia arriba — token inválido, expirado, firma incorrecta — todo termina como Err que el runtime de auth mapea a 401.

Ahora para que los handlers requieran auth, apilamos el decorador:

@authenticated
@post("/shorten")
async fn shorten(db: DbConn, req: ShortenRequest, user: User) -> ShortenResponse { ... }

@authenticated
@get("/stats/{code}")
async fn stats(db: DbConn, code: Str, user: User) -> Result<Link> {
    return Link.where(fn(l) => l.code == code and l.user_email == user.email)
               .first(db)
               .await
}

El parámetro user: User lo inyecta automáticamente el runtime después de que el provider valida el token. Si el token falta o es inválido → 401 sin que el handler corra siquiera. El schema OpenAPI refleja todo esto: aparece el securitySchemes.bearerAuth, los handlers protegidos llevan security: [{bearerAuth: []}], y el 401 queda documentado automático.

El decorador @admin (no lo usamos acá) va más allá: además del token exige user.role == "admin". El compilador valida estáticamente que User tenga un campo role: Str. Si no lo tiene, error en compile time.

Paso 6 — Probarlo

Con fitz dev corriendo en otra terminal:

# Login
curl -X POST localhost:8080/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"demo123"}'
# {"token":"eyJ0eXAiOiJKV1Qi..."}

TOKEN="eyJ0eXAi..."  # pegá el token del response

# Crear una URL corta
curl -X POST localhost:8080/shorten \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"target_url":"https://github.com/Thegreekman76/fitz"}'
# {"code":"abc123","short_url":"http://localhost:8080/abc123"}

# Redirección (el browser sigue; con curl usá -I)
curl -I localhost:8080/abc123
# HTTP/1.1 302 Found
# location: https://github.com/Thegreekman76/fitz

# Stats
curl localhost:8080/stats/abc123 -H "Authorization: Bearer $TOKEN"
# {"id":1,"code":"abc123","target_url":"...","clicks":1,"created_at":"..."}

Abrí http://localhost:8080/docs y vas a ver la UI completa de Scalar: los cuatro endpoints con el schema correcto, el botón Authorize para pegar el token que funciona, los endpoints protegidos con el iconito de candado. Nada de esto se configuró a mano — vino del compilador leyendo el AST.

Paso 7 — Compilar a binario nativo

Hasta ahora corrimos con fitz run (interpretado). Ahora envíamos:

fitz build

Eso produce url-shortener (o url-shortener.exe en Windows) — un binario nativo standalone. Todo lo demás está estáticamente linkeado excepto libc.

ls -lh url-shortener
# -rwxr-xr-x  1  user  user   18M  May 29 14:00 url-shortener

DATABASE_URL=postgres://postgres:demo@localhost:5432/shortener ./url-shortener
# server listening on 127.0.0.1:8080

El requisito duro de Fitz es que fitz run y fitz build produzcan comportamiento bit-a-bit idéntico. Mismo output JSON, mismos status codes, mismas queries SQL. Si divergen, es un bug.

Para Docker:

FROM gcr.io/distroless/cc-debian12
COPY url-shortener /url-shortener
ENV DATABASE_URL=postgres://...
ENV JWT_SECRET=...
EXPOSE 8080
CMD ["/url-shortener"]

Imagen distroless con el binario adentro. ~30 MB final. Sin python, sin node, sin cargo — solo tu binario compilado y un libc mínimo.

Paso 8 — Deploy con un solo comando

En realidad no tenés que escribir ese Dockerfile a mano. Fitz lee el shape de tu programa y lo genera por vos:

fitz docker init

Esto crea tres archivos en tu proyecto:

Dockerfile — multi-stage, imagen builder más una stage de runtime con gcr.io/distroless/cc-debian12. EXPOSE 8080 porque hay un @server(8080) en el código.
.dockerignore — defaults razonables (target/, .git/, .env*, __pycache__/).
docker-compose.yml — tu app más un service postgres:16-alpine con healthcheck y volumen pgdata, porque hay un db.connect(...) en el código. El env var DATABASE_URL se cablea automático.

La detección es AST-only (~50ms). No hace falta ejecutar el programa para saber qué infraestructura querés. Si hubieras tenido @cron, hubiera agregado restart: unless-stopped. Si hubieras tenido from python import ..., hubiera elegido python:3.12-slim-bookworm en lugar de distroless. Genera lo que vos escribirías a mano, lo commiteás, lo editás cuando lo necesites.

Ahora shippeás:

# Build de imagen, push al registry.
fitz deploy docker --tag mycorp/shortener:v1

# O levantá local con compose (útil para QA local).
fitz deploy compose

fitz deploy es un wrapper fino sobre los CLIs nativos docker/docker compose. No se trata de inventar herramientas nuevas — se trata de que dejes de perseguir errores de Dockerfile equivocados durante dos días cada vez que arrancás un proyecto. Los correctos ya están ahí.

Si querés deploy del binario sin Docker, podés seguir haciendo lo de paso 7 — scp del binario, correrlo. El output de fitz build es genuinamente standalone.

Detalles production: healthchecks, secrets, observability

Ya que estamos hablando de producción, Fitz ya tiene el resto del checklist como parte del lenguaje:

@healthz
fn liveness() -> Bool => true

@readyz
async fn readiness(db: DbConn) -> Bool {
    return match db.exec("SELECT 1").await {
        Ok(_) => true,
        Err(_) => false,
    }
}

/healthz y /readyz se auto-montan en el router HTTP. Kubernetes contento.

let JWT_SECRET: Secret<Str> = secret("JWT_SECRET")  // nunca printea, nunca loguea el valor
let LOG_LEVEL: Str = config("LOG_LEVEL", "info")    // env var tipada con default

Secret<T> es un type opaco — print(JWT_SECRET) imprime "***", la serialización JSON lo redacta, las llamadas a log.info(...) lo strippean de los fields estructurados. La única forma de exponer el valor es .expose() — explícito y greppable en code review.

# Observability con un env var, cero cambios de código.
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318 ./url-shortener

Cuando el env var está seteado, cada request HTTP abre un span que exporta a OpenTelemetry. trace_id/span_id se propagan a cada log.info(...) adentro del handler — grepeás Jaeger por trace_id y encontrás cada log line relacionado al instante. Cuando el env var no está seteado, hay cero overhead de red — el exporter es no-op.

No tenés que enchufar nada de esto. Ya está.

¿Cuán rápido es lo que acabás de construir?

Aprovechando que hablamos de producción: el boilerplate api-postgres-python del repo implementa el mismo CRUD con forma de shortener que vos escribiste en este tutorial, pero con FastAPI + SQLAlchemy + asyncpg. Mismo Postgres, mismo schema, mismos endpoints, mismo shape de JSON, mismo docker compose. Desde el bench reproducible en v0.10.13 (Intel Core Ultra 7 155H, Docker 29.2.1, 30s sostenidos, concurrencia 10):

Métrica	Fitz ORM	Python + SQLAlchemy	Speedup
Memory peak	9.2 MB	51 MB	5.5× más eficiente
`GET /users` p50	4.88 ms	37.85 ms	7.76×
`GET /users` RPS	1944	246	7.91×
`GET /users/{id}` p50	3.60 ms	31.87 ms	8.85×
`GET /users/{id}` RPS	2604	296	8.80×
Cold start	0.14 s	0.22 s	1.57×
Image size	131 MB	258 MB	2× más liviano

Misma máquina, misma red Docker, mismo Postgres. El binario que acabás de compilar en el paso 7 está en la columna de la izquierda. Corré bash benchmarks/orm-vs-sqlalchemy/run.sh desde el repo para reproducir en tu hardware (~5–8 min con cache Docker caliente; requiere oha + jq). Metodología completa y output crudo en benchmarks/orm-vs-sqlalchemy/README.md.

Lo que te queda

Un acortador de URLs funcionando en ~120 líneas de Fitz:

Server HTTP con OpenAPI 3.1 + UI Scalar.
ORM Postgres con closure-to-SQL tipado y fitz db diff/migrate para schema.
Auth con JWT + passwords Argon2id.
Jobs en background con spawn.
Binario nativo construido con fitz build.
Dockerfile + compose generados del AST con fitz docker init.
fitz deploy wrappeando docker build/push y docker compose up.
Health checks vía @healthz/@readyz, secrets vía Secret<T>, observability vía OpenTelemetry — todo built-in.

Lo que no instalaste:

FastAPI, Uvicorn, Pydantic.
SQLAlchemy, asyncpg, alembic.
python-jose, passlib, argon2-cffi.
Celery, Redis (para el spawn).
OpenTelemetry SDK + paquetes de auto-instrumentation.
Un linter de Dockerfile, un generador de compose, un script de deploy.

Dependencias externas totales de tu proyecto: 0. Solo Fitz y Postgres.

Qué falta (para contexto)

En un shortener real igualmente querrías:

Usuarios reales — hardcodeamos a Ada. Una tabla User real con @table son dos minutos más.
Rate limiting por usuario — middleware encima del @authenticated. Un @middleware(rate_limit) más un contador chico en Redis/Postgres.
Analytics custom — más allá del contador de clicks, querrías user agent, referer, etc. Se suma en 5 líneas más.
Tracking en background con retry — spawn es fire-and-forget. Para retries reales, los jobs @cron con persistencia + retry config (@cron("expr", retry={max: 5, backoff: "exponential"}, store=db)) ya están soportados — cableás una tabla clicks_queue y un @cron que la drene.

Todo realizable hoy con lo que está en la caja.

Qué viene en la serie

En el próximo post sumamos WebSockets al shortener: un dashboard en tiempo real que mira los clicks en vivo, con la misma auth, con AsyncAPI generado automático.

Si te trabaste en algún paso o construiste algo interesante, escribí en issues de GitHub — leo todos.

Repo final: el código completo de este tutorial está en github.com/Thegreekman76/fitz/tree/main/boilerplates/api-orm-full.

Docs y curso: thegreekman76.github.io/fitz
Guía (34 capítulos): thegreekman76.github.io/fitz/guide/
Roadmap: docs/roadmap.md
CHANGELOG: CHANGELOG.md

Nos vemos en el próximo.

Build a URL shortener with Fitz: HTTP + Postgres + auth in 30 minutes

Martin Palopoli — Tue, 09 Jun 2026 10:11:49 +0000

A step-by-step tutorial through Fitz. We start from fitz new, finish with a native binary running in Docker. No external dependencies. No pip install. Just typed Postgres, JWT auth, and OpenAPI auto-generated.

What we're building

A URL shortener with the four things every real API needs:

HTTP endpoints for create, redirect, and stats.
Postgres persistence for the links and the click counter.
JWT authentication — only logged-in users can create short URLs.
A native binary with fitz build, ready to drop into a container.

Final size: ~120 lines of Fitz. No requirements.txt. No package.json. No cargo add. Just fitz and Postgres.

You'll come out with:

POST /login → swap credentials for a JWT.
POST /shorten (auth required) → returns the short code.
GET /{code} → redirects to the original URL and increments the counter.
GET /stats/{code} (auth required) → shows clicks and creation date.
An auto-generated OpenAPI 3.1 schema at /openapi.json.
The Scalar UI at /docs to test from the browser.

Let's go.

Setup (2 minutes)

Install Fitz:

# Linux / macOS / WSL
curl -sSf https://thegreekman76.github.io/fitz/install.sh | sh

# Windows (PowerShell)
irm https://thegreekman76.github.io/fitz/install.ps1 | iex

Or grab a pre-compiled binary from the releases.

VSCode extension (strongly recommended for this tutorial — you get hover with types, autocomplete, signature help, format on save): from the same releases page grab the fitz-lang-<platform>.vsix matching your OS and install it:

code --install-extension fitz-lang-<platform>.vsix --force

The Language Server is bundled inside the .vsix — no separate install. Reload VSCode once after the install.

Reopen the terminal so the PATH change applies, then check:

fitz --version
# fitz 0.15.0

You'll also need a running Postgres. The fastest is Docker:

docker run -d --name pg-shortener \
  -e POSTGRES_PASSWORD=demo \
  -e POSTGRES_DB=shortener \
  -p 5432:5432 \
  postgres:16

Now create the project:

fitz new url-shortener --http
cd url-shortener

The --http flag templates a main.fitz with @get + @server already wired. Open main.fitz and let's start editing.

Step 1 — Hello world HTTP

Replace main.fitz with this minimum:

@server(8080)
fn main() => 0

@get("/health")
fn health() -> Str => "ok"

Run it:

fitz dev

fitz dev watches the file and respawns on every save — it's the Fitz equivalent of uvicorn --reload. In another terminal:

curl localhost:8080/health
# ok

Open http://localhost:8080/docs in your browser. You already have a Scalar UI with GET /health documented. No decorator-to-register-routes magic, no app.include_router(...). The compiler reads the AST and generates the schema.

Step 2 — Model the domain

A Link is the short code, the original URL, the counter, and the owner.

type Link {
    @primary id: Int,
    code: Str,
    target_url: Str,
    user_email: Str,
    clicks: Int,
    created_at: Str,
}

The @primary decorator marks it as primary key. Int is i64 in the generated binary, bigint in Postgres. The ORM understands this because the type is read in the compiler — not at runtime.

But we haven't told Fitz that this type is a Postgres table. Adding @table:

@table("links")
type Link {
    @primary id: Int,
    code: Str,
    target_url: Str,
    user_email: Str,
    clicks: Int,
    created_at: Str,
}

Now Link.all(db), Link.insert(db, l), Link.where(...), .preload(...) etc. exist on this type. The checker validates statically that any closure inside .where(...) only references existing fields. Typos die at compile time, not in production.

Step 3 — Connect to Postgres

db.connect(url) opens a connection pool. We do it once at boot:

let DB_URL = env_or("DATABASE_URL", "postgres://postgres:demo@localhost:5432/shortener")
let db = db.connect(DB_URL)

env_or is a built-in: reads the environment variable, falls back to the default if it's not set. Useful for local dev + Docker without conditionals.

We also need the table to exist. The right tool here is schema migrations — Fitz has fitz db diff and fitz db migrate built-in. Declare the table as a @table type, then let the migrator do the SQL:

@table("links")
type Link {
    @primary id: Int,
    code: Str,
    target_url: Str,
    user_email: Str,
    clicks: Int = 0,
    created_at: Str = "",
}

The first time:

$ fitz db diff
+ CREATE TABLE links (
+     id BIGSERIAL PRIMARY KEY,
+     code TEXT NOT NULL,
+     target_url TEXT NOT NULL,
+     user_email TEXT NOT NULL,
+     clicks BIGINT NOT NULL DEFAULT 0,
+     created_at TEXT NOT NULL DEFAULT ''
+ );

$ fitz db migrate
✓ applied migration_20260530_links.sql

fitz db diff reads the @table types in your code, introspects the live DB, computes the SQL needed to bring them in sync, and emits an idempotent migration file. fitz db migrate applies the unapplied migrations in order. Same model as Alembic, but with the types as source of truth instead of separate SQL files you have to keep aligned by hand.

When you add name: Str to Link later, fitz db diff emits ALTER TABLE links ADD COLUMN name TEXT NOT NULL. You re-run fitz db migrate. No hand-written DDL.

For this tutorial, run fitz db diff + fitz db migrate once before starting the server.

Step 4 — Create + redirect

Two endpoints. The interesting thing is how compact they are:

type ShortenRequest { target_url: Str }
type ShortenResponse { code: Str, short_url: Str }

@post("/shorten")
async fn shorten(db: DbConn, req: ShortenRequest, user: User) -> ShortenResponse {
    let code = generate_code()
    let link = Link {
        id: 0,
        code: code,
        target_url: req.target_url,
        user_email: user.email,
        clicks: 0,
        created_at: "",  // DB default fills it in
    }
    Link.insert(db, link).await
    return ShortenResponse {
        code: code,
        short_url: "http://localhost:8080/{code}",
    }
}

Three things to note:

The db: DbConn parameter — the runtime injects the connection automatically. Fitz figures out it's coming from the global pool by type.
The user: User parameter — this comes from auth, which we'll wire up in the next step. The compiler statically validates the handler is @authenticated.
id: 0 — sentinel that tells the ORM "this is the first insert, ignore the field, let BIGSERIAL assign it". The ORM omits the field from the INSERT automatically.

The redirect:

@get("/{code}")
async fn redirect(db: DbConn, code: Str) -> Result<HttpResponse> {
    let link: Link = match Link.where(fn(l) => l.code == code).first(db).await {
        Ok(l) => l,
        Err(_) => return Err("not found"),
    }
    // increment the counter without blocking the redirect
    spawn(increment_clicks(db, link.id))
    return Ok(redirect_to(link.target_url))
}

@background
async fn increment_clicks(db: DbConn, link_id: Int) {
    Link.where(fn(l) => l.id == link_id)
        .update(db, { "clicks": "clicks + 1" })
        .await
}

The closure fn(l) => l.code == code gets translated to parametrized SQL at compile time: WHERE code = $1. There's no eval, no string concat, no SQL injection risk. The code variable becomes a bind parameter.

spawn(increment_clicks(...)) is fire-and-forget — the response goes back without waiting. The @background decorator authorizes the function to be called from a spawn. It's a fence-of-intent: nothing accidentally goes to a background scheduler.

Step 5 — JWT auth

Three pieces: the User type, the @auth_provider, the /login endpoint.

type User { email: Str, name: Str }
type LoginRequest { email: Str, password: Str }
type LoginResponse { token: Str }

let JWT_SECRET = env_or("JWT_SECRET", "demo-secret-change-me")
let DEMO_HASH = hash.password("demo123")

@auth_provider
fn check_token(headers: Map<Str, Str>) -> Result<User> {
    let auth: Str = match headers.get("authorization") {
        Ok(v) => v,
        Err(_) => return Err("missing Authorization"),
    }
    let parts = auth.split(" ")
    if (parts.len() != 2 or parts[0] != "Bearer") {
        return Err("expected 'Bearer <token>'")
    }
    let claims = jwt.decode(parts[1], JWT_SECRET)?
    return Ok(User { email: claims["email"], name: claims["name"] })
}

@post("/login")
fn login(creds: LoginRequest) -> LoginResponse {
    if (creds.email != "ada@example.com") {
        return 401 { "error": "invalid credentials" }
    }
    if (not hash.verify(creds.password, DEMO_HASH)) {
        return 401 { "error": "invalid credentials" }
    }
    let claims = { "email": creds.email, "name": "Ada" }
    return LoginResponse { token: jwt.encode(claims, JWT_SECRET) }
}

What's happening:

hash.password(...) is Argon2id (the OWASP recommendation for password hashing in 2026). At program boot we hash the demo password "demo123" — in production this would be a SQL query.
jwt.encode(...) signs with HS256 by default. The claims are a Map<Str, Str>.
@auth_provider is the global singleton of the program. The checker enforces only one @auth_provider per program and that handlers @authenticated reference a valid User type.
The ? operator on jwt.decode(...)? propagates the error upward — invalid token, expired, wrong signature — everything ends up as Err that the auth runtime maps to a 401.

Now to require auth on the handlers, stack the decorator:

@authenticated
@post("/shorten")
async fn shorten(db: DbConn, req: ShortenRequest, user: User) -> ShortenResponse { ... }

@authenticated
@get("/stats/{code}")
async fn stats(db: DbConn, code: Str, user: User) -> Result<Link> {
    return Link.where(fn(l) => l.code == code and l.user_email == user.email)
               .first(db)
               .await
}

The user: User parameter is automatically injected by the runtime after the provider validates the token. If the token is missing/invalid → 401 without the handler ever running. The OpenAPI schema reflects all of this: securitySchemes.bearerAuth appears, the protected handlers carry security: [{bearerAuth: []}], and 401 is documented automatically.

The @admin decorator (not used here) takes it further: it requires user.role == "admin" in addition to the token. The compiler enforces statically that User has a role: Str field. If it doesn't, error at compile time.

Step 6 — Test it

With fitz dev running on another terminal:

# Login
curl -X POST localhost:8080/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"demo123"}'
# {"token":"eyJ0eXAiOiJKV1Qi..."}

TOKEN="eyJ0eXAi..."  # paste the token from the response

# Create a short URL
curl -X POST localhost:8080/shorten \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"target_url":"https://github.com/Thegreekman76/fitz"}'
# {"code":"abc123","short_url":"http://localhost:8080/abc123"}

# Redirect (browser follows; with curl use -I)
curl -I localhost:8080/abc123
# HTTP/1.1 302 Found
# location: https://github.com/Thegreekman76/fitz

# Stats
curl localhost:8080/stats/abc123 -H "Authorization: Bearer $TOKEN"
# {"id":1,"code":"abc123","target_url":"...","clicks":1,"created_at":"..."}

Open http://localhost:8080/docs and you'll see the full Scalar UI: all four endpoints with the right schema, the Authorize button that paste the token works, the protected endpoints with the lock icon. None of this was set up by hand — it came from the compiler reading the AST.

Step 7 — Compile to a native binary

So far we ran with fitz run (interpreted). Now we ship:

fitz build

That produces url-shortener (or url-shortener.exe on Windows) — a single self-contained native binary. Everything is statically linked except libc.

ls -lh url-shortener
# -rwxr-xr-x  1  user  user   18M  May 29 14:00 url-shortener

DATABASE_URL=postgres://postgres:demo@localhost:5432/shortener ./url-shortener
# server listening on 127.0.0.1:8080

The hard requirement of Fitz is that fitz run and fitz build produce bit-for-bit identical behavior. Same JSON output, same status codes, same SQL queries. If they diverge, it's a bug.

For Docker:

FROM gcr.io/distroless/cc-debian12
COPY url-shortener /url-shortener
ENV DATABASE_URL=postgres://...
ENV JWT_SECRET=...
EXPOSE 8080
CMD ["/url-shortener"]

Distroless image with the binary inside. ~30 MB final. No python, no node, no cargo — just your compiled binary and a minimal libc.

Step 8 — Deploy with one command

You don't actually have to write that Dockerfile by hand. Fitz reads the shape of your program and generates it for you:

fitz docker init

This creates three files in your project:

Dockerfile — multi-stage, builder image plus a gcr.io/distroless/cc-debian12 runtime stage. EXPOSE 8080 because there's an @server(8080) in the code.
.dockerignore — sane defaults (target/, .git/, .env*, __pycache__/).
docker-compose.yml — your app plus a postgres:16-alpine service with a healthcheck and pgdata volume, because there's a db.connect(...) in the code. The DATABASE_URL env var is wired automatically.

The detection is AST-only (~50ms). No need to run the program to figure out what infrastructure it wants. If you had @cron, it would add restart: unless-stopped. If you had from python import ..., it would pick python:3.12-slim-bookworm over distroless. It generates what you'd write by hand, you commit it, you edit it when you need to.

Now you ship:

# Build the image, push to a registry.
fitz deploy docker --tag mycorp/shortener:v1

# Or bring up locally with compose (handy for local QA).
fitz deploy compose

fitz deploy is a thin wrapper over the native docker/docker compose CLIs. The point isn't to invent new tools — it's that you stop chasing wrong Dockerfile mistakes for two days every time you start a project. The right ones are already there.

If you want the binary deployment without Docker, you can keep doing what we did in step 7 — scp the binary, run it. The fitz build output is genuinely standalone.

Production niceties: healthchecks, secrets, observability

While we're talking about production, Fitz already has the rest of the production checklist as part of the language:

@healthz
fn liveness() -> Bool => true

@readyz
async fn readiness(db: DbConn) -> Bool {
    return match db.exec("SELECT 1").await {
        Ok(_) => true,
        Err(_) => false,
    }
}

/healthz and /readyz auto-mount on the HTTP router. Kubernetes is happy.

let JWT_SECRET: Secret<Str> = secret("JWT_SECRET")  // never prints, never logs the value
let LOG_LEVEL: Str = config("LOG_LEVEL", "info")    // typed env var with default

Secret<T> is an opaque type — print(JWT_SECRET) prints "***", JSON serialization redacts it, the log.info(...) calls strip it from structured fields. The only way to expose the value is .expose() — explicit and grep-able for code review.

# Observability with one env var, zero code changes.
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318 ./url-shortener

When the env var is set, every HTTP request opens a span that exports to OpenTelemetry. trace_id/span_id are propagated to every log.info(...) inside the handler — you grep Jaeger by trace_id and instantly find every related log line. When the env var is not set, there is zero network overhead — the exporter is a no-op.

You don't have to bolt any of this on. It's already there.

How fast is the thing you just built?

While we're talking production: the api-postgres-python boilerplate in the repo implements the same shortener-shaped CRUD that you wrote in this tutorial, but with FastAPI + SQLAlchemy + asyncpg. Same Postgres, same schema, same endpoints, same JSON shape, same docker compose. From the reproducible bench on v0.10.13 (Intel Core Ultra 7 155H, Docker 29.2.1, 30s sustained, concurrency 10):

Metric	Fitz ORM	Python + SQLAlchemy	Speedup
Memory peak	9.2 MB	51 MB	5.5× leaner
`GET /users` p50	4.88 ms	37.85 ms	7.76×
`GET /users` RPS	1944	246	7.91×
`GET /users/{id}` p50	3.60 ms	31.87 ms	8.85×
`GET /users/{id}` RPS	2604	296	8.80×
Cold start	0.14 s	0.22 s	1.57×
Image size	131 MB	258 MB	2× lighter

Same machine, same Docker network, same Postgres. The binary you just compiled in step 7 is in that left column. Run bash benchmarks/orm-vs-sqlalchemy/run.sh from the repo to reproduce on your hardware (~5–8 min with hot Docker cache; needs oha + jq). Full methodology and raw output in benchmarks/orm-vs-sqlalchemy/README.md.

What you got

A working URL shortener in ~120 lines of Fitz:

HTTP server with OpenAPI 3.1 + Scalar UI.
Postgres ORM with typed closure-to-SQL and fitz db diff/migrate for schema.
JWT auth + Argon2id passwords.
Background jobs with spawn.
Native binary built with fitz build.
Dockerfile + compose generated from the AST with fitz docker init.
fitz deploy wrapping docker build/push and docker compose up.
Health checks via @healthz/@readyz, secrets via Secret<T>, observability via OpenTelemetry — all built in.

What you didn't install:

FastAPI, Uvicorn, Pydantic.
SQLAlchemy, asyncpg, alembic.
python-jose, passlib, argon2-cffi.
Celery, Redis (for the spawn).
OpenTelemetry SDK + auto-instrumentation packages.
A Dockerfile linter, a compose generator, a deploy script.

Total external dependencies of your project: 0. Just Fitz and Postgres.

What's missing (for context)

In a real shortener you'd still want:

Real users — we hardcoded Ada. A real User table with @table is two minutes more.
Rate limiting per user — middleware on top of @authenticated. A @middleware(rate_limit) plus a small Redis/Postgres counter.
Custom analytics — beyond click counter, you'd want user agent, referer, etc. Adds in 5 more lines.
Background tracking with retry — spawn is fire-and-forget. For real retries, the @cron jobs with persistence + retry config (@cron("expr", retry={max: 5, backoff: "exponential"}, store=db)) are already supported — wire a clicks_queue table and a @cron that drains it.

All achievable today with what's in the box.

What comes next in the series

In the next post we add WebSockets to the shortener: a real-time dashboard that watches clicks live, with the same auth, with AsyncAPI generated automatically.

If you got stuck somewhere or built something interesting, drop a note in issues on GitHub — I read every one.

Final repo: the full code of this tutorial is at github.com/Thegreekman76/fitz/tree/main/boilerplates/api-orm-full.

Docs and course: thegreekman76.github.io/fitz
Guide (34 chapters): thegreekman76.github.io/fitz/guide/
Roadmap: docs/roadmap.md
CHANGELOG: CHANGELOG.md

Until the next one.

Presentando Fitz: un lenguaje donde HTTP, Postgres, JWT y WebSockets son parte de la sintaxis

Martin Palopoli — Sat, 06 Jun 2026 11:09:56 +0000

Fitz es un lenguaje de programación nuevo, escrito en Rust, con compilador de tipado gradual. La premisa: en lugar de apilar FastAPI + SQLAlchemy + python-jose + Celery + Pydantic + uvicorn + Alembic + typer sobre Python, lo que cada una resuelve vive adentro del lenguaje: ruteo HTTP, generación de OpenAPI/AsyncAPI, async/await, autenticación con JWT, hashing de passwords, un ORM con driver Postgres escrito en Rust puro, migraciones de schema, WebSockets, cron, jobs en background, un CLI builder, healthchecks, observability con OpenTelemetry, secrets como tipos opacos, y un orquestador fitz deploy. Un solo binario. Cero deps externas para el stack core. Repo: github.com/Thegreekman76/fitz · Docs: thegreekman76.github.io/fitz

Hace años que vengo escribiendo APIs en Python — FastAPI más el elenco habitual: SQLAlchemy, python-jose para JWT, passlib para Argon2, Celery + Redis para jobs, Pydantic para validación, uvicorn para servir, alembic para migraciones. Cada API que entrego necesita más o menos las mismas nueve librerías, cada una con sus convenciones, sus breaking changes, su forma de integrarse con el resto.

En algún momento me hice la pregunta obvia: ¿por qué no es esto el lenguaje y listo?

Esa pregunta es Fitz.

Cómo se ve Fitz

Empecemos por la foto, después caminamos las piezas.

@server(43928)
fn main() => 0

type User { id: Int, email: Str, name: Str, role: Str }
type Credentials { email: Str, password: Str }
type LoginResponse { token: Str }

let SECRET = "demo-secret-cambiame-en-prod"
let ADA_HASH = hash.password("secret-ada-123")

@auth_provider
fn check_token(headers: Map<Str, Str>) -> Result<User> {
    let auth: Str = match headers.get("authorization") {
        Ok(v) => v,
        Err(_) => return Err("falta header Authorization"),
    }
    let parts = auth.split(" ")
    if (parts.len() != 2 or parts[0] != "Bearer") {
        return Err("se esperaba 'Bearer <token>'")
    }
    let claims = jwt.decode(parts[1], SECRET)?
    return find_user(claims["email"])
}

@post("/login")
fn login(creds: Credentials) -> LoginResponse {
    let user: User = match find_user(creds.email) {
        Ok(u) => u,
        Err(_) => return 401 { "error": "credenciales inválidas" },
    }
    if (not hash.verify(creds.password, ADA_HASH)) {
        return 401 { "error": "credenciales inválidas" }
    }
    let claims = { "email": user.email, "role": user.role }
    return LoginResponse { token: jwt.encode(claims, SECRET) }
}

@authenticated
@get("/me")
fn me(user: User) -> User => user

@admin
@get("/admin/users")
fn admin_list(user: User) -> List<User> { ... }

Lo que hace este código, sin un solo import ni una dependencia externa:

Levanta un servidor HTTP en el puerto 43928.
Genera OpenAPI 3.1 automático en /openapi.json.
Sirve la UI de Scalar en /docs con botón "Authorize" funcional.
Firma y verifica JWT (HS256/384/512).
Hashea passwords con Argon2id (recomendación de OWASP, no bcrypt).
Valida estáticamente que cada @authenticated/@admin tenga un @auth_provider declarado, que el provider devuelva el tipo User correcto, y que los handlers @admin tengan un campo role: Str en el User.
Compila a un binario nativo con fitz build, con paridad bit-a-bit contra fitz run.

La auth, el hashing, el JWT, el OpenAPI con el security scheme bearerAuth, las respuestas 401/403 — todo eso vive adentro del binario fitz. No hay requirements.txt, no hay package.json, no hay Cargo.toml del lado del usuario.

Por qué "ciudadano de primera" importa

"Ciudadano de primera clase" es una de esas frases que se gastan rápido. Lo digo concreto.

En FastAPI, @app.get("/users") es un método sobre una instancia. El framework es una librería de la cual hacés opt-in. El router es una estructura de datos Python. La autenticación es un Depends(...). Nada de eso es visible para el type checker como algo especial — son simplemente llamadas a funciones y decoradores que producen metadata.

En Fitz, @get("/users") es un decorador que el compilador entiende. El checker valida el template del path, los tipos de los parámetros contra los path params, el tipo del body, el tipo de retorno. El generador de OpenAPI inspecciona el AST directamente — no introspeciona objetos de runtime, no necesita decoradores que se "registren" a sí mismos. El User que devolvés en tu handler es el mismo User que aparece en el schema generado y en la UI de Scalar.

Suena chico hasta que lo vivís una semana. Después dejás de pelear con "por qué Pydantic discrepa con SQLAlchemy sobre si este campo es opcional" y empezás a escribir endpoints.

Las piezas

HTTP + OpenAPI + UI Scalar, todo automático

type Post { id: Int, title: Str, body: Str, tags: List<Str> }

@get("/posts")
fn list_posts() -> List<Post> { ... }

@post("/posts")
fn create_post(post: Post) -> Post { ... }

Eso es todo lo que necesitás. /openapi.json y /docs (Scalar) aparecen solos. Path params (/posts/{id}) son tipados y coercionados. La deserialización del JSON del body chequea required, aplica defaults, valida nullables, rechaza campos extra. Podés desactivar con @server(docs=false).

WebSockets tipados, con AsyncAPI auto-generado

type ChatMessage { from: Str, text: Str }

@server(43929, ws_heartbeat_secs=30)
fn main() => 0

@authenticated
@ws("/chat")
async fn chat(conn: WsConn<ChatMessage>, user: User) {
    loop {
        let msg = match conn.recv() {
            Ok(m) => m,
            Err(_) => break,
        }
        conn.broadcast(ChatMessage { from: user.name, text: msg.text })
    }
}

Cada frame se marshallea automáticamente desde y hacia el tipo declarado. La auth corre antes del upgrade WebSocket — token inválido devuelve 401 sin abrir el socket. El heartbeat con ping/pong mantiene la conexión viva más allá de los 60s default de Nginx. /asyncapi.json se genera solo (la spec hermana de OpenAPI para APIs event-driven). No conozco otro lenguaje que auto-genere AsyncAPI desde el código fuente tipado.

Jobs en background y cron, sin Redis

@cron("*/5 * * * *")
async fn cleanup_old_sessions() {
    db.exec("DELETE FROM sessions WHERE expires_at < now()")
}

@background
async fn send_welcome_email(email: Str) {
    // cosa cara
}

@post("/signup")
fn signup(creds: Credentials) -> User {
    let user = create_user(creds)
    spawn(send_welcome_email(user.email))  // fire-and-forget, Future<Null> tipado
    return user
}

Sin Celery. Sin Redis. Sin celery worker -A app corriendo al lado del uvicorn. El scheduler está en tu binario. Suficiente para el 90% de servicios — cuando lo superás, lo superás por una razón concreta, y eso es problema de Fase 11+.

Un ORM nativo con driver Postgres en Rust puro

Esta es la pieza de la que más orgulloso estoy, y la que más tiempo me llevó. Fitz tiene su propio driver de Postgres escrito en Rust — sin libpq, sin tokio-postgres, sin sqlx. El protocolo wire (v3.0), auth SCRAM-SHA-256, prepared statements, formato binario para 11 tipos OID — todo implementado desde el RFC.

@table("users")
type User {
    @primary id: Int,
    email: Str,
    name: Str,
    @has_many("Post", "user_id") posts: List<Post>,
}

@table("posts")
type Post {
    @primary id: Int,
    user_id: Int,
    title: Str,
    body: Str,
    @belongs_to user: User?,
}

@get("/users")
async fn list_users(db: DbConn) -> List<User> {
    return User.all(db).preload("posts").await
}

@get("/users/{id}")
async fn get_user(db: DbConn, id: Int) -> Result<User> {
    return User.where(fn(u) => u.id == id).first(db).await
}

@post("/users")
async fn create_user(db: DbConn, user: User) -> User {
    return User.insert(db, user).await
}

La closure adentro de .where(...) se traduce a SQL parametrizado en tiempo de compilación — fn(u) => u.id == id se convierte en WHERE id = $1. Operadores como .is_in([...]), .like(...), .ilike(...), .contains(...), más operadores JSONB como .has_key(...), .contains_json(...) mapean a operadores nativos de Postgres. El eager loading con .preload("posts") dispara una sola query batched. Agregados (.sum/.avg/.min/.max/.count) y GROUP BY están soportados a través de un tipo separado Aggregated<Row>.

Esto compila a código nativo vía fitz build. El binario generado hace exactamente las mismas calls a Postgres. Cero overhead de runtime para el SQL — ya es constante en build-time, comparable en performance con Diesel o sqlx.

¿Cuán rápido es de verdad? — cabeza-a-cabeza contra SQLAlchemy

La promesa "cero overhead" es fácil de decir y fácil de inflar, así que el repo trae un bench reproducible entre dos boilerplates equivalentes (api-postgres-fitz vs api-postgres-python) — mismo Postgres, mismos endpoints, mismo shape de respuesta, mismo docker compose. Números headline en v0.10.13 (Intel Core Ultra 7 155H, Docker 29.2.1, 30s sostenidos, concurrencia 10):

Métrica	Fitz ORM	Python + SQLAlchemy	Speedup
Memory peak	9.2 MB	51 MB	5.5× más eficiente
`GET /users` p50	4.88 ms	37.85 ms	7.76×
`GET /users` RPS	1944	246	7.91×
`GET /users/{id}` p50	3.60 ms	31.87 ms	8.85×
`GET /users/{id}` RPS	2604	296	8.80×
Cold start	0.14 s	0.22 s	1.57×
Image size	131 MB	258 MB	2× más liviano

Eso es ~8× el throughput con ~5× menos memoria, en la misma máquina, sobre la misma red Docker, contra el mismo Postgres. Reproducí los números con bash benchmarks/orm-vs-sqlalchemy/run.sh (~5–8 min con cache Docker caliente; requiere oha + jq). Metodología completa, output crudo y las partes donde la comparación es injusta para Fitz están en el README del bench.

from python import math, json

let radius = 5.0
let area: Float = math.pi * radius * radius

let parsed: Result<Map<Str, Any>> = match json.loads("{\"name\": \"ada\"}") {
    Ok(d) => Ok(d),
    Err(e) => Err("JSON malformado: {e}"),
}

SQLAlchemy, NumPy, pandas, lo que esté en PyPI — accesible desde Fitz con from python import .... El runtime embebe CPython vía PyO3. Las excepciones Python se vuelven Result::Err automáticamente. Async Python (asyncpg, SQLAlchemy 2.x async) se bridgea al .await de Fitz transparente. Incluso podés hacer fitz build --bundle-python para entregar un binario con CPython embebido — no se necesita Python en la máquina destino.

Esto es intencional. Fitz no quiere reemplazar el ecosistema de Python — quiere darte un lenguaje mejor para la capa web mientras dejás abierta la puerta a todo lo que Python ya construyó.

Async, finalmente sin color

async fn fetch_user(id: Int) -> Result<User> { ... }

async fn main() {
    let user = fetch_user(42).await?
    print("llegó {user.name}")
}

async/await en el core, sobre runtime tokio. El operador ? funciona a través de Result<T>. El type checker exige que ? solo aparezca adentro de funciones que retornan Result<...>. Compila a async fn + .await en Rust — mismo modelo de ejecución, mismo executor multi-thread.

CLI builder — el mismo lenguaje, herramientas de línea de comandos

Fitz no es solo para servicios HTTP. El mismo compilador trae un CLI builder built-in, sin librerías:

@command("greet", desc="Saludar a una persona")
fn greet(name: Str, loud: Bool = false, count: Int = 1) -> Int {
    let n = count
    while n > 0 {
        if loud { print("HOLA, {name}!") } else { print("hola, {name}") }
        n = n - 1
    }
    return 0
}

@command("add", desc="Sumar dos números")
fn add(a: Int, b: Int) -> Int {
    print("{a + b}")
    return 0
}

$ ./mybin greet Ada --loud --count 3
HOLA, Ada!
HOLA, Ada!
HOLA, Ada!

$ ./mybin --help
USAGE: mybin <command> [ARGS] [OPTIONS]
COMMANDS:
    greet    Saludar a una persona
    add      Sumar dos números

Convención sobre decoración: params sin default son positional args, params con default son flags. Bool con default = false se vuelve --flag, otros tipos --flag <value>. Short flags auto-derivados (--loud → -l) con detección de conflictos. Help auto-generado, exit codes POSIX estándar. Paridad bit-a-bit entre fitz run (desarrollo) y fitz build (binario self-contained que dropeás en /usr/local/bin).

Es el mismo lenguaje. Mismo type checker. Mismo async/await. Mismo Result<T> para errores. Si tu herramienta necesita pegar a la DB, el ORM está ahí. Si necesita HTTP, @get/@post están ahí. La línea entre "servicio web" y "CLI tool" deja de ser una decisión de stack.

Stack production-ready — del repo a producción

Esto es lo que separa a Fitz de los lenguajes "prototipo interesante". Los servicios reales necesitan health checks, secrets, observability, y una forma de shippear. Todo eso es parte del lenguaje:

@server(43928)
fn main() => 0

// Auto-montados en GET /healthz y /readyz — Kubernetes-friendly.
@healthz
fn liveness() -> Bool => true

@readyz
async fn readiness(db: DbConn) -> Bool {
    return match db.exec("SELECT 1").await {
        Ok(_) => true,
        Err(_) => false,
    }
}

// Secret<T> nunca leakea a logs, imprime "***" en Display.
let db_url: Secret<Str> = secret("DATABASE_URL")
let log_level: Str = config("LOG_LEVEL", "info")

// Tracing + métricas con un decorador cada uno.
@trace(name="process_order")
@metric(name="orders")
async fn process(order: Order) -> Result<Receipt> {
    // process_order_duration_seconds (histogram) y orders_calls_total
    // (counter) se populan automático al hacer drop del scope.
}

// Feature flags con dos fuentes: fitz.toml [flags] + env vars FITZ_FLAG_<NAME>.
@flag("new-checkout")
@post("/v2/checkout")
fn v2_checkout(body: Cart) -> Receipt { ... }

Atrás de bambalinas:

HTTP access logs auto-emitidos con trace_id/span_id propagado a cada log.info(...) adentro del handler.
Export OpenTelemetry OTLP con un solo env var: OTEL_EXPORTER_OTLP_ENDPOINT. Los spans fluyen a Jaeger/Tempo/Honeycomb. Sin el env var, cero overhead, cero llamadas de red.
Endpoint /metrics Prometheus expone counters y histogramas — @server(prometheus=true) lo activa.
@flag sobre handlers HTTP/WS retorna 404 cuando la flag está off — gate del hot path ANTES de middleware/auth.

Deployando:

# Genera Dockerfile + docker-compose.yml a partir del shape del programa.
fitz docker init

# Build del binario, build de imagen Docker, push al registry.
fitz deploy docker --tag mycorp/api:v1

# O levantá local con compose.
fitz deploy compose

fitz docker init lee tu AST. Si hay db.connect(...), agrega Postgres al compose. Si hay @server(N), setea EXPOSE N. Si hay @cron, agrega restart: unless-stopped. Si hay from python import ..., elige python:3.12-slim-bookworm en lugar de distroless. Genera lo que vos escribirías a mano, lo commiteás, lo editás cuando lo necesites.

No conozco otro lenguaje donde deployment sea una feature del lenguaje. Acá lo es porque cada proyecto que entregué en Python terminaba con dos días debuggeando gotchas del Dockerfile.

Las herramientas

Esta es la parte que subestimé cuando arranqué. Un lenguaje sin buenas herramientas nace muerto. Acá lo que hay hoy:

fitz run — interpreta el archivo directo. El ciclo de feedback más rápido.
fitz build — compila a binario nativo vía un proyecto Rust generado. La paridad bit-a-bit con fitz run es un requisito duro.
fitz check — solo type checker, sin ejecución.
fitz test — test runner built-in con decorador @test y assert, assert_eq, assert_throws. Output estilo cargo.
fitz dev — hot reload. Watchea *.fitz y fitz.toml, mata y respawnea el child al cambio.
fitz fmt — formatter opinionado, cero config. Preserva tus comentarios y líneas en blanco.
fitz lint — 4 lints built-in con supresión // @allow(<nombre>). Output estilo cargo-clippy.
fitz repl — REPL interactivo con soporte multi-línea, :type, :load, historial persistente.
fitz openapi — emite el schema OpenAPI sin levantar el server.
fitz db diff/migrate — tooling de migraciones de schema. Diff entre la DB viva y los types @table en tu código, genera migraciones idempotentes, las aplicás con fitz db migrate. Mismo modelo que Alembic pero con los types como fuente de verdad.
fitz docker init/build — genera el Dockerfile + .dockerignore + docker-compose.yml a partir del shape del programa, después docker build wrappeado.
fitz deploy docker/compose — wrapper fino para shippear la imagen o levantar local con un solo comando.
Extensión VSCode — diagnostics + hover + go-to-definition + autocomplete + signature help + format on save + inferencia bidireccional para callbacks, distribución multi-platform.
fitz new + fitz add + fitz remove + fitz update — package manager con fitz.toml, lockfile, path deps, git deps.

El LSP es real (tower-lsp adentro). El formatter es real (tu código hace round-trip por él). El test runner es real. Todo está dogfooded — escribo código Fitz con la misma extensión VSCode que entrego.

Siendo honesto sobre el estado

Esto es un proyecto de un solo desarrollador. Empecé aprendiendo Rust para construirlo. No voy a fingir que está listo para producción para cualquiera — esto es lo verdadero hoy (junio 2026, release v0.15.0):

Lo que funciona end-to-end, con paridad bit-a-bit fitz run ↔ fitz build:

Server HTTP con @get/@post/@put/@delete, OpenAPI auto, UI Scalar.
Chain de middleware con @middleware(fn) + CORS built-in.
Auth con JWT con @auth_provider/@authenticated/@admin + @requires("role_custom") para RBAC. Hashing de passwords con Argon2id. Token blacklist sobre Postgres para logout/refresh.
WebSockets con WsConn<T>, AsyncAPI auto, heartbeat, auth pre-upgrade.
Cron jobs con @cron("expr") (con retry, timezone, persistencia, catch-up), jobs background con @background + spawn(...).
ORM Postgres con @table/@primary/@column/@belongs_to/@has_many, closure-to-SQL, eager loading, transacciones (db.transaction(fn)), migraciones de schema (fitz db diff/migrate).
TLS estricto para Postgres (sslmode=require).
Async/await sobre tokio.
Interop Python con from python import ..., incluyendo bridge automático para async.
CLI builder con @command — mismo lenguaje para CLI tools.
Stack production: @healthz/@readyz, Secret<T>, secret()/config(), @trace/@metric, @flag, export OpenTelemetry OTLP, endpoint Prometheus /metrics, fitz docker init/build, fitz deploy.
Package manager con path deps y git deps.
Tooling completo: LSP (con signature help, format on save, hover sobre params y bindings), fmt, test, dev, repl, lint.

Lo que todavía no está en la caja:

Frontend en .fitz (single-file components, SSR). Roadmap (Fase 11) — la apuesta más ambiciosa del proyecto. Sin arrancar.
Un registry público de paquetes. Path deps y git deps funcionan hoy; el registry está en pausa hasta que aparezca demanda real.
Targets de fitz deploy más allá de docker/compose (todavía no hay wrapper de fly/railway/k8s — usá los CLIs nativos).
Debugging interactivo en VSCode (Debug Adapter Protocol). Workarounds: print, REPL :type/:env, diagnostics LSP. Trackeado como V6 en el backlog.

Lo que es estable: ~3030 tests unit de Rust + 13 LSP E2E + 360 compile E2E (smoke sobre cada ejemplo de la guía) + ~140 más entre otras suites corriendo en CI en cada push. Clippy -D warnings limpio.

Cómo probarlo

# Instalación en Linux / macOS / WSL
curl -sSf https://thegreekman76.github.io/fitz/install.sh | sh

# Instalación en Windows (PowerShell)
irm https://thegreekman76.github.io/fitz/install.ps1 | iex

# O bajá un binario desde GitHub
# https://github.com/Thegreekman76/fitz/releases

# Reabrí la terminal para que el cambio de PATH aplique, después:
fitz --version

Extensión VSCode (recomendado — syntax highlighting, hover con tipos, autocomplete, signature help, format on save): bajá el .vsix de tu plataforma desde la misma página de releases (fitz-lang-<plataforma>.vsix) e instalala con code --install-extension fitz-lang-<plataforma>.vsix --force. El Language Server viene incluido — no hace falta instalarlo aparte. Recargá VSCode una vez.

Primer server:

fitz new mi-api --http
cd mi-api
fitz dev

Vienen ocho boilerplates en el repo bajo boilerplates/:

api-simple — API HTTP mínima.
api-middleware-cors — chain de middleware + config de CORS.
api-postgres-fitz — ORM + Postgres, Dockerizado.
api-postgres-python — Postgres vía interop Python/SQLAlchemy.
api-websocket — chat WebSocket tipado.
api-orm-full — el showcase completo: auth + ORM + WebSockets + cron + jobs.
api-fullstack-postgres — backend + frontend mínimo en un binario.
cli-tool — app CLI con @command (sin HTTP).

Cada uno corre con docker compose up o fitz dev. El README tiene la matriz completa.

Por qué construí esto

Vivo en El Chaltén, en la Patagonia argentina. El Fitz Roy es la torre de granito que define el horizonte acá. Borges escribió que vivimos en un país donde el pasado es incierto y solo el futuro es real. Creo que también vale para los lenguajes de programación: el pasado está lleno de workarounds acumulados por features que faltan en el lenguaje, y el futuro es lo que vos decidís construir.

Llevo diez años escribiendo código de APIs en Python. Amo FastAPI. Pero cada vez que arranco un proyecto nuevo, las primeras tres horas se van pegando librerías para hacer lo mismo que hice la semana pasada. En algún punto la pregunta se vuelve: ¿cómo sería un lenguaje que arrancara desde este conjunto de necesidades en 2026, en lugar de hacerlas crecer como parches sobre un lenguaje diseñado para scripting de shell en 1991?

Eso es Fitz.

No está terminado. Soy uno solo. Va a llegar.

Repo: github.com/Thegreekman76/fitz
Docs y curso: thegreekman76.github.io/fitz
Guía (34 capítulos): thegreekman76.github.io/fitz/guide/
Roadmap: docs/roadmap.md
CHANGELOG: CHANGELOG.md — cada release con detalle.
Issues: github.com/Thegreekman76/fitz/issues

Si lo probás, quiero saber qué se rompió. Abrí un issue o una discussion en GitHub.

Introducing Fitz: a language where HTTP, Postgres, JWT, and WebSockets are part of the syntax

Martin Palopoli — Sat, 06 Jun 2026 11:07:43 +0000

Fitz is a new programming language built in Rust, with a gradually-typed compiler. The pitch: instead of stacking FastAPI + SQLAlchemy + python-jose + Celery + Pydantic + uvicorn + Alembic + typer on top of Python, the things they each solve live inside the language: HTTP routing, OpenAPI/AsyncAPI generation, async/await, JWT auth, password hashing, an ORM with a pure-Rust Postgres driver, schema migrations, WebSockets, cron, background jobs, a CLI builder, healthchecks, observability with OpenTelemetry, secrets as opaque types, and a fitz deploy orchestrator. One binary. Zero external deps for the core stack. Repo: github.com/Thegreekman76/fitz · Docs: thegreekman76.github.io/fitz<

I've been building web APIs in Python for years — FastAPI plus the usual cast: SQLAlchemy, python-jose for JWT, passlib for Argon2, Celery + Redis for background jobs, Pydantic for validation, uvicorn for serving, alembic for migrations. Every API I ship needs roughly the same nine libraries, each with its own conventions, its own breaking changes, its own way to integrate with the others.

At some point I asked myself the obvious question: why isn't this just the language?

That question is Fitz.

What Fitz looks like

Let's start with the picture, then walk through the pieces.

@server(43928)
fn main() => 0

type User { id: Int, email: Str, name: Str, role: Str }
type Credentials { email: Str, password: Str }
type LoginResponse { token: Str }

let SECRET = "demo-secret-change-me-in-prod"
let ADA_HASH = hash.password("secret-ada-123")

@auth_provider
fn check_token(headers: Map<Str, Str>) -> Result<User> {
    let auth: Str = match headers.get("authorization") {
        Ok(v) => v,
        Err(_) => return Err("missing Authorization header"),
    }
    let parts = auth.split(" ")
    if (parts.len() != 2 or parts[0] != "Bearer") {
        return Err("expected 'Bearer <token>'")
    }
    let claims = jwt.decode(parts[1], SECRET)?
    return find_user(claims["email"])
}

@post("/login")
fn login(creds: Credentials) -> LoginResponse {
    let user: User = match find_user(creds.email) {
        Ok(u) => u,
        Err(_) => return 401 { "error": "invalid credentials" },
    }
    if (not hash.verify(creds.password, ADA_HASH)) {
        return 401 { "error": "invalid credentials" }
    }
    let claims = { "email": user.email, "role": user.role }
    return LoginResponse { token: jwt.encode(claims, SECRET) }
}

@authenticated
@get("/me")
fn me(user: User) -> User => user

@admin
@get("/admin/users")
fn admin_list(user: User) -> List<User> { ... }

What this code does, without a single import or external dependency:

Starts an HTTP server on port 43928.
Auto-generates OpenAPI 3.1 at /openapi.json.
Auto-serves Scalar UI at /docs with a working "Authorize" button.
Signs and verifies JWT tokens (HS256/384/512 supported).
Hashes passwords with Argon2id (OWASP recommendation, not bcrypt).
Statically validates that every @authenticated/@admin handler has an @auth_provider declared, that the provider returns the right User type, and that @admin handlers have a role: Str field on the User.
Compiles to a single native binary with fitz build, with bit-for-bit parity against fitz run.

The auth, the hashing, the JWT, the OpenAPI with bearerAuth security scheme, the 401/403 responses — all of that is in the binary fitz itself. There's no requirements.txt, no package.json, no Cargo.toml for the user.

Why "first-class" matters

"First-class citizen" is one of those phrases that gets thrown around. Here's what I mean concretely.

In FastAPI, @app.get("/users") is a method on an object instance. The framework is a library you opt into. The router is a Python data structure. Authentication is a Depends(...). None of those things are visible to the type checker as anything special — they're just function calls and decorators that happen to produce metadata.

In Fitz, @get("/users") is a decorator the compiler understands. The checker validates the path template, the parameter types against the path params, the body type, the return type. The OpenAPI generator inspects the AST directly — it doesn't introspect runtime objects, it doesn't need decorators that "register" themselves. The User you return in your handler is the same User that appears in the generated schema and in the Scalar UI.

This sounds like a small distinction until you live it for a week. Then you stop fighting "why does Pydantic disagree with SQLAlchemy about whether this field is optional" and you start writing endpoints.

The pieces

HTTP + OpenAPI + Scalar UI, all auto

type Post { id: Int, title: Str, body: Str, tags: List<Str> }

@get("/posts")
fn list_posts() -> List<Post> { ... }

@post("/posts")
fn create_post(post: Post) -> Post { ... }

That's all you need. /openapi.json and /docs (Scalar UI) appear automatically. Path params (/posts/{id}) are typed and coerced. JSON body deserialization checks for missing required fields, applies defaults, validates nullables, rejects extras. You can opt out with @server(docs=false).

WebSockets, typed, with AsyncAPI auto-generated

type ChatMessage { from: Str, text: Str }

@server(43929, ws_heartbeat_secs=30)
fn main() => 0

@authenticated
@ws("/chat")
async fn chat(conn: WsConn<ChatMessage>, user: User) {
    loop {
        let msg = match conn.recv() {
            Ok(m) => m,
            Err(_) => break,
        }
        conn.broadcast(ChatMessage { from: user.name, text: msg.text })
    }
}

Every frame is auto-marshalled to and from the declared type. Auth runs before the WebSocket upgrade — invalid token gets a 401 without ever opening the socket. Ping/pong heartbeat keeps the connection alive past Nginx's 60s default. /asyncapi.json is generated automatically (the event-driven sibling of OpenAPI). I don't know of another language that auto-generates AsyncAPI from typed source.

Background jobs and cron, no Redis required

@cron("*/5 * * * *")
async fn cleanup_old_sessions() {
    db.exec("DELETE FROM sessions WHERE expires_at < now()")
}

@background
async fn send_welcome_email(email: Str) {
    // expensive thing
}

@post("/signup")
fn signup(creds: Credentials) -> User {
    let user = create_user(creds)
    spawn(send_welcome_email(user.email))  // fire-and-forget, typed Future<Null>
    return user
}

No Celery. No Redis. No celery worker -A app next to your uvicorn process. The scheduler is in your binary. Suitable for 90% of services — when you outgrow it, you outgrow it for a reason, and that's a Fase 11+ problem.

A native ORM with a pure-Rust Postgres driver

This is the piece I'm most proud of, and the one that took the longest. Fitz has its own Postgres driver written in Rust — no libpq, no tokio-postgres, no sqlx. The wire protocol (v3.0), SCRAM-SHA-256 auth, prepared statements, the binary format for 11 OID types — all implemented from the RFC.

@table("users")
type User {
    @primary id: Int,
    email: Str,
    name: Str,
    @has_many("Post", "user_id") posts: List<Post>,
}

@table("posts")
type Post {
    @primary id: Int,
    user_id: Int,
    title: Str,
    body: Str,
    @belongs_to user: User?,
}

@get("/users")
async fn list_users(db: DbConn) -> List<User> {
    return User.all(db).preload("posts").await
}

@get("/users/{id}")
async fn get_user(db: DbConn, id: Int) -> Result<User> {
    return User.where(fn(u) => u.id == id).first(db).await
}

@post("/users")
async fn create_user(db: DbConn, user: User) -> User {
    return User.insert(db, user).await
}

The closure inside .where(...) is translated to parametrized SQL at compile time — fn(u) => u.id == id becomes WHERE id = $1. Operators like .is_in([...]), .like(...), .ilike(...), .contains(...), plus JSONB operators like .has_key(...), .contains_json(...) all map to native Postgres operators. Eager loading with .preload("posts") issues a single batched query. Aggregates (.sum/.avg/.min/.max/.count) and GROUP BY are supported through a separate Aggregated<Row> type.

This compiles to native code via fitz build. The generated binary makes the same Postgres calls. Zero overhead at runtime for the SQL — it's already constant by the time the binary runs, comparable in performance to Diesel or sqlx.

How fast is it really? — head-to-head against SQLAlchemy

The "zero overhead" claim is easy to make and easy to fake, so the repo ships a reproducible bench between two equivalent boilerplates (api-postgres-fitz vs api-postgres-python) — same Postgres, same endpoints, same response shape, same docker compose. Headline numbers on v0.10.13 (Intel Core Ultra 7 155H, Docker 29.2.1, 30s sustained, concurrency 10):

Metric	Fitz ORM	Python + SQLAlchemy	Speedup
Memory peak	9.2 MB	51 MB	5.5× leaner
`GET /users` p50	4.88 ms	37.85 ms	7.76×
`GET /users` RPS	1944	246	7.91×
`GET /users/{id}` p50	3.60 ms	31.87 ms	8.85×
`GET /users/{id}` RPS	2604	296	8.80×
Cold start	0.14 s	0.22 s	1.57×
Image size	131 MB	258 MB	2× lighter

That's ~8× the throughput at ~5× less memory, on the same machine, in the same Docker network, against the same Postgres. Reproduce with bash benchmarks/orm-vs-sqlalchemy/run.sh (~5–8 min with hot Docker cache; needs oha + jq). Full methodology, raw output, and the parts where the comparison is *un*fair to Fitz live in the bench README.

Python interop when you do need it

from python import math, json

let radius = 5.0
let area: Float = math.pi * radius * radius

let parsed: Result<Map<Str, Any>> = match json.loads("{\"name\": \"ada\"}") {
    Ok(d) => Ok(d),
    Err(e) => Err("malformed JSON: {e}"),
}

SQLAlchemy, NumPy, pandas, anything on PyPI — accessible from Fitz with from python import .... The runtime embeds CPython via PyO3. Python exceptions become Result::Err automatically. Async Python (asyncpg, SQLAlchemy 2.x async) bridges to Fitz's .await transparently. You can even do fitz build --bundle-python to ship a binary with CPython embedded — no Python required on the destination machine.

This is intentional. Fitz isn't trying to replace Python's ecosystem — it's trying to give you a better language for the web layer while keeping the door open to everything Python has already built.

Async, finally without color

async fn fetch_user(id: Int) -> Result<User> { ... }

async fn main() {
    let user = fetch_user(42).await?
    print("got {user.name}")
}

async/await is in the core, on a tokio runtime. The ? operator works through Result<T>. The type checker enforces that ? only appears inside functions that return Result<...>. Compiles to async fn + .await in Rust — same execution model as Rust async, same multi-threaded executor.

CLI builder — same language, command-line tools

Fitz isn't only for HTTP services. The same compiler ships a built-in CLI builder, no library needed:

@command("greet", desc="Greet a person")
fn greet(name: Str, loud: Bool = false, count: Int = 1) -> Int {
    let n = count
    while n > 0 {
        if loud { print("HELLO, {name}!") } else { print("hello, {name}") }
        n = n - 1
    }
    return 0
}

@command("add", desc="Sum two numbers")
fn add(a: Int, b: Int) -> Int {
    print("{a + b}")
    return 0
}

$ ./mybin greet Ada --loud --count 3
HELLO, Ada!
HELLO, Ada!
HELLO, Ada!

$ ./mybin --help
USAGE: mybin <command> [ARGS] [OPTIONS]
COMMANDS:
    greet    Greet a person
    add      Sum two numbers

Convention over decoration: params without defaults are positional args, params with defaults are flags. Bool with default = false becomes --flag, other types become --flag <value>. Short flags auto-derive (--loud → -l) with conflict detection. Help auto-generated, exit codes POSIX standard. Bit-for-bit parity between fitz run (development) and fitz build (a self-contained binary you can drop into /usr/local/bin).

This is the same language. Same type checker. Same async/await. Same Result<T> for errors. If your tool needs to hit the database, the ORM is there. If it needs HTTP, @get/@post are there. The line between "web service" and "CLI tool" stops being a stack decision.

Production-ready stack — from repo to production

This is what separates Fitz from "interesting prototype" languages. Real services need health checks, secrets, observability, and a way to ship. All of them are part of the language:

@server(43928)
fn main() => 0

// Auto-mounted at GET /healthz and /readyz — Kubernetes-friendly.
@healthz
fn liveness() -> Bool => true

@readyz
async fn readiness(db: DbConn) -> Bool {
    return match db.exec("SELECT 1").await {
        Ok(_) => true,
        Err(_) => false,
    }
}

// Secret<T> never leaks to logs, prints "***" on Display.
let db_url: Secret<Str> = secret("DATABASE_URL")
let log_level: Str = config("LOG_LEVEL", "info")

// Tracing + metrics with one decorator each.
@trace(name="process_order")
@metric(name="orders")
async fn process(order: Order) -> Result<Receipt> {
    // process_order_duration_seconds (histogram) and orders_calls_total
    // (counter) populate automatically on drop.
}

// Feature flags with two sources: fitz.toml [flags] + FITZ_FLAG_<NAME> env vars.
@flag("new-checkout")
@post("/v2/checkout")
fn v2_checkout(body: Cart) -> Receipt { ... }

Behind the scenes:

HTTP access logs auto-emit with trace_id/span_id propagated to every log.info(...) inside the handler.
OpenTelemetry OTLP export with one env var: OTEL_EXPORTER_OTLP_ENDPOINT. Spans flow to Jaeger/Tempo/Honeycomb. Without the env var, zero overhead, zero network calls.
Prometheus /metrics endpoint exposes counters and histograms — @server(prometheus=true) enables.
@flag on HTTP/WS handlers returns 404 when the flag is off — gate the hot path before middleware/auth.

Deploying:

# Generate the Dockerfile + docker-compose.yml from the program shape.
fitz docker init

# Build the binary, the Docker image, push to a registry.
fitz deploy docker --tag mycorp/api:v1

# Or bring up locally with compose.
fitz deploy compose

fitz docker init reads your AST. If there's a db.connect(...), it adds Postgres to the compose. If there's @server(N), it sets EXPOSE N. If there's @cron, it adds restart: unless-stopped. If there's from python import ..., it picks python:3.12-slim-bookworm instead of distroless. It generates what you'd write by hand, you commit it, edit when you need to.

I'm not aware of another language where deployment is a language feature. It is here because every project I shipped in Python ended with two days of debugging Dockerfile gotchas.

What's the tooling like?

This is the part I underestimated when I started. A language without good tools is dead on arrival. Here's the current state:

fitz run — interpret the file directly. Fastest feedback loop.
fitz build — compile to a native binary via a generated Rust project. Bit-for-bit parity with fitz run is a hard requirement.
fitz check — type checker only, no execution.
fitz test — built-in test runner with @test decorator and assert, assert_eq, assert_throws. Cargo-style output.
fitz dev — hot reload. Watches *.fitz and fitz.toml, kills and respawns the child on change.
fitz fmt — opinionated formatter, zero config. Preserves your comments and blank lines.
fitz lint — 4 built-in lints with // @allow(<name>) suppression. Cargo-clippy-style output.
fitz repl — interactive REPL with multi-line support, :type, :load, persistent history.
fitz openapi — emit the OpenAPI schema without running the server.
fitz db diff/migrate — schema migration tooling. Diff the live DB against the @table types in your code, generate idempotent migrations, apply them with fitz db migrate. Same model as Alembic but with the types as source of truth.
fitz docker init/build — generate the Dockerfile + .dockerignore + docker-compose.yml from the program shape, then docker build wrapped.
fitz deploy docker/compose — thin wrapper to ship the image or bring up locally with one command.
VSCode extension — diagnostics + hover + go-to-definition + autocomplete + signature help + format on save + bidirectional type inference for callbacks, multi-platform distribution.
fitz new + fitz add + fitz remove + fitz update — package manager with fitz.toml, lockfile, path deps, git deps.

The LSP is real (tower-lsp under the hood). The formatter is real (your code round-trips through it). The test runner is real. The whole thing is dogfooded — I write Fitz code with the same VSCode extension I ship.

Being honest about state

This is a one-developer project. I started learning Rust to build it. I'm not going to pretend it's production-ready for everyone — here's what's true today (June 2026, release v0.15.0):

What works end-to-end, with bit-for-bit fitz run ↔ fitz build parity:

HTTP server with @get/@post/@put/@delete, OpenAPI auto, Scalar UI.
Middleware chain with @middleware(fn) + CORS built-in.
JWT auth with @auth_provider/@authenticated/@admin + @requires("custom_role") for RBAC. Argon2id password hashing. Token blacklist over Postgres for logout/refresh.
WebSockets with WsConn<T>, AsyncAPI auto, heartbeat, auth pre-upgrade.
Cron jobs with @cron("expr") (with retry, timezone, persistence, catch-up), background jobs with @background + spawn(...).
Postgres ORM with @table/@primary/@column/@belongs_to/@has_many, closure-to-SQL, eager loading, transactions (db.transaction(fn)), schema migrations (fitz db diff/migrate).
TLS strict for Postgres (sslmode=require).
Async/await on tokio.
Python interop with from python import ..., including auto-bridging async.
CLI builder with @command — same language for CLI tools.
Production stack: @healthz/@readyz, Secret<T>, secret()/config(), @trace/@metric, @flag, OpenTelemetry OTLP export, Prometheus /metrics, fitz docker init/build, fitz deploy.
Package manager with path deps and git deps.
Full tooling: LSP (with signature help, format on save, hover over params and bindings), fmt, test, dev, repl, lint.

What's not in the box yet:

Frontend in .fitz (single-file components, SSR). Roadmap (Fase 11) — the most ambitious bet of the project. Not started.
A public package registry. Path deps and git deps work today; the registry is on hold until there's real demand.
fitz deploy targets beyond docker/compose (no fly/railway/k8s wrapper yet — use the native CLIs).
Interactive debugging in VSCode (Debug Adapter Protocol). Workarounds: print, REPL :type/:env, LSP diagnostics. Tracked as V6 in the backlog.

What's stable: ~3030 Rust unit tests + 13 LSP E2E + 360 compile E2E (smoke over every example in the guide) + ~140 more across other suites running in CI on every push. Clippy -D warnings clean.

How to try it

# Install on Linux / macOS / WSL
curl -sSf https://thegreekman76.github.io/fitz/install.sh | sh

# Install on Windows (PowerShell)
irm https://thegreekman76.github.io/fitz/install.ps1 | iex

# Or grab a release binary from GitHub
# https://github.com/Thegreekman76/fitz/releases

# Reopen the terminal so the PATH change takes effect, then:
fitz --version

VSCode extension (recommended — syntax highlighting, hover with types, autocomplete, signature help, format on save): grab the .vsix for your platform from the same releases page (fitz-lang-<platform>.vsix) and install it with code --install-extension fitz-lang-<platform>.vsix --force. The Language Server is bundled inside — no separate install needed. Reload VSCode once.

First server:

fitz new my-api --http
cd my-api
fitz dev

Eight boilerplates ship in the repo under boilerplates/:

api-simple — minimal HTTP API.
api-middleware-cors — middleware chain + CORS configuration.
api-postgres-fitz — ORM + Postgres, Dockerized.
api-postgres-python — Postgres via Python/SQLAlchemy interop.
api-websocket — typed WebSocket chat.
api-orm-full — the full showcase: auth + ORM + WebSockets + cron + jobs.
api-fullstack-postgres — backend + minimal frontend in one binary.
cli-tool — CLI app with @command (no HTTP).

Each one runs with docker compose up or fitz dev. The README has the full matrix.

Why I built this

I live in El Chaltén, in Argentine Patagonia. The Fitz Roy is the granite tower that defines the skyline here. Borges wrote that we live in a country where the past is uncertain and only the future is real. I think that's true of programming languages too: the past is full of accumulated workarounds for missing language features, and the future is whatever you decide to build.

I've spent ten years writing API code in Python. I love FastAPI. But every time I start a new project, the first three hours are spent gluing libraries together to do the same thing I did last week. At some point the question becomes: what would a language look like that started from this set of needs in 2026, instead of growing them as patches on a language designed for shell scripting in 1991?

That's Fitz.

It's not done. I'm one person. It will get there.

Repo: github.com/Thegreekman76/fitz
Docs and course: thegreekman76.github.io/fitz
Guide (34 chapters): thegreekman76.github.io/fitz/guide/
Roadmap: docs/roadmap.md
CHANGELOG: CHANGELOG.md — every release with detail.
Issues: github.com/Thegreekman76/fitz/issues

If you try it, I want to hear what broke. Open an issue or a discussion on GitHub.

Presentando Citai: el motor RAG que construí en 6 artículos — y que ahora podés probar gratis

Martin Palopoli — Tue, 28 Apr 2026 13:10:00 +0000

Durante los últimos 6 artículos compartí cómo construí cada pieza de un motor RAG de producción: búsqueda híbrida, cross-encoder reranking, streaming SSE, multi-tenancy, cache semántico y detección de idioma. Hoy presento el producto terminado: Citai (cite + AI) — un motor de conocimiento con citación verificable que cualquiera puede probar gratis en citai.ai.

La serie completa

Si llegás a este artículo primero, acá está todo lo que construí y documenté:

Pipeline RAG — búsqueda híbrida (pgvector + BM25), cross-encoder reranking, MMR diversity
Deploy en producción — Docker multi-stage, Nginx, DigitalOcean, zero-downtime deploys
Multi-tenancy — planes, cuotas atómicas, rate limiting con Redis, aislamiento de datos
Streaming SSE — desde el LLM hasta el navegador pasando por Nginx, protocolo custom de 10 eventos
Cache semántico + FAQ — 3 capas de ahorro que reducen ~40% el costo de LLM
Detección de idioma — heurística ES/EN/PT sin APIs externas, reglas de contenido

Cada artículo tiene código real del proyecto. Nada inventado para el tutorial.

Qué es Citai

Citai = cite + AI. Un motor de conocimiento donde cada respuesta cita la fuente exacta (página, documento, párrafo).

La idea nació de una frustración: los chatbots corporativos que dicen "según nuestros documentos..." pero nunca te muestran dónde. No podés verificar nada. No podés confiar.

Citai resuelve eso: subís tus documentos (PDF, DOCX, TXT, o URLs), el sistema los procesa, y cuando alguien pregunta, la respuesta viene con la referencia exacta. Si dice "ver página 15 del manual", podés ir a la página 15 y verificar.

Para quién es

Empresas con documentación interna: manuales, políticas, procedimientos que nadie lee
Equipos de soporte: base de conocimiento que responde antes que el humano
Educación: material de estudio con respuestas verificables
Salud y legal: donde citar la fuente no es opcional, es obligatorio

Cualquier caso donde la respuesta sin fuente no alcanza.

Lo que incluye (y que ya mostré cómo funciona)

Búsqueda híbrida de 3 etapas

Lo que describí en el artículo #1 es exactamente lo que corre en producción:

Query → Vector (pgvector) + BM25 (tsvector)
     → RRF merge (70/30)
     → Cross-encoder rerank
     → MMR diversity (λ=0.6)
     → Top 5-10 fuentes con citación exacta

No es "cosine similarity y listo". Es un pipeline completo con reranking que mejora la relevancia un 25-40% sobre búsqueda vectorial pura.

Confianza calibrada

Cada respuesta tiene un score de confianza (0-100%) basado en los scores del cross-encoder. Si la confianza es baja, el sistema lo dice. No inventa.

"No encontré información suficiente en la documentación disponible
para responder con certeza."

Eso es más valioso que una respuesta inventada con tono seguro.

Widget embebible

Una línea de código:

<script
  src="https://citai.ai/widget.js"
  data-api-key="sk-..."
  data-base-url="https://citai.ai"
></script>

Shadow DOM (no contamina tus estilos), streaming SSE en tiempo real, formularios pre-chat, horario de atención, escalación a humanos, respuestas rápidas, y 4 templates por industria. Todo lo que describí en el artículo #4 sobre SSE es lo que corre en el widget.

RAG configurable sin código

Cada base de conocimiento tiene su propia configuración:

Parámetro	Default	Qué controla
`candidate_k`	30	Candidatos iniciales por búsqueda
`rerank_top_n`	15	Documentos después del reranker
`top_k`	10	Fuentes finales (post-MMR)
`lambda_param`	0.6	Balance relevancia vs diversidad
`bm25_weight`	0.3	Peso de BM25 en la fusión
`faq_threshold`	0.85	Umbral de match para FAQs
`temperature`	0.3	Creatividad del LLM
`chunk_size`	1024	Tamaño de fragmentos

Un admin puede ajustar todo esto desde la UI, sin tocar código. Y el Playground permite testear cambios antes de aplicarlos.

Cache semántico + FAQ matching

Lo del artículo #5 en acción:

FAQ match → respuesta curada en ~15ms, costo $0
Cache hit (similitud ≥ 0.95) → respuesta cacheada en ~20ms, costo $0
Cache miss → pipeline completo en ~2-4s

En producción, entre FAQ y cache se evita el 30-45% de las llamadas al LLM. Eso es plata real ahorrada.

Multilingüe sin APIs externas

Detección automática de ES/EN/PT por heurística (artículo #6). El usuario pregunta en su idioma, Citai responde en ese idioma. Sin latencia extra, sin costo extra.

Los embeddings son multilingües (paraphrase-multilingual-MiniLM-L12-v2), así que podés tener documentos en español y preguntar en inglés — funciona.

Analytics completo

Tasa de resolución (resueltas / escaladas / negativas)
Top 10 preguntas frecuentes
Lagunas de conocimiento (preguntas sin respuesta)
Distribución por tags (auto-tagging con LLM)
Costos por proveedor y ahorro por FAQ/cache
Health Score por base de conocimiento (0-100)
Exportación CSV/JSON

Smart Routing

Si tenés múltiples bases de conocimiento, Citai rutea automáticamente la pregunta a la KB más relevante usando centroides de embeddings. Sin configuración manual.

Reglas de contenido

BLOCK, REDIRECT y FILTER — para controlar qué preguntas se procesan y qué temas se bloquean. Evaluadas antes del LLM, sin costo.

Tool Calling

Conectá APIs externas (clima, calendario, CRM, lo que sea) y el agente las invoca automáticamente cuando la pregunta lo requiere. Templates incluidos para los casos más comunes.

El stack (para los que leyeron toda la serie)

┌─────────────────────────────────────────┐
│            Frontend (Vue 3 + TS)        │
│    Tailwind · vue-i18n · Chart.js       │
├─────────────────────────────────────────┤
│              Nginx (TLS + HTTP/2)       │
│    Proxy SSE · Gzip · Maintenance mode  │
├─────────────────────────────────────────┤
│          Backend (FastAPI async)         │
│   SQLAlchemy · Alembic · JWT · SSE      │
├────────────┬────────────┬───────────────┤
│ PostgreSQL │   Redis    │    Groq       │
│  pgvector  │ Rate limit │  LLaMA 3.3   │
│   BM25     │ Concurrent │  70B versatile│
└────────────┴────────────┴───────────────┘

LLM: Groq como primario (rápido y barato), con fallback a GPT-4o-mini
Embeddings: paraphrase-multilingual-MiniLM-L12-v2 (384 dimensiones, corre local)
Reranker: cross-encoder/ms-marco-MiniLM-L-6-v2 (también local)
DB: PostgreSQL 16 + pgvector (HNSW) + tsvector (BM25)
Infra: Docker Compose en un VPS de 4GB ($24/mes)

Sí, todo esto corre en un droplet de 4GB. El artículo #2 explica cómo.

Planes

	Free	Starter	Pro	Enterprise
Precio	$0	$29/mes	$79/mes	Custom
Consultas IA/mes	50	500	5,000	Ilimitadas
Usuarios	2	5	15	Ilimitados
Bases de conocimiento	1	5	20	Ilimitadas
Documentos	10	50	200	Ilimitados
Almacenamiento	100 MB	500 MB	5 GB	50 GB+
API keys	—	2	10	Ilimitadas
Widget	—	Sí	Sí	White-label
FAQs	Ilimitadas	Ilimitadas	Ilimitadas	Ilimitadas

Las FAQs son ilimitadas en todos los planes. Si una pregunta matchea una FAQ curada, se responde gratis sin consumir consultas IA. Eso no es un truco — es el diseño del artículo #5 en acción.

El plan Free no pide tarjeta de crédito. Registrate, subí un PDF, y preguntale algo.

Lo que aprendí construyendo esto

1. El reranker es lo que más mejora la calidad

Puedo cambiar el LLM, los embeddings, el tamaño de chunks — nada mejora tanto la relevancia como agregar un cross-encoder después de la búsqueda. Es el upgrade más barato en relación costo/beneficio.

2. Las FAQs son aburridas pero poderosas

Una tabla con preguntas y respuestas no es sexy. Pero cada FAQ es una respuesta perfecta, en 15ms, a costo cero, para siempre. En un sistema SaaS multi-tenant, eso escala mejor que cualquier LLM.

3. El cache semántico necesita umbral alto

0.95 de similitud mínima. A 0.90 tuve cache hits incorrectos. Mejor un miss que una respuesta equivocada.

4. Multi-tenancy no es "agregar un tenant_id"

Es plan enforcement con contadores atómicos, rate limiting, aislamiento de datos en cada query, y un sistema de roles que funcione. Lleva más código que el pipeline RAG mismo.

5. SSE streaming a través de Nginx tiene trampas

proxy_buffering off y proxy_cache off son obvios. Pero X-Accel-Buffering: no en el header de respuesta fue lo que realmente lo resolvió. Artículo #4 tiene los detalles.

6. Un VPS de 4GB alcanza para más de lo que pensás

Con 1 worker de Uvicorn (el embedding model usa ~500MB), PostgreSQL tuneado y Redis con 64MB, el sistema sirve tráfico real sin problemas. No necesitás Kubernetes para lanzar.

7. La confianza calibrada cambia la percepción del usuario

Cuando el sistema dice "no estoy seguro" en vez de inventar, el usuario confía más en las respuestas donde sí está seguro. Contra-intuitivo pero medible.

Probalo

citai.ai

Registrate gratis (sin tarjeta)
Subí un PDF o documento
Preguntale algo
Verificá la fuente

Si leíste alguno de los 6 artículos anteriores, todo lo que describí es lo que vas a encontrar adentro. No es un prototipo — es producción.

Qué sigue

Estoy trabajando en:

Importación automática de URLs con sync periódico
Templates por industria más completos
SDK para integración programática
Más proveedores LLM (Mistral, Ollama local)

Si te interesa alguna de estas features, dejá un comentario o contactame. Si encontrás un bug, también — es software real, no una demo.

Gracias

A todos los que leyeron, comentaron y reaccionaron a los artículos anteriores. Esta serie empezó como documentación personal y se convirtió en algo que vale la pena compartir.

Si Citai te parece útil — o si simplemente te interesa el stack — un like ayuda a que llegue a más gente.

Esta es la última entrega de la serie "RAG en Producción". Los 6 artículos anteriores están en mi perfil. Preguntas, feedback o ideas → comentarios abiertos.

Introducing Citai: the RAG engine I built across 6 articles — now free to try

Martin Palopoli — Tue, 28 Apr 2026 13:10:00 +0000

Over the last 6 articles I shared how I built every piece of a production RAG engine: hybrid search, cross-encoder reranking, SSE streaming, multi-tenancy, semantic cache and language detection. Today I'm introducing the finished product: Citai (cite + AI) — a knowledge engine with verifiable citations that anyone can try for free at citai.ai.

The full series

If you're landing on this article first, here's everything I built and documented:

RAG Pipeline — hybrid search (pgvector + BM25), cross-encoder reranking, MMR diversity
Production deploy — Docker multi-stage, Nginx, DigitalOcean, zero-downtime deploys
Multi-tenancy — plans, atomic quotas, Redis rate limiting, data isolation
SSE Streaming — from the LLM to the browser through Nginx, custom 10-event protocol
Semantic cache + FAQ — 3 savings layers that cut ~40% of LLM cost
Language detection — ES/EN/PT heuristics without external APIs, content rules

Every article has real code from the project. Nothing made up for the tutorial.

What is Citai

Citai = cite + AI. A knowledge engine where every answer cites the exact source (page, document, paragraph).

The idea came from a frustration: corporate chatbots that say "according to our documents..." but never show you where. You can't verify anything. You can't trust it.

Citai solves that: upload your documents (PDF, DOCX, TXT, or URLs), the system processes them, and when someone asks a question, the answer comes with the exact reference. If it says "see page 15 of the manual", you can go to page 15 and verify.

Who it's for

Companies with internal documentation: manuals, policies, procedures nobody reads
Support teams: a knowledge base that answers before the human does
Education: study materials with verifiable answers
Healthcare and legal: where citing the source isn't optional — it's mandatory

Any use case where an answer without a source isn't enough.

What's included (and what I already showed how it works)

3-stage hybrid search

What I described in article #1 is exactly what runs in production:

Query → Vector (pgvector) + BM25 (tsvector)
     → RRF merge (70/30)
     → Cross-encoder rerank
     → MMR diversity (λ=0.6)
     → Top 5-10 sources with exact citation

It's not "cosine similarity and done". It's a full pipeline with reranking that improves relevance by 25-40% over pure vector search.

Calibrated confidence

Every answer has a confidence score (0-100%) based on cross-encoder scores. If confidence is low, the system says so. It doesn't make things up.

"I couldn't find enough information in the available documentation
to answer with certainty."

That's more valuable than a fabricated answer delivered with confidence.

Embeddable widget

One line of code:

<script
  src="https://citai.ai/widget.js"
  data-api-key="sk-..."
  data-base-url="https://citai.ai"
></script>

Shadow DOM (won't pollute your styles), real-time SSE streaming, pre-chat forms, business hours, human escalation, quick replies, and 4 industry templates. Everything I described in article #4 about SSE is what runs inside the widget.

No-code RAG configuration

Each knowledge base has its own configuration:

Parameter	Default	What it controls
`candidate_k`	30	Initial candidates per search
`rerank_top_n`	15	Documents after the reranker
`top_k`	10	Final sources (post-MMR)
`lambda_param`	0.6	Relevance vs diversity balance
`bm25_weight`	0.3	BM25 weight in the fusion
`faq_threshold`	0.85	FAQ match threshold
`temperature`	0.3	LLM creativity
`chunk_size`	1024	Chunk size in characters

An admin can adjust all of this from the UI, no code required. And the Playground lets you test changes before applying them.

Semantic cache + FAQ matching

Article #5 in action:

FAQ match → curated answer in ~15ms, cost $0
Cache hit (similarity >= 0.95) → cached response in ~20ms, cost $0
Cache miss → full pipeline in ~2-4s

In production, FAQ and cache combined avoid 30-45% of LLM calls. That's real money saved.

Multilingual without external APIs

Automatic ES/EN/PT detection via heuristics (article #6). Users ask in their language, Citai responds in that language. No extra latency, no extra cost.

The embeddings are multilingual (paraphrase-multilingual-MiniLM-L12-v2), so you can have documents in Spanish and ask in English — it works.

Full analytics

Resolution rate (resolved / escalated / negative)
Top 10 most frequent questions
Knowledge gaps (unanswered queries)
Tag distribution (auto-tagging via LLM)
Cost by provider and FAQ/cache savings
Health Score per knowledge base (0-100)
CSV/JSON export

Smart Routing

If you have multiple knowledge bases, Citai automatically routes the query to the most relevant KB using embedding centroids. No manual configuration.

Content rules

BLOCK, REDIRECT and FILTER — to control which questions get processed and which topics are blocked. Evaluated before the LLM, at zero cost.

Tool Calling

Connect external APIs (weather, calendar, CRM, anything) and the agent invokes them automatically when the question requires it. Templates included for the most common use cases.

The stack (for those who read the whole series)

┌─────────────────────────────────────────┐
│            Frontend (Vue 3 + TS)        │
│    Tailwind · vue-i18n · Chart.js       │
├─────────────────────────────────────────┤
│              Nginx (TLS + HTTP/2)       │
│    Proxy SSE · Gzip · Maintenance mode  │
├─────────────────────────────────────────┤
│          Backend (FastAPI async)         │
│   SQLAlchemy · Alembic · JWT · SSE      │
├────────────┬────────────┬───────────────┤
│ PostgreSQL │   Redis    │    Groq       │
│  pgvector  │ Rate limit │  LLaMA 3.3   │
│   BM25     │ Concurrent │  70B versatile│
└────────────┴────────────┴───────────────┘

LLM: Groq as primary (fast and cheap), with GPT-4o-mini fallback
Embeddings: paraphrase-multilingual-MiniLM-L12-v2 (384 dimensions, runs locally)
Reranker: cross-encoder/ms-marco-MiniLM-L-6-v2 (also local)
DB: PostgreSQL 16 + pgvector (HNSW) + tsvector (BM25)
Infra: Docker Compose on a 4GB VPS ($24/month)

Yes, all of this runs on a 4GB droplet. Article #2 explains how.

Plans

	Free	Starter	Pro	Enterprise
Price	$0	$29/mo	$79/mo	Custom
AI queries/month	50	500	5,000	Unlimited
Users	2	5	15	Unlimited
Knowledge bases	1	5	20	Unlimited
Documents	10	50	200	Unlimited
Storage	100 MB	500 MB	5 GB	50 GB+
API keys	—	2	10	Unlimited
Widget	—	Yes	Yes	White-label
FAQs	Unlimited	Unlimited	Unlimited	Unlimited

FAQs are unlimited across all plans. If a question matches a curated FAQ, it's answered for free without consuming AI queries. That's not a gimmick — it's the design from article #5 in action.

The Free plan doesn't require a credit card. Sign up, upload a PDF, and ask it something.

What I learned building this

1. The reranker improves quality more than anything else

I can swap the LLM, the embeddings, the chunk size — nothing improves relevance as much as adding a cross-encoder after retrieval. It's the cheapest upgrade in terms of cost/benefit ratio.

2. FAQs are boring but powerful

A table with questions and answers isn't sexy. But each FAQ is a perfect answer, served in 15ms, at zero cost, forever. In a multi-tenant SaaS, that scales better than any LLM.

3. Semantic cache needs a high threshold

0.95 minimum similarity. At 0.90 I got incorrect cache hits. A miss is better than a wrong answer.

4. Multi-tenancy is not "add a tenant_id"

It's plan enforcement with atomic counters, rate limiting, data isolation in every query, and a role system that actually works. It takes more code than the RAG pipeline itself.

5. SSE streaming through Nginx has gotchas

proxy_buffering off and proxy_cache off are obvious. But X-Accel-Buffering: no in the response header is what actually fixed it. Article #4 has the details.

6. A 4GB VPS handles more than you'd think

With 1 Uvicorn worker (the embedding model uses ~500MB), tuned PostgreSQL and Redis at 64MB, the system serves real traffic without issues. You don't need Kubernetes to launch.

7. Calibrated confidence changes user perception

When the system says "I'm not sure" instead of making things up, users trust the answers where it is sure even more. Counter-intuitive but measurable.

Try it

citai.ai

Sign up for free (no credit card)
Upload a PDF or document
Ask it something
Verify the source

If you've read any of the 6 previous articles, everything I described is what you'll find inside. It's not a prototype — it's production.

What's next

I'm working on:

Automatic URL import with periodic sync
More industry templates
SDK for programmatic integration
More LLM providers (Mistral, local Ollama)

If you're interested in any of these features, drop a comment or reach out. If you find a bug, same thing — it's real software, not a demo.

Thank you

To everyone who read, commented, and reacted to the previous articles. This series started as personal documentation and became something worth sharing.

If Citai looks useful to you — or if you're just interested in the stack — a like helps it reach more people.

This is the final installment of the "RAG in Production" series. The 6 previous articles are on my profile. Questions, feedback or ideas → comments are open.

Language Detection Without External APIs for a Multilingual RAG System

Martin Palopoli — Tue, 21 Apr 2026 13:02:00 +0000

I implemented complete linguistic intelligence for a multi-tenant RAG engine: heuristic language detection (ES/EN/PT) with zero latency, configurable priority chain, injection into LLM prompts, content rules (BLOCK/REDIRECT/FILTER) for moderation, and browser_lang from the widget. All without external APIs, in ~90 lines of code.

The Multilingual Problem in RAG

Most RAG tutorials assume a single language. In production you'll run into:

Queries in English against documents in Spanish (or vice versa)
Widgets embedded on Brazilian sites receiving Portuguese
The LLM responds in the context's language instead of the user's language

Common "solutions" are detection APIs (Google, AWS Comprehend) that add latency and cost, libraries like langdetect/fasttext that are heavy dependencies for 3 languages, or simply ignoring the problem.

I needed something with zero latency, no dependencies, and configurable per Knowledge Base.

The Solution: Heuristic Detection + Priority Chain

General Approach

Instead of using a full statistical model, I attack the problem in layers:

User query
       │
       ▼
┌──────────────────────┐
│  1. Fixed override?   │──→ If admin forced "en": always use "en"
└──────┬───────────────┘
       │ No override
       ▼
┌──────────────────────┐
│  2. Heuristic         │──→ Count ES/EN/PT keywords
└──────┬───────────────┘
       │ Score < threshold
       ▼
┌──────────────────────┐
│  3. Browser lang?     │──→ Browser language (widget)
└──────┬───────────────┘
       │ Not available
       ▼
    Default: "es"

The Word Lists

The heart of detection is three sets of common words per language:

import re

_PUNCT_RE = re.compile(r"[^\w\s]", re.UNICODE)

_EN_WORDS = {
    "how", "what", "where", "when", "why", "who", "which", "can", "could",
    "would", "should", "does", "do", "is", "are", "the", "this", "that",
    "help", "please", "tell", "explain", "show", "need", "want", "have",
    "about", "from", "with", "your", "they", "there", "their", "been",
    "just", "also", "very", "some", "any", "other", "than", "into",
}

_PT_WORDS = {
    "como", "onde", "quando", "porque", "quem", "qual", "pode", "poderia",
    "esta", "são", "isso", "isto", "ajuda", "ajudar", "mostre", "explique",
    "você", "vocês", "obrigado", "obrigada", "preciso", "quero", "tenho",
    "sobre", "para", "com", "seu", "sua", "eles", "também", "muito",
    "algum", "outro", "mais", "ainda", "aqui", "depois", "antes", "entre",
    "posso", "gostaria", "fazer", "dizer", "favor", "bom", "boa", "dia",
    "noite", "olá", "sim", "não", "bem", "tudo",
}

_ES_WORDS = {
    "qué", "cómo", "dónde", "cuándo", "cuál", "quién", "puedo", "podría",
    "necesito", "quiero", "tengo", "también", "aquí", "después", "ahora",
    "entonces", "pero", "sino", "aunque", "desde", "hasta", "hacia",
    "según", "ayuda", "explicar", "mostrar", "buscar", "hola", "gracias",
    "información", "pregunta", "respuesta", "por", "favor",
}

Key decisions in the lists: English focuses on function words (the, is, are) that almost never appear in Spanish/Portuguese. Portuguese includes key differentiators vs ES: você, não, obrigado, tudo. Spanish uses accents when possible (qué, cómo, dónde) — a user who types with accents is almost certainly writing in Spanish.

The Detection Function

def detect_language(query: str) -> str:
    """Detect query language. Returns 'es', 'en', or 'pt'. Default 'es'."""
    q = _PUNCT_RE.sub("", query.lower().strip())
    words = set(q.split())

    scores = {
        "en": len(words & _EN_WORDS),
        "pt": len(words & _PT_WORDS),
        "es": len(words & _ES_WORDS),
    }
    best = max(scores, key=scores.get)

    if scores[best] >= 2:
        return best
    return "es"

Why threshold of 2? With a single matching word, false positive risk is high. "como" exists in both Spanish and Portuguese. "para" too. But if we find 2+ words from one language, the probability of being correct jumps dramatically.

Why default "es"? My primary use case is Latin America. If I can't detect with confidence, Spanish is the safest bet. This is configurable — you can change the default based on your market.

The Priority Chain: `resolve_language()`

Heuristic detection is just one layer. The real function that decides the language is resolve_language():

_LANG_INSTRUCTIONS = {
    "en": "Respond entirely in English.",
    "pt": "Responda inteiramente em português.",
    "es": "Responde completamente en español.",
}


def resolve_language(
    query: str,
    auto_detect: bool = True,
    override: str | None = None,
    browser_lang: str | None = None,
) -> str:
    """
    Resolve the final language for a query.
    Priority: override > heuristic detection > browser fallback > 'es'.
    """
    # 1. Admin override: ignore everything, force language
    if override and override in ("es", "en", "pt"):
        return override

    # 2. Heuristic: analyze the text
    if auto_detect:
        detected = detect_language(query)
        # If detected something other than default, trust it
        if detected != "es" or not browser_lang:
            return detected

    # 3. Browser lang: user's browser language
    if browser_lang:
        bl = browser_lang.lower()[:2]
        if bl in ("en", "pt", "es"):
            return bl

    # 4. Default
    return "es"

Why This Priority?

Level	Source	When it wins
1	Admin override	Always. If the admin says "this KB is in English", it's respected
2	Heuristic	If it detects EN or PT with confidence (score >= 2)
3	Browser lang	If heuristic couldn't decide (returned "es" by default)
4	Default "es"	Last resort

The subtle trick: if the heuristic returns "es", it could be actual Spanish OR "couldn't detect". In that case, we give browser_lang a chance. If the user's browser is in Portuguese and the query is ambiguous, it's probably Portuguese.

Usage in Chat vs Widget

# Chat: no browser_lang
detected_lang = resolve_language(
    data.content,
    auto_detect=rag_config.language_auto_detect,
    override=rag_config.language_override,
)

# Widget: includes browser_lang as additional fallback
detected_lang = resolve_language(
    data.message,
    auto_detect=rag_config.language_auto_detect,
    override=rag_config.language_override,
    browser_lang=data.browser_lang,
)
lang_hint = get_language_instruction(detected_lang)

The widget captures the browser language and sends it with each request:

var body = {
  message: text,
  session_token: sessionToken,
  browser_lang: widgetLang,  // navigator.language || "es"
};

Injecting Language into the LLM System Prompt

Detecting the language isn't enough — you need to force the LLM to respond in that language. This is done by injecting an explicit instruction at the end of the system prompt:

def _build_messages(query, sources, ..., language_hint=None):
    system_message = identity_prefix + mode_prefix + _build_system_prompt(context)

    if language_hint:
        system_message += f"\n\nIMPORTANT: {language_hint}"

    messages = [{"role": "system", "content": system_message}]
    messages.append({"role": "user", "content": query})
    return messages

Where language_hint is one of:

_LANG_INSTRUCTIONS = {
    "en": "Respond entirely in English.",
    "pt": "Responda inteiramente em português.",
    "es": "Responde completamente en español.",
}

Why at the end of the system prompt? LLMs tend to give more weight to instructions at the beginning and end of the prompt (recency bias). Putting the language at the end maximizes the probability of compliance, even when the document context is in a different language.

Why "IMPORTANT:"? For the same reason. LLMs respond better to instructions marked as important. Without this prefix, Llama 3.3 sometimes ignored the language instruction when all context was in another language.

Multilingual Embeddings: The Silent Hero

All of this works thanks to an embedding model that understands multiple languages in the same vector space:

# config.py
embedding_model: str = "paraphrase-multilingual-MiniLM-L12-v2"

paraphrase-multilingual-MiniLM-L12-v2 generates 384-dimensional vectors and supports 50+ languages. This means:

"How do I reset my password?" (English)
"¿Cómo reseteo mi contraseña?" (Spanish)
"Como redefinir minha senha?" (Portuguese)

Produce embeddings close in vector space, despite being in different languages.

Without multilingual embeddings, an English query would never find Spanish documents. With this model, the user asks in English, pgvector finds Spanish chunks (because the meaning is close), the cross-encoder confirms relevance, and the LLM responds in English. No intermediate translation.

The reranker is also multilingual (cross-encoder/mmarco-mMiniLMv2-L12-H384-v1, trained on mMARCO, 14 languages). Crucial because it evaluates query + chunk together — if they're in different languages, it needs to understand both.

BM25: The Hardcoded tsvector Limitation

There's an elephant in the room. My BM25 search uses PostgreSQL tsvector with 'spanish' hardcoded:

SELECT c.id, c.content, d.filename as document_name,
       ts_rank_cd(c.search_vector, plainto_tsquery('spanish', :query)) as score
FROM chunks c
JOIN documents d ON d.id = c.document_id
WHERE c.knowledge_base_id IN (:kb_ids)
  AND c.search_vector @@ plainto_tsquery('spanish', :query)
ORDER BY score DESC
LIMIT :top_k

The problem: if the user asks in English, plainto_tsquery('spanish', 'how do I reset') won't tokenize English words correctly. Spanish stemming converts "reset" differently than English stemming.

Why I Didn't Change It

Vector search compensates: BM25 is 30% of hybrid search. If it fails for cross-language queries, vector search (70%) still works perfectly thanks to multilingual embeddings.
The OR fallback helps: When the AND query finds no results, a fallback to OR (to_tsquery with |) is more permissive and rescues partial matches.
Complexity vs benefit: Dynamic tsvector by language would require multiple search_vector columns or on-the-fly regeneration. The marginal improvement doesn't justify the cost when vector search is the primary component.

This is a known and documented limitation. If your use case has 80%+ queries in English with English documents, you should change 'spanish' to 'english' — or better yet, to 'simple' which does basic tokenization without language-specific stemming.

Content Rules: Moderation Without LLM

Beyond detecting language, I implemented a content rules system that acts before the RAG pipeline. Three types:

BLOCK: Stop the Query

def evaluate_block_redirect(
    query: str, rules: list[ContentRule]
) -> dict | None:
    q_lower = query.lower()
    for rule in rules:
        if not rule.enabled or rule.type == "filter":
            continue
        for trigger in rule.triggers:
            if trigger.lower() in q_lower:
                return {"type": rule.type, "response": rule.response}
    return None

If a BLOCK trigger matches, the user receives the configured response and the RAG pipeline never executes. Zero tokens, zero LLM latency.

REDIRECT and FILTER

REDIRECT uses the same mechanism as BLOCK but to redirect ("For billing inquiries, contact support@company.com"). FILTER is different — it acts post-retrieval, removing chunks before sending them to the LLM:

def get_filter_terms(rules: list[ContentRule]) -> list[str]:
    terms = []
    for rule in rules:
        if rule.enabled and rule.type == "filter":
            terms.extend(rule.triggers)
    return [t.lower() for t in terms]


def filter_chunks(sources: list[dict], filter_terms: list[str]) -> list[dict]:
    if not filter_terms:
        return sources
    filtered = []
    for source in sources:
        content_lower = source.get("content", "").lower()
        if not any(term in content_lower for term in filter_terms):
            filtered.append(source)
    return filtered

Useful when your documents have sections you don't want the LLM to use as context (internal pricing, confidential information in partially public documents).

The Full Flow

# 1. Content rules check (BLOCK / REDIRECT) — before everything
if rag_config.content_rules:
    rule_match = evaluate_block_redirect(data.content, rag_config.content_rules)
    if rule_match:
        yield {"event": "content_blocked", "data": json.dumps({
            "type": rule_match["type"],
            "response": rule_match["response"],
        })}
        return

# 2. Normal RAG pipeline (vector + BM25 + rerank + MMR)
sources = await search_chunks(db, query, kb_ids, rag_config=rag_config)

# 3. Apply FILTER content rules — after retrieval, before LLM
if rag_config.content_rules:
    blocked_terms = get_filter_terms(rag_config.content_rules)
    if blocked_terms:
        sources = filter_blocked_chunks(sources, blocked_terms)

# 4. LLM with language hint
response = stream_chat_response(query, sources, language_hint=lang_hint)

Everything is stored in each Knowledge Base's rag_config JSONB — no separate table, no migrations:

class ContentRule(BaseModel):
    type: Literal["block", "redirect", "filter"]
    triggers: list[str] = Field(default_factory=list)
    response: str = Field(default="", max_length=500)
    enabled: bool = True

class RAGConfig(BaseModel):
    # ... retrieval, llm, processing configs ...
    language_auto_detect: bool = Field(default=True)
    language_override: str | None = Field(default=None, pattern=r"^(es|en|pt)$")
    content_rules: list[ContentRule] = Field(default_factory=list)

Each KB has its own detection, its own override, and its own content rules.

Frontend and Tracking

In the RAG configuration dialog, the admin has an auto-detection toggle, forced language selector, and inline content rules CRUD:

const languageAutoDetect = ref(true)
const languageOverride = ref('')
const contentRules = reactive<ContentRule[]>([])

// On save
payload.language_auto_detect = languageAutoDetect.value
payload.language_override = languageOverride.value || null
payload.content_rules = contentRules.map(r => ({ ...toRaw(r) }))

If the override is active, the auto-detection toggle is visually disabled — no point detecting if you've already forced a language.

Every query is logged with the detected language (migration 027: detected_language VARCHAR(5) on usage_logs), which allows analyzing language distribution per KB and detecting failure patterns.

Edge Cases and Limitations

1. Very Short Queries

"Reset" — is it English or Spanish (used as an anglicism)? With a single word, there's not enough context. The 2-word minimum threshold protects against this, but it means 1-2 word queries always return the default.

2. Spanglish and Code-Switching

"Necesito help con el login" — tie between ES and EN. Since the score doesn't reach 2 for English, it returns "es". Correct, but not for the ideal reasons.

3. Portuguese vs Spanish

Many words are identical ("como", "para", "sobre"). Differentiation depends on exclusive words like você, não, obrigado. Without them, a Brazilian user may be detected as Spanish-speaking.

4. Pure Technical Queries

"HTTP 403 POST /api/users" — score 0 in all languages, returns default. For queries without natural words, language matters less.

Numbers

Aspect	Value
Detection latency	~0.01ms (set intersection)
Word lists total	~120 words (40 EN + 45 PT + 35 ES)
Confidence threshold	2 words minimum
Languages supported	3 (ES, EN, PT)
Multilingual embeddings	50+ languages (384d)
Multilingual cross-encoder	14 languages
Content rules per KB	Unlimited
Total overhead	< 1ms per request

Lessons Learned

1. You Don't Need an ML Model to Detect 3 Languages

For a small set of languages, word lists + scoring is absurdly effective. An ML model needs to be loaded in memory, has cold start, and its accuracy for short queries (5-10 words) isn't significantly better than a well-calibrated heuristic approach.

2. The Priority Chain Is More Important Than Detection

The resolve_language() function is more valuable than detect_language(). Being able to combine admin override + automatic detection + browser signal in a configurable chain covers 99% of cases. Heuristic detection alone would cover maybe 85%.

3. browser_lang Is Underestimated

In embedded widgets, the browser language is an extremely strong signal. If the browser is set to pt-BR and the query is ambiguous, the user is almost certainly Brazilian. Adding this field to the widget request was one line of code that significantly improved the experience for short or ambiguous queries.

4. Content Rules Are More Useful Than Expected

I started implementing content rules as "nice to have" for basic moderation. In practice, admins use them creatively: redirect billing questions to the right email, block queries about competitors, filter internal sections from documents. They're a control layer that bypasses the LLM.

5. Multilingual Embeddings Do 80% of the Work

The uncomfortable truth is that if you use paraphrase-multilingual-MiniLM-L12-v2 for embeddings, cross-language retrieval works pretty well without doing anything else. Language detection is primarily for controlling the response language of the LLM, not retrieval.

6. Logging the Detected Language Is Essential

Without the detected_language field in usage_logs, I'd be guessing if detection works well. With the data, I can see patterns: "15% of queries to the Brazil widget are detected as Spanish" tells me I need to expand the Portuguese word lists.

What's Next

Character n-gram detection: More robust for short queries than word lists
Dynamic tsvector: Choose dictionary based on detected language ('english', 'portuguese', 'simple')
More languages: French and German only need new word lists
Dynamic stop words: Currently only Spanish — should adapt to the detected language

Conclusion

Multilingual support in RAG doesn't need to be complicated or expensive. Multilingual embeddings as the foundation, heuristic detection in ~90 lines, and a well-designed priority chain cover 99% of cases for ES/EN/PT.

What matters isn't the detection itself — it's the architecture: configurable per KB, with reasonable fallbacks, that logs its decisions for improvement, and where content rules give admins control without going through the LLM. Sometimes the simplest solution is the right one.

If you work with multilingual RAG and found other edge cases, drop a comment. And if this article was useful, a like helps it reach more people.

Detección de idioma sin APIs externas para un sistema RAG multilingüe

Martin Palopoli — Tue, 14 Apr 2026 13:11:00 +0000

Implementé inteligencia lingüística completa para un motor RAG multi-tenant: detección heurística de idioma (ES/EN/PT) con latencia cero, cadena de prioridad configurable, inyección en prompts del LLM, reglas de contenido (BLOCK/REDIRECT/FILTER) para moderación, y browser_lang desde el widget. Todo sin APIs externas, con ~90 líneas de código.

El problema multilingüe en RAG

La mayoría de tutoriales RAG asumen un solo idioma. En producción te encontrás con:

Queries en inglés contra documentos en español (o viceversa)
Widgets embebidos en sitios brasileños recibiendo portugués
El LLM responde en el idioma del contexto en vez del idioma del usuario

Las "soluciones" comunes son APIs de detección (Google, AWS Comprehend) que agregan latencia y costo, librerías como langdetect/fasttext que son dependencias pesadas para 3 idiomas, o directamente ignorar el problema.

Necesitaba algo con latencia cero, sin dependencias, y configurable por Knowledge Base.

La solución: detección heurística + cadena de prioridad

Enfoque general

En vez de usar un modelo estadístico completo, ataco el problema en capas:

Query del usuario
       │
       ▼
┌──────────────────────┐
│  1. Override fijo?    │──→ Si admin forzó "en": usar "en" siempre
└──────┬───────────────┘
       │ No override
       ▼
┌──────────────────────┐
│  2. Heurística        │──→ Contar palabras clave ES/EN/PT
└──────┬───────────────┘
       │ Score < threshold
       ▼
┌──────────────────────┐
│  3. Browser lang?     │──→ Idioma del navegador (widget)
└──────┬───────────────┘
       │ No disponible
       ▼
    Default: "es"

Las word lists

El corazón de la detección son tres sets de palabras comunes por idioma:

import re

_PUNCT_RE = re.compile(r"[^\w\s]", re.UNICODE)

_EN_WORDS = {
    "how", "what", "where", "when", "why", "who", "which", "can", "could",
    "would", "should", "does", "do", "is", "are", "the", "this", "that",
    "help", "please", "tell", "explain", "show", "need", "want", "have",
    "about", "from", "with", "your", "they", "there", "their", "been",
    "just", "also", "very", "some", "any", "other", "than", "into",
}

_PT_WORDS = {
    "como", "onde", "quando", "porque", "quem", "qual", "pode", "poderia",
    "esta", "são", "isso", "isto", "ajuda", "ajudar", "mostre", "explique",
    "você", "vocês", "obrigado", "obrigada", "preciso", "quero", "tenho",
    "sobre", "para", "com", "seu", "sua", "eles", "também", "muito",
    "algum", "outro", "mais", "ainda", "aqui", "depois", "antes", "entre",
    "posso", "gostaria", "fazer", "dizer", "favor", "bom", "boa", "dia",
    "noite", "olá", "sim", "não", "bem", "tudo",
}

_ES_WORDS = {
    "qué", "cómo", "dónde", "cuándo", "cuál", "quién", "puedo", "podría",
    "necesito", "quiero", "tengo", "también", "aquí", "después", "ahora",
    "entonces", "pero", "sino", "aunque", "desde", "hasta", "hacia",
    "según", "ayuda", "explicar", "mostrar", "buscar", "hola", "gracias",
    "información", "pregunta", "respuesta", "por", "favor",
}

Decisiones clave en las listas: Inglés se enfoca en function words (the, is, are) que casi nunca aparecen en español/portugués. Portugués incluye diferenciadores clave vs ES: você, não, obrigado, tudo. Español usa acentos cuando es posible (qué, cómo, dónde) — un usuario que escribe con acentos es casi seguro que está en español.

La función de detección

def detect_language(query: str) -> str:
    """Detect query language. Returns 'es', 'en', or 'pt'. Default 'es'."""
    q = _PUNCT_RE.sub("", query.lower().strip())
    words = set(q.split())

    scores = {
        "en": len(words & _EN_WORDS),
        "pt": len(words & _PT_WORDS),
        "es": len(words & _ES_WORDS),
    }
    best = max(scores, key=scores.get)

    if scores[best] >= 2:
        return best
    return "es"

¿Por qué threshold de 2? Con una sola palabra coincidente, el riesgo de falso positivo es alto. "como" existe en español y portugués. "para" también. Pero si encontramos 2+ palabras de un idioma, la probabilidad de acertar sube dramáticamente.

¿Por qué default "es"? Mi caso de uso principal es Latinoamérica. Si no puedo detectar con confianza, español es la apuesta más segura. Esto es configurable — podés cambiar el default según tu mercado.

La cadena de prioridad: `resolve_language()`

La detección heurística es solo una capa. La función real que decide el idioma es resolve_language():

_LANG_INSTRUCTIONS = {
    "en": "Respond entirely in English.",
    "pt": "Responda inteiramente em português.",
    "es": "Responde completamente en español.",
}


def resolve_language(
    query: str,
    auto_detect: bool = True,
    override: str | None = None,
    browser_lang: str | None = None,
) -> str:
    """
    Resolve the final language for a query.
    Priority: override > heuristic detection > browser fallback > 'es'.
    """
    # 1. Admin override: ignora todo, fuerza idioma
    if override and override in ("es", "en", "pt"):
        return override

    # 2. Heuristic: analiza el texto
    if auto_detect:
        detected = detect_language(query)
        # Si detectó algo que no es el default, confiar
        if detected != "es" or not browser_lang:
            return detected

    # 3. Browser lang: idioma del navegador del usuario
    if browser_lang:
        bl = browser_lang.lower()[:2]
        if bl in ("en", "pt", "es"):
            return bl

    # 4. Default
    return "es"

¿Por qué esta prioridad?

Nivel	Fuente	Cuándo gana
1	Override del admin	Siempre. Si el admin dice "esta KB es en inglés", se respeta
2	Heurística	Si detecta EN o PT con confianza (score >= 2)
3	Browser lang	Si la heurística no pudo decidir (devolvió "es" por default)
4	Default "es"	Último recurso

El truco sutil: si la heurística devuelve "es", podría ser un verdadero español O un "no pude detectar". En ese caso, le damos la oportunidad al browser_lang. Si el navegador del usuario está en portugués y la query es ambigua, probablemente es portugués.

Uso en chat vs widget

# Chat: sin browser_lang
detected_lang = resolve_language(
    data.content,
    auto_detect=rag_config.language_auto_detect,
    override=rag_config.language_override,
)

# Widget: incluye browser_lang como fallback adicional
detected_lang = resolve_language(
    data.message,
    auto_detect=rag_config.language_auto_detect,
    override=rag_config.language_override,
    browser_lang=data.browser_lang,
)
lang_hint = get_language_instruction(detected_lang)

El widget captura el idioma del navegador y lo envía en cada request:

var body = {
  message: text,
  session_token: sessionToken,
  browser_lang: widgetLang,  // navigator.language || "es"
};

Inyectando el idioma en el system prompt del LLM

Detectar el idioma no alcanza — hay que forzar al LLM a responder en ese idioma. Esto se hace inyectando una instrucción explícita al final del system prompt:

def _build_messages(query, sources, ..., language_hint=None):
    system_message = identity_prefix + mode_prefix + _build_system_prompt(context)

    if language_hint:
        system_message += f"\n\nIMPORTANTE: {language_hint}"

    messages = [{"role": "system", "content": system_message}]
    messages.append({"role": "user", "content": query})
    return messages

Donde language_hint es uno de:

_LANG_INSTRUCTIONS = {
    "en": "Respond entirely in English.",
    "pt": "Responda inteiramente em português.",
    "es": "Responde completamente en español.",
}

¿Por qué al final del system prompt? Los LLMs tienden a darle más peso a las instrucciones al principio y al final del prompt (recency bias). Poniendo el idioma al final, maximizamos la probabilidad de que lo respete, incluso cuando el contexto de los documentos está en otro idioma.

¿Por qué "IMPORTANTE:"? Por la misma razón. Los LLMs responden mejor a instrucciones marcadas como importantes. Sin este prefijo, Llama 3.3 a veces ignoraba la instrucción de idioma cuando todo el contexto estaba en otro idioma.

Embeddings multilingües: el héroe silencioso

Todo esto funciona gracias a un modelo de embeddings que entiende múltiples idiomas en el mismo espacio vectorial:

# config.py
embedding_model: str = "paraphrase-multilingual-MiniLM-L12-v2"

paraphrase-multilingual-MiniLM-L12-v2 genera vectores de 384 dimensiones y soporta 50+ idiomas. Esto significa que:

"How do I reset my password?" (inglés)
"¿Cómo reseteo mi contraseña?" (español)
"Como redefinir minha senha?" (portugués)

Producen embeddings cercanos en el espacio vectorial, a pesar de estar en idiomas diferentes.

Sin embeddings multilingües, una query en inglés jamás encontraría documentos en español. Con este modelo, el usuario pregunta en inglés, pgvector encuentra chunks en español (porque el significado es cercano), el cross-encoder confirma la relevancia, y el LLM responde en inglés. Sin traducción intermedia.

El reranker también es multilingüe (cross-encoder/mmarco-mMiniLMv2-L12-H384-v1, entrenado en mMARCO, 14 idiomas). Crucial porque evalúa query + chunk juntos — si están en idiomas diferentes, necesita entender ambos.

BM25: la limitación del tsvector hardcodeado

Hay un elefante en la habitación. Mi búsqueda BM25 usa PostgreSQL tsvector con la configuración 'spanish' hardcodeada:

SELECT c.id, c.content, d.filename as document_name,
       ts_rank_cd(c.search_vector, plainto_tsquery('spanish', :query)) as score
FROM chunks c
JOIN documents d ON d.id = c.document_id
WHERE c.knowledge_base_id IN (:kb_ids)
  AND c.search_vector @@ plainto_tsquery('spanish', :query)
ORDER BY score DESC
LIMIT :top_k

El problema: si el usuario pregunta en inglés, plainto_tsquery('spanish', 'how do I reset') no va a tokenizar correctamente las palabras inglesas. El stemming de español convierte "reset" diferente que el stemming de inglés.

¿Por qué no lo cambié?

La búsqueda vectorial compensa: El BM25 es el 30% de la búsqueda híbrida. Si falla para queries cross-language, la búsqueda vectorial (70%) sigue funcionando perfectamente gracias a los embeddings multilingües.
El fallback OR ayuda: Cuando el AND query no encuentra resultados, un fallback a OR (to_tsquery con |) es más permisivo y rescata matches parciales.
Complejidad vs beneficio: tsvector dinámico por idioma requeriría múltiples search_vector columns o regeneración al vuelo. La mejora marginal no justifica el costo cuando el vector search es el componente principal.

Esto es una limitación conocida y documentada. Si tu caso de uso tiene 80%+ de queries en inglés con documentos en inglés, deberías cambiar 'spanish' por 'english' — o mejor aún, por 'simple' que hace tokenización básica sin stemming idioma-específico.

Content Rules: moderación sin LLM

Además de detectar idioma, implementé un sistema de reglas de contenido que actúa antes del pipeline RAG. Tres tipos:

BLOCK: detener la query

def evaluate_block_redirect(
    query: str, rules: list[ContentRule]
) -> dict | None:
    q_lower = query.lower()
    for rule in rules:
        if not rule.enabled or rule.type == "filter":
            continue
        for trigger in rule.triggers:
            if trigger.lower() in q_lower:
                return {"type": rule.type, "response": rule.response}
    return None

Si un trigger de tipo BLOCK matchea, el usuario recibe el response configurado y el pipeline RAG nunca se ejecuta. Cero tokens, cero latencia de LLM.

REDIRECT y FILTER

REDIRECT usa el mismo mecanismo que BLOCK pero para redirigir ("Para facturación, contacta soporte@empresa.com"). FILTER es diferente — actúa post-retrieval, eliminando chunks antes de enviarlos al LLM:

def get_filter_terms(rules: list[ContentRule]) -> list[str]:
    terms = []
    for rule in rules:
        if rule.enabled and rule.type == "filter":
            terms.extend(rule.triggers)
    return [t.lower() for t in terms]


def filter_chunks(sources: list[dict], filter_terms: list[str]) -> list[dict]:
    if not filter_terms:
        return sources
    filtered = []
    for source in sources:
        content_lower = source.get("content", "").lower()
        if not any(term in content_lower for term in filter_terms):
            filtered.append(source)
    return filtered

Útil cuando tus documentos tienen secciones que no querés que el LLM use como contexto (precios internos, información confidencial en documentos parcialmente públicos).

El flujo completo

# 1. Content rules check (BLOCK / REDIRECT) — antes de todo
if rag_config.content_rules:
    rule_match = evaluate_block_redirect(data.content, rag_config.content_rules)
    if rule_match:
        yield {"event": "content_blocked", "data": json.dumps({
            "type": rule_match["type"],
            "response": rule_match["response"],
        })}
        return

# 2. Pipeline RAG normal (vector + BM25 + rerank + MMR)
sources = await search_chunks(db, query, kb_ids, rag_config=rag_config)

# 3. Apply FILTER content rules — después del retrieval, antes del LLM
if rag_config.content_rules:
    blocked_terms = get_filter_terms(rag_config.content_rules)
    if blocked_terms:
        sources = filter_blocked_chunks(sources, blocked_terms)

# 4. LLM con language hint
response = stream_chat_response(query, sources, language_hint=lang_hint)

Todo se almacena en el rag_config JSONB de cada Knowledge Base — sin tabla separada, sin migraciones:

class ContentRule(BaseModel):
    type: Literal["block", "redirect", "filter"]
    triggers: list[str] = Field(default_factory=list)
    response: str = Field(default="", max_length=500)
    enabled: bool = True

class RAGConfig(BaseModel):
    # ... retrieval, llm, processing configs ...
    language_auto_detect: bool = Field(default=True)
    language_override: str | None = Field(default=None, pattern=r"^(es|en|pt)$")
    content_rules: list[ContentRule] = Field(default_factory=list)

Cada KB tiene su propia detección, su propio override, y sus propias reglas de contenido.

Frontend y tracking

En el diálogo de configuración RAG, el admin tiene toggle de auto-detección, selector de idioma forzado, y CRUD inline de content rules:

const languageAutoDetect = ref(true)
const languageOverride = ref('')
const contentRules = reactive<ContentRule[]>([])

// Al guardar
payload.language_auto_detect = languageAutoDetect.value
payload.language_override = languageOverride.value || null
payload.content_rules = contentRules.map(r => ({ ...toRaw(r) }))

Si el override está activo, el toggle de auto-detección se deshabilita visualmente — no tiene sentido detectar si ya forzaste un idioma.

Cada query se loguea con el idioma detectado (migration 027: detected_language VARCHAR(5) en usage_logs), lo que permite analizar distribución de idiomas por KB y detectar patrones de fallo.

Edge cases y limitaciones

1. Queries muy cortas

"Reset" — ¿es inglés o español (se usa como anglicismo)? Con una sola palabra, no hay suficiente contexto. El threshold de 2 palabras mínimas protege contra esto, pero significa que queries de 1-2 palabras siempre devuelven el default.

2. Spanglish y code-switching

"Necesito help con el login" — empate entre ES y EN. Como el score no llega a 2 para inglés, devuelve "es". Correcto, pero no por las razones ideales.

3. Portugués vs español

Muchas palabras son idénticas ("como", "para", "sobre"). La diferenciación depende de palabras exclusivas como você, não, obrigado. Sin ellas, un brasileño puede ser detectado como hispanohablante.

4. Queries técnicas puras

"HTTP 403 POST /api/users" — score 0 en todos los idiomas, devuelve el default. Para queries sin palabras naturales, el idioma importa menos.

Números

Aspecto	Valor
Latencia de detección	~0.01ms (set intersection)
Word lists total	~120 palabras (40 EN + 45 PT + 35 ES)
Threshold de confianza	2 palabras mínimo
Idiomas soportados	3 (ES, EN, PT)
Embeddings multilingües	50+ idiomas (384d)
Cross-encoder multilingüe	14 idiomas
Content rules por KB	Ilimitadas
Overhead total	< 1ms por request

Lecciones aprendidas

1. No necesitás un modelo de ML para detectar 3 idiomas

Para un set acotado de idiomas, word lists + scoring es absurdamente efectivo. Un modelo de ML necesita cargarse en memoria, tiene cold start, y su accuracy para queries cortas (5-10 palabras) no es significativamente mejor que un enfoque heurístico bien calibrado.

2. La cadena de prioridad es más importante que la detección

La función resolve_language() es más valiosa que detect_language(). Poder combinar override del admin + detección automática + señal del navegador en una cadena configurable cubre el 99% de los casos. La detección heurística sola cubriría quizás el 85%.

3. El browser_lang es subestimado

En widgets embebidos, el idioma del navegador es una señal fortísima. Si el navegador está en pt-BR y la query es ambigua, es casi seguro que el usuario es brasileño. Añadir este campo al request del widget fue una línea de código que mejoró significativamente la experiencia para queries cortas o ambiguas.

4. Content rules son más útiles de lo esperado

Empecé implementando content rules como "nice to have" para moderación básica. En la práctica, los admins los usan creativamente: redirigir preguntas de facturación al email correcto, bloquear queries sobre competidores, filtrar secciones internas de documentos. Son una capa de control que no pasa por el LLM.

5. Embeddings multilingües hacen el 80% del trabajo

La verdad incómoda es que si usás paraphrase-multilingual-MiniLM-L12-v2 para embeddings, el cross-language retrieval funciona bastante bien sin hacer nada más. La detección de idioma es principalmente para controlar el idioma de la respuesta del LLM, no del retrieval.

6. Loguear el idioma detectado es esencial

Sin el campo detected_language en usage_logs, estaría adivinando si la detección funciona bien. Con los datos, puedo ver patrones: "el 15% de queries al widget en Brasil se detectan como español" me dice que necesito expandir las word lists de portugués.

Lo que sigue

Detección por n-gramas de caracteres: Más robusto para queries cortas que word lists
tsvector dinámico: Elegir el diccionario según idioma detectado ('english', 'portuguese', 'simple')
Más idiomas: Francés y alemán solo requieren nuevas word lists
Stop words dinámicas: Hoy son solo español — deberían adaptarse al idioma

Conclusión

El soporte multilingüe en RAG no necesita ser complicado ni caro. Embeddings multilingües como base, detección heurística de ~90 líneas, y una cadena de prioridad bien diseñada cubren el 99% de los casos para ES/EN/PT.

Lo importante no es la detección en sí — es la arquitectura: configurable por KB, con fallbacks razonables, que loguea sus decisiones para poder mejorar, y que las content rules den control al admin sin pasar por el LLM. A veces la solución más simple es la correcta.

Si trabajás con RAG multilingüe y encontraste otros edge cases, dejá un comentario. Y si este artículo te fue útil, un like ayuda a que llegue a más personas.

Semantic Cache and FAQ Matching: How I Cut LLM Costs by 40% in My RAG Engine

Martin Palopoli — Tue, 14 Apr 2026 13:10:00 +0000

Every RAG query costs money: embedding + LLM tokens. I implemented three optimization layers that reduce real cost by 30-45%: FAQ matching (curated answers at zero cost), semantic cache (pgvector with similarity >= 0.95), and auto-FAQ generation from frequent unanswered queries. All with production code and a fallback that keeps the service running when the LLM budget runs out.

The Problem: Every Query Costs Real Money

In previous articles I built a RAG pipeline with hybrid search, reranking and streaming. Works well. But in production:

Typical query:  embedding + search + LLM (~800 tokens) ≈ $0.0003
1,000 queries/day × 30 days = 30,000 queries/month
30,000 × $0.0003 = ~$9/month per tenant
50 tenants = ~$450/month in LLM alone

The key insight: 35-40% of queries are repeated or very similar. Each one is money burned.

Architecture of the 3 Savings Layers

User query
     │
     ▼
┌─────────────┐
│  FAQ Match   │──→ If score ≥ 0.85: curated answer (LLM cost = $0)
└─────┬───────┘
      │ No match
      ▼
┌─────────────────┐
│ Semantic Cache   │──→ If similarity ≥ 0.95: cached response ($0)
└─────┬───────────┘
      │ Cache miss
      ▼
┌─────────────────┐
│ Budget Check     │──→ If budget exhausted: FAQ-only fallback
└─────┬───────────┘
      │ Budget OK
      ▼
  Full RAG pipeline → fire-and-forget: store in cache

Layer 1: FAQ Matching — The Most Profitable Investment

async def match_faq(
    db: AsyncSession, query: str, kb_ids: list[UUID], threshold: float = 0.85,
) -> dict | None:
    query_embedding = embedding_service.embed_query(query)
    kb_ids_str = ",".join(f"'{str(kb_id)}'" for kb_id in kb_ids)

    stmt = text(f"""
        SELECT id, question, answer, attachments,
               1 - (embedding <=> CAST(:embedding AS vector)) as score
        FROM faqs
        WHERE knowledge_base_id IN ({kb_ids_str})
          AND is_active = true AND embedding IS NOT NULL
        ORDER BY embedding <=> CAST(:embedding AS vector)
        LIMIT 1
    """)
    result = await db.execute(stmt, {"embedding": str(query_embedding)})
    row = result.mappings().first()

    if not row or float(row["score"]) < threshold:
        return None

    # Increment hit_count atomically
    await db.execute(
        update(FAQ).where(FAQ.id == row["id"]).values(hit_count=FAQ.hit_count + 1)
    )
    await db.commit()
    return {"faq_id": str(row["id"]), "question": row["question"],
            "answer": row["answer"], "score": float(row["score"])}

The model uses an HNSW index on the embedding so the search takes ~15ms:

class FAQ(Base):
    __tablename__ = "faqs"
    embedding = mapped_column(Vector(384), nullable=True)
    hit_count = mapped_column(Integer, default=0, server_default="0")

    __table_args__ = (
        Index("ix_faqs_embedding", "embedding",
              postgresql_using="hnsw",
              postgresql_ops={"embedding": "vector_cosine_ops"},
              postgresql_with={"m": 16, "ef_construction": 64}),
    )

Threshold Tuning: From 0.75 to 0.85

Started at 0.75. Too low — got false positives where "How do I configure the widget?" matched "What is a widget?". Raised to 0.85 and false positives disappeared:

Query	Stored FAQ	Score	Match?
"how do I reset my password"	"How do I change my password?"	0.91	Yes
"do you accept visa?"	"What payment methods do you accept?"	0.87	Yes
"how do I configure the widget"	"What is a widget?"	0.72	No

When there's a match, the full pipeline doesn't execute:

if faq_match:
    yield {"event": "faq_match", "data": json.dumps(faq_match)}
    # FAQ matches are free — don't increment billing counters
    fire_and_forget_log_usage(
        query_type="faq", response_tokens=0, provider=None, ...
    )

response_tokens=0 and query_type="faq" — fundamental for savings metrics.

Layer 2: Semantic Cache — pgvector as Intelligent Cache

The Concept

If someone asks "How do I reset my password?" and 2 hours ago another asked "How can I change my password?", the answer is the same. Semantic cache detects that equivalence by comparing embeddings, not exact strings.

The model stores the query embedding, response, sources, and a hash of the RAG configuration:

class ResponseCache(Base):
    __tablename__ = "response_cache"

    query_embedding = mapped_column(Vector(384), nullable=False)
    query_text = mapped_column(String(500), nullable=False)
    response_text = mapped_column(Text, nullable=False)
    sources = mapped_column(JSONB, nullable=False, default=list)
    confidence = mapped_column(Float, nullable=False)
    knowledge_base_ids = mapped_column(ARRAY(UUID(as_uuid=True)), nullable=False)
    rag_config_hash = mapped_column(String(64), nullable=False)
    hit_count = mapped_column(Integer, default=0, server_default="0")
    expires_at = mapped_column(DateTime(timezone=True), nullable=False)

Config Hash: Scoping by Configuration

If the admin changes RAG parameters, cached answers are no longer valid:

def compute_config_hash(retrieval_config, language: str | None = None) -> str:
    key_fields = {
        "candidate_k": retrieval_config.candidate_k,
        "rerank_top_n": retrieval_config.rerank_top_n,
        "top_k": retrieval_config.top_k,
        "lambda_param": retrieval_config.lambda_param,
        "max_per_doc": retrieval_config.max_per_doc,
        "bm25_weight": retrieval_config.bm25_weight,
        "language": language or "es",
    }
    return hashlib.sha256(json.dumps(key_fields, sort_keys=True).encode()).hexdigest()

Lookup: Similarity >= 0.95

CACHE_SIMILARITY_THRESHOLD = 0.95

async def lookup_cache(db, query_embedding, kb_ids, rag_config_hash, tenant_id):
    stmt = text(f"""
        SELECT id, response_text, sources, confidence,
               1 - (query_embedding <=> CAST(:embedding AS vector)) AS similarity
        FROM response_cache
        WHERE tenant_id = :tid AND expires_at > now()
          AND rag_config_hash = :config_hash
          AND knowledge_base_ids @> {kb_array}
        ORDER BY query_embedding <=> CAST(:embedding AS vector)
        LIMIT 1
    """)
    row = result.mappings().first()
    if not row or float(row["similarity"]) < CACHE_SIMILARITY_THRESHOLD:
        return None

    await db.execute(
        text("UPDATE response_cache SET hit_count = hit_count + 1 WHERE id = :cid"),
        {"cid": str(row["id"])},
    )
    return {"response_text": row["response_text"], "sources": row["sources"],
            "confidence": float(row["confidence"])}

Why 0.95? At 0.90 I had incorrect cache hits:

Query A	Query B	Similarity	Same answer?
"How do I export to CSV"	"How do I download data as CSV"	0.97	Yes
"How do I configure the webhook"	"How do I test the webhook"	0.92	No
"How do I add users"	"How do I delete users"	0.91	No

Fire-and-Forget Storage

You can't block SSE streaming to save to cache:

def fire_and_forget_store_cache(tenant_id, query_embedding, query_text,
                                 kb_ids, rag_config_hash, response_text,
                                 sources, confidence, ttl_hours=168):
    async def _store():
        try:
            async with async_session() as db:
                await store_cache(db, tenant_id, query_embedding, ...)
        except Exception as e:
            logger.error("Failed to store cache: %s", e)

    try:
        loop = asyncio.get_running_loop()
        loop.create_task(_store())
    except RuntimeError:
        pass  # No event loop (tests) — skip

And the condition for caching:

if rag_config.retrieval.cache_enabled and kb_ids and not low_confidence:
    fire_and_forget_store_cache(...)

not low_confidence: we don't cache bad answers.

Proactive Invalidation: The Cache That Doesn't Lie

async def invalidate_kb_cache(db: AsyncSession, kb_id: UUID) -> int:
    result = await db.execute(
        text("DELETE FROM response_cache WHERE CAST(:kb_id AS UUID) = ANY(knowledge_base_ids)"),
        {"kb_id": str(kb_id)},
    )
    await db.commit()
    return result.rowcount

Called automatically on every operation that changes KB content:

# In faq_service.py — when creating, updating or importing FAQs
async def create_faq(db, kb_id, data):
    faq = FAQ(knowledge_base_id=kb_id, ...)
    db.add(faq)
    await db.commit()
    await invalidate_kb_cache(db, kb_id)  # Cache dies
    return faq

Same happens when uploading or reprocessing documents. Simple rule: if a KB's content changed, that KB's cache dies.

Auto-FAQ: Turn Frequent Questions into Real FAQs

The system records queries with low confidence. When one appears multiple times, the admin can auto-generate a FAQ:

async def generate_faq_suggestion(db, unanswered_query_id, kb_id, tenant_id):
    uq = await db.get(UnansweredQuery, unanswered_query_id)

    # Dedup: skip if pending suggestion or similar FAQ (>= 0.85) exists
    similar_faq = await db.execute(text("""
        SELECT 1 - (embedding <=> CAST(:embedding AS vector)) AS score
        FROM faqs WHERE knowledge_base_id = :kb_id AND is_active = true
        ORDER BY embedding <=> CAST(:embedding AS vector) LIMIT 1
    """), ...)
    if faq_row and float(faq_row["score"]) >= 0.85:
        return None  # Similar FAQ already exists

    # Search KB for context, then call LLM
    sources = await search_chunks(db, uq.query_text, [kb_id], ...)
    result = await generate_playground_response(
        query=uq.query_text, sources=sources[:5],
        temperature=0.2, max_tokens=512,
        system_prompt="Answer ONLY with information from the context. "
                      "2-4 sentences. If insufficient info: NO_ANSWER"
    )
    if not result.get("response") or result["response"].strip() == "NO_ANSWER":
        return None

    return SuggestedFAQ(
        tenant_id=tenant_id, knowledge_base_id=kb_id,
        question=uq.query_text, generated_answer=result["response"].strip(),
        embedding=query_embedding, status="pending",
    )

Batch generation prioritizes by frequency:

async def batch_generate_suggestions(db, tenant_id, kb_id, limit=5):
    stmt = text("""
        SELECT uq.id FROM unanswered_queries uq
        WHERE uq.tenant_id = :tid AND uq.resolved = false
          AND NOT EXISTS (
              SELECT 1 FROM suggested_faqs sf
              WHERE sf.source_query_id = uq.id AND sf.status = 'pending'
          )
        ORDER BY uq.occurrence_count DESC LIMIT :lim
    """)
    # Generate suggestions for each...

On approval, the real FAQ is created, cache is invalidated, and the query is marked as resolved. Closed loop.

FAQ-Only Fallback: Degraded Service Without Cutoff

Free plan: 50 AI queries/month. When exhausted, FAQs keep working:

async def is_llm_budget_exhausted(db, tenant_id) -> bool:
    """Soft check — enables FAQ-only fallback, does NOT raise."""
    plan, tenant = await _get_plan_and_tenant(db, tenant_id)
    if not plan:
        return False
    usage = await get_monthly_usage(db, tenant_id)
    if plan.max_messages_month != -1 and usage["messages_month"] >= plan.max_messages_month:
        return True
    return False

In the main flow:

faq_only_mode = await is_llm_budget_exhausted(db, tenant_id)

# FAQ matching always works
if faq_match:
    return faq_response(faq_match)  # Free

# No match + no budget → upgrade card
if faq_only_mode:
    yield {"event": "upgrade_required", "data": json.dumps({
        "message": "You've reached your AI query limit. "
                   "FAQs remain available at no cost."
    })}

Cost Metrics

async def _get_cost_metrics(db, tenant_id, cutoff):
    # Tokens by provider
    # ...configurable prices from settings...
    groq_price = await settings_service.get(db, "cost.groq.price_per_1k_tokens", 0.00027)

    # FAQ savings estimation
    avg_llm_tokens = total_tokens / max(llm_query_count, 1)
    estimated_faq_tokens_saved = int(faq_count * avg_llm_tokens)
    estimated_faq_cost_saved = estimated_faq_tokens_saved / 1000 * groq_price

    return {
        "by_provider": by_provider,
        "total_estimated_cost": round(total_cost, 4),
        "faq_savings": {
            "queries_without_llm": faq_count,
            "estimated_tokens_saved": estimated_faq_tokens_saved,
            "estimated_cost_saved": round(estimated_faq_cost_saved, 4),
        },
        "avg_cost_per_conversation": round(total_cost / conv_count, 6),
    }

Cache hit rate as the 7th stat card in the dashboard:

async def get_cache_stats(db, tenant_id):
    rate_result = await db.execute(text("""
        SELECT
            COUNT(*) FILTER (WHERE query_type = 'cached') AS cached_queries,
            COUNT(*) FILTER (WHERE query_type IN ('chat','widget','cached')) AS total_queries
        FROM usage_logs WHERE tenant_id = :tid
    """))
    return {"hit_rate": round(cached / total, 3), ...}

The Full Flow in the Chat Endpoint

To see how the 3 layers fit together, here's the real order in chat.py:

# 1. Budget check (soft — doesn't raise)
faq_only_mode = await is_llm_budget_exhausted(db, tenant_id)

# 2. FAQ match (always works, even in faq_only_mode)
faq_match = await match_faq(db, data.content, kb_ids, threshold=0.85)
if faq_match:
    return EventSourceResponse(faq_event_generator())  # $0

# 3. Budget exhausted + no FAQ match → upgrade card
if faq_only_mode:
    yield {"event": "upgrade_required", ...}
    return

# 4. Semantic cache lookup
query_embedding = embedding_service.embed_query(effective_query)
config_hash = compute_config_hash(rag_config.retrieval, detected_lang)
cache_hit = await lookup_cache(db, query_embedding, kb_ids, config_hash, tenant_id)
if cache_hit:
    return EventSourceResponse(cache_event_generator())  # $0

# 5. Full RAG pipeline (vector + BM25 + rerank + LLM)
# ... streaming response ...

# 6. Fire-and-forget: store in cache for next time
if not low_confidence:
    fire_and_forget_store_cache(...)

Real Numbers

Metric	Value
FAQ threshold	0.85
Cache threshold	0.95
Default cache TTL	7 days
FAQ match latency	~15ms
Cache lookup latency	~20ms
Full pipeline latency	~2-4s
% queries resolved by FAQ	15-25%
% queries resolved by cache	10-20%
% queries reaching the LLM	55-75%
Estimated total savings	30-45%

Lessons Learned

1. FAQs Are the Best Investment

Not sexy. It's a table with questions and answers. But every FAQ is a perfect answer served in 15ms at zero cost, forever.

2. Cache Threshold Must Be Very High

At 0.90 I had false positives that served incorrect answers. 0.95 is the safe minimum.

3. Fire-and-Forget Is Mandatory for Cache Storage

First attempt was synchronous. If the INSERT takes long, the last streaming token is delayed. Fire-and-forget eliminates that latency.

4. Proactive Invalidation Is Worth It

It's tempting to let cache expire on its own (TTL). But the admin who uploads a document expects updated answers immediately.

5. Auto-FAQ Closes the Loop

Without auto-FAQ, knowledge gaps accumulate. With auto-FAQ, in 2 clicks the frequent question goes from gap to active FAQ.

6. FAQ-Only Fallback > Cutting Off Service

Free-tier users still ask questions that match FAQs. Reduces churn and provides real incentive to upgrade.

7. LLM Prices Must Be Configurable

Hardcoding $0.00027/1K tokens is a trap. Prices change. Storing them in a settings table allows adjustments without a deploy.

Conclusion

Optimizing RAG costs is a problem of avoiding unnecessary work. The three layers (FAQ, cache, auto-FAQ) attack the same principle: if the answer already exists, don't pay to generate it again.

The interesting part: they also improve the experience. FAQ match in 15ms vs 2-4s for the full pipeline. Cache hit in 20ms with the same quality. And pgvector was already in the stack — no need for Redis or Elasticsearch.

This is the fifth article in the series. If it was useful, a like helps it reach more people. Questions about semantic cache or FAQ matching? Drop a comment.

Cache semántico y FAQ matching: cómo reduje un 40% el costo de LLM en mi motor RAG

Martin Palopoli — Tue, 07 Apr 2026 13:10:00 +0000

Cada query RAG cuesta dinero: embedding + tokens de LLM. Implementé tres capas de optimización que reducen el costo real un 30-45%: FAQ matching (respuestas curadas a costo cero), cache semántico (pgvector con similaridad >= 0.95), y auto-generación de FAQs desde queries frecuentes sin respuesta. Todo con código de producción y un fallback que mantiene el servicio activo cuando el presupuesto de LLM se agota.

El problema: cada query cuesta dinero real

En los artículos anteriores construí un pipeline RAG con búsqueda híbrida, reranking y streaming. Funciona bien. Pero en producción:

Query típica:  embedding + búsqueda + LLM (~800 tokens) ≈ $0.0003
1,000 queries/día × 30 días = 30,000 queries/mes
30,000 × $0.0003 = ~$9/mes por tenant
50 tenants = ~$450/mes solo en LLM

El insight clave: el 35-40% de las queries son repetidas o muy similares. Cada una es dinero quemado.

Arquitectura de las 3 capas de ahorro

Query del usuario
     │
     ▼
┌─────────────┐
│  FAQ Match   │──→ Si score ≥ 0.85: respuesta curada (costo LLM = $0)
└─────┬───────┘
      │ No match
      ▼
┌─────────────────┐
│ Semantic Cache   │──→ Si similaridad ≥ 0.95: respuesta cacheada ($0)
└─────┬───────────┘
      │ Cache miss
      ▼
┌─────────────────┐
│ Budget Check     │──→ Si presupuesto agotado: fallback FAQ-only
└─────┬───────────┘
      │ Budget OK
      ▼
  Pipeline RAG completo → fire-and-forget: guardar en cache

Capa 1: FAQ Matching — la inversión más rentable

async def match_faq(
    db: AsyncSession, query: str, kb_ids: list[UUID], threshold: float = 0.85,
) -> dict | None:
    query_embedding = embedding_service.embed_query(query)
    kb_ids_str = ",".join(f"'{str(kb_id)}'" for kb_id in kb_ids)

    stmt = text(f"""
        SELECT id, question, answer, attachments,
               1 - (embedding <=> CAST(:embedding AS vector)) as score
        FROM faqs
        WHERE knowledge_base_id IN ({kb_ids_str})
          AND is_active = true AND embedding IS NOT NULL
        ORDER BY embedding <=> CAST(:embedding AS vector)
        LIMIT 1
    """)
    result = await db.execute(stmt, {"embedding": str(query_embedding)})
    row = result.mappings().first()

    if not row or float(row["score"]) < threshold:
        return None

    # Increment hit_count atomically
    await db.execute(
        update(FAQ).where(FAQ.id == row["id"]).values(hit_count=FAQ.hit_count + 1)
    )
    await db.commit()
    return {"faq_id": str(row["id"]), "question": row["question"],
            "answer": row["answer"], "score": float(row["score"])}

El modelo usa un índice HNSW sobre el embedding para que la búsqueda sea ~15ms:

class FAQ(Base):
    __tablename__ = "faqs"
    embedding = mapped_column(Vector(384), nullable=True)
    hit_count = mapped_column(Integer, default=0, server_default="0")

    __table_args__ = (
        Index("ix_faqs_embedding", "embedding",
              postgresql_using="hnsw",
              postgresql_ops={"embedding": "vector_cosine_ops"},
              postgresql_with={"m": 16, "ef_construction": 64}),
    )

Threshold tuning: de 0.75 a 0.85

Empecé con 0.75. Demasiado bajo — obtuve false positives donde "¿Cómo configuro el widget?" matcheaba con "¿Qué es un widget?". Subí a 0.85 y los falsos positivos desaparecieron:

Query	FAQ almacenada	Score	Match?
"como reseteo mi clave"	"¿Cómo cambio mi contraseña?"	0.91	Si
"aceptan visa?"	"¿Qué medios de pago aceptan?"	0.87	Si
"como configuro el widget"	"¿Qué es un widget?"	0.72	No

Cuando hay match, el pipeline completo no se ejecuta:

if faq_match:
    yield {"event": "faq_match", "data": json.dumps(faq_match)}
    # FAQ matches are free — don't increment billing counters
    fire_and_forget_log_usage(
        query_type="faq", response_tokens=0, provider=None, ...
    )

response_tokens=0 y query_type="faq" — fundamental para las métricas de ahorro.

Capa 2: Cache Semántico — pgvector como cache inteligente

El concepto

Si alguien pregunta "¿Cómo reseteo mi contraseña?" y hace 2 horas otro preguntó "¿Cómo puedo cambiar mi password?", la respuesta es la misma. El cache semántico detecta esa equivalencia comparando embeddings, no strings exactos.

El modelo almacena el embedding del query, la respuesta, las fuentes, y un hash de la configuración RAG:

class ResponseCache(Base):
    __tablename__ = "response_cache"

    query_embedding = mapped_column(Vector(384), nullable=False)
    query_text = mapped_column(String(500), nullable=False)
    response_text = mapped_column(Text, nullable=False)
    sources = mapped_column(JSONB, nullable=False, default=list)
    confidence = mapped_column(Float, nullable=False)
    knowledge_base_ids = mapped_column(ARRAY(UUID(as_uuid=True)), nullable=False)
    rag_config_hash = mapped_column(String(64), nullable=False)
    hit_count = mapped_column(Integer, default=0, server_default="0")
    expires_at = mapped_column(DateTime(timezone=True), nullable=False)

Config hash: scoping por configuración

Si el admin cambia parámetros de RAG, las respuestas cacheadas ya no son válidas:

def compute_config_hash(retrieval_config, language: str | None = None) -> str:
    key_fields = {
        "candidate_k": retrieval_config.candidate_k,
        "rerank_top_n": retrieval_config.rerank_top_n,
        "top_k": retrieval_config.top_k,
        "lambda_param": retrieval_config.lambda_param,
        "max_per_doc": retrieval_config.max_per_doc,
        "bm25_weight": retrieval_config.bm25_weight,
        "language": language or "es",
    }
    return hashlib.sha256(json.dumps(key_fields, sort_keys=True).encode()).hexdigest()

Lookup: similaridad >= 0.95

CACHE_SIMILARITY_THRESHOLD = 0.95

async def lookup_cache(db, query_embedding, kb_ids, rag_config_hash, tenant_id):
    stmt = text(f"""
        SELECT id, response_text, sources, confidence,
               1 - (query_embedding <=> CAST(:embedding AS vector)) AS similarity
        FROM response_cache
        WHERE tenant_id = :tid AND expires_at > now()
          AND rag_config_hash = :config_hash
          AND knowledge_base_ids @> {kb_array}
        ORDER BY query_embedding <=> CAST(:embedding AS vector)
        LIMIT 1
    """)
    row = result.mappings().first()
    if not row or float(row["similarity"]) < CACHE_SIMILARITY_THRESHOLD:
        return None

    await db.execute(
        text("UPDATE response_cache SET hit_count = hit_count + 1 WHERE id = :cid"),
        {"cid": str(row["id"])},
    )
    return {"response_text": row["response_text"], "sources": row["sources"],
            "confidence": float(row["confidence"])}

¿Por qué 0.95? Con 0.90 tuve cache hits incorrectos:

Query A	Query B	Similaridad	¿Misma respuesta?
"Cómo exporto a CSV"	"Cómo descargo datos en CSV"	0.97	Si
"Cómo configuro el webhook"	"Cómo pruebo el webhook"	0.92	No
"Cómo agrego usuarios"	"Cómo elimino usuarios"	0.91	No

Fire-and-forget storage

No podés bloquear el streaming SSE para guardar en cache:

def fire_and_forget_store_cache(tenant_id, query_embedding, query_text,
                                 kb_ids, rag_config_hash, response_text,
                                 sources, confidence, ttl_hours=168):
    async def _store():
        try:
            async with async_session() as db:
                await store_cache(db, tenant_id, query_embedding, ...)
        except Exception as e:
            logger.error("Failed to store cache: %s", e)

    try:
        loop = asyncio.get_running_loop()
        loop.create_task(_store())
    except RuntimeError:
        pass  # No event loop (tests) — skip

Y la condición para cachear:

if rag_config.retrieval.cache_enabled and kb_ids and not low_confidence:
    fire_and_forget_store_cache(...)

not low_confidence: no cacheamos respuestas malas.

Invalidación proactiva: el cache que no miente

async def invalidate_kb_cache(db: AsyncSession, kb_id: UUID) -> int:
    result = await db.execute(
        text("DELETE FROM response_cache WHERE CAST(:kb_id AS UUID) = ANY(knowledge_base_ids)"),
        {"kb_id": str(kb_id)},
    )
    await db.commit()
    return result.rowcount

Se llama automáticamente en cada operación que cambia contenido de una KB:

# En faq_service.py — al crear, actualizar o importar FAQs
async def create_faq(db, kb_id, data):
    faq = FAQ(knowledge_base_id=kb_id, ...)
    db.add(faq)
    await db.commit()
    await invalidate_kb_cache(db, kb_id)  # Cache muere
    return faq

Lo mismo ocurre al subir o reprocesar documentos. Regla simple: si el contenido de una KB cambió, el cache de esa KB muere.

Auto-FAQ: convertir preguntas frecuentes en FAQs reales

El sistema registra queries con baja confianza. Cuando una aparece múltiples veces, el admin puede auto-generar una FAQ:

async def generate_faq_suggestion(db, unanswered_query_id, kb_id, tenant_id):
    uq = await db.get(UnansweredQuery, unanswered_query_id)

    # Dedup: skip si ya hay sugerencia pendiente o FAQ similar (>= 0.85)
    similar_faq = await db.execute(text("""
        SELECT 1 - (embedding <=> CAST(:embedding AS vector)) AS score
        FROM faqs WHERE knowledge_base_id = :kb_id AND is_active = true
        ORDER BY embedding <=> CAST(:embedding AS vector) LIMIT 1
    """), ...)
    if faq_row and float(faq_row["score"]) >= 0.85:
        return None  # Similar FAQ already exists

    # Search KB for context, then call LLM
    sources = await search_chunks(db, uq.query_text, [kb_id], ...)
    result = await generate_playground_response(
        query=uq.query_text, sources=sources[:5],
        temperature=0.2, max_tokens=512,
        system_prompt="Responde SOLO con información del contexto. "
                      "2-4 oraciones. Si no hay info suficiente: NO_ANSWER"
    )
    if not result.get("response") or result["response"].strip() == "NO_ANSWER":
        return None

    return SuggestedFAQ(
        tenant_id=tenant_id, knowledge_base_id=kb_id,
        question=uq.query_text, generated_answer=result["response"].strip(),
        embedding=query_embedding, status="pending",
    )

Batch generation prioriza por frecuencia:

async def batch_generate_suggestions(db, tenant_id, kb_id, limit=5):
    stmt = text("""
        SELECT uq.id FROM unanswered_queries uq
        WHERE uq.tenant_id = :tid AND uq.resolved = false
          AND NOT EXISTS (
              SELECT 1 FROM suggested_faqs sf
              WHERE sf.source_query_id = uq.id AND sf.status = 'pending'
          )
        ORDER BY uq.occurrence_count DESC LIMIT :lim
    """)
    # Generate suggestions for each...

Al aprobar, se crea la FAQ real, se invalida el cache, y la query se marca como resuelta. Ciclo cerrado.

Fallback FAQ-only: servicio degradado sin corte

Plan Free: 50 queries de IA/mes. Cuando se agotan, las FAQs siguen activas:

async def is_llm_budget_exhausted(db, tenant_id) -> bool:
    """Soft check — enables FAQ-only fallback, does NOT raise."""
    plan, tenant = await _get_plan_and_tenant(db, tenant_id)
    if not plan:
        return False
    usage = await get_monthly_usage(db, tenant_id)
    if plan.max_messages_month != -1 and usage["messages_month"] >= plan.max_messages_month:
        return True
    return False

En el flujo principal:

faq_only_mode = await is_llm_budget_exhausted(db, tenant_id)

# FAQ matching funciona siempre
if faq_match:
    return faq_response(faq_match)  # Gratis

# Sin match + sin presupuesto → upgrade card
if faq_only_mode:
    yield {"event": "upgrade_required", "data": json.dumps({
        "message": "Has alcanzado el límite de consultas de IA. "
                   "Las FAQs siguen disponibles sin costo."
    })}

Métricas de costo

async def _get_cost_metrics(db, tenant_id, cutoff):
    # Tokens by provider
    # ...configurable prices from settings...
    groq_price = await settings_service.get(db, "cost.groq.price_per_1k_tokens", 0.00027)

    # FAQ savings estimation
    avg_llm_tokens = total_tokens / max(llm_query_count, 1)
    estimated_faq_tokens_saved = int(faq_count * avg_llm_tokens)
    estimated_faq_cost_saved = estimated_faq_tokens_saved / 1000 * groq_price

    return {
        "by_provider": by_provider,
        "total_estimated_cost": round(total_cost, 4),
        "faq_savings": {
            "queries_without_llm": faq_count,
            "estimated_tokens_saved": estimated_faq_tokens_saved,
            "estimated_cost_saved": round(estimated_faq_cost_saved, 4),
        },
        "avg_cost_per_conversation": round(total_cost / conv_count, 6),
    }

Cache hit rate como 7ma stat card en el dashboard:

async def get_cache_stats(db, tenant_id):
    rate_result = await db.execute(text("""
        SELECT
            COUNT(*) FILTER (WHERE query_type = 'cached') AS cached_queries,
            COUNT(*) FILTER (WHERE query_type IN ('chat','widget','cached')) AS total_queries
        FROM usage_logs WHERE tenant_id = :tid
    """))
    return {"hit_rate": round(cached / total, 3), ...}

El flujo completo en el endpoint de chat

Para ver cómo encajan las 3 capas, este es el orden real en chat.py:

# 1. Budget check (soft — no lanza excepción)
faq_only_mode = await is_llm_budget_exhausted(db, tenant_id)

# 2. FAQ match (funciona siempre, incluso en faq_only_mode)
faq_match = await match_faq(db, data.content, kb_ids, threshold=0.85)
if faq_match:
    return EventSourceResponse(faq_event_generator())  # $0

# 3. Budget exhausted + no FAQ match → upgrade card
if faq_only_mode:
    yield {"event": "upgrade_required", ...}
    return

# 4. Semantic cache lookup
query_embedding = embedding_service.embed_query(effective_query)
config_hash = compute_config_hash(rag_config.retrieval, detected_lang)
cache_hit = await lookup_cache(db, query_embedding, kb_ids, config_hash, tenant_id)
if cache_hit:
    return EventSourceResponse(cache_event_generator())  # $0

# 5. Full RAG pipeline (vector + BM25 + rerank + LLM)
# ... streaming response ...

# 6. Fire-and-forget: store in cache for next time
if not low_confidence:
    fire_and_forget_store_cache(...)

Números reales

Métrica	Valor
Threshold FAQ	0.85
Threshold cache	0.95
TTL cache default	7 días
Latencia FAQ match	~15ms
Latencia cache lookup	~20ms
Latencia pipeline completo	~2-4s
% queries resueltas por FAQ	15-25%
% queries resueltas por cache	10-20%
% queries que llegan al LLM	55-75%
Ahorro estimado total	30-45%

Lecciones aprendidas

1. Las FAQs son la mejor inversión

No es sexy. Es una tabla con preguntas y respuestas. Pero cada FAQ es una respuesta perfecta servida en 15ms a costo cero, para siempre.

2. El threshold del cache debe ser muy alto

Con 0.90 tuve falsos positivos que sirvieron respuestas incorrectas. 0.95 es el mínimo seguro.

3. Fire-and-forget es obligatorio para cache storage

El primer intento fue síncrono. Si el INSERT tarda, el último token del streaming se demora. Fire-and-forget elimina esa latencia.

4. La invalidación proactiva vale la pena

Es tentador dejar que el cache expire solo (TTL). Pero el admin que sube un documento espera respuestas actualizadas inmediatamente.

5. Auto-FAQ cierra el ciclo

Sin auto-FAQ, las knowledge gaps se acumulan. Con auto-FAQ, en 2 clicks la pregunta frecuente pasa de gap a FAQ activa.

6. Fallback FAQ-only > cortar el servicio

Los usuarios free siguen haciendo preguntas que matchean FAQs. Reduce churn y da incentivo real para upgradear.

7. Los precios de LLM deben ser configurables

Hardcodear $0.00027/1K tokens es una trampa. Los precios cambian. Guardarlos en una tabla de settings permite ajustarlos sin deploy.

Conclusión

Optimizar costos en RAG es un problema de evitar trabajo innecesario. Las tres capas (FAQ, cache, auto-FAQ) atacan el mismo principio: si la respuesta ya existe, no pagues por generarla de nuevo.

Lo interesante: también mejoran la experiencia. FAQ match en 15ms vs 2-4s del pipeline. Cache hit en 20ms con la misma calidad. Y pgvector ya estaba en el stack — no necesitás Redis ni Elasticsearch.

Este es el quinto artículo de la serie. Si te sirvió, un like ayuda a que llegue a más personas. ¿Tenés preguntas sobre cache semántico o FAQ matching? Dejá un comentario.