tai-api
Framework declarativo de Python, sobre FastAPI, que convierte un schema de tai-sql en una API REST completa. No se escriben endpoints: se declara la base de datos con tai-sql, se declara quién puede hacer qué en un fichero de permisos, y tai-api genera el resto —endpoints, autenticación, permisos, filtrado por fila, documentación— y el cliente TypeScript que la consume.
schemas/public.py (tai-sql) ──▶ tai-api generate ──▶ la API: /public/<tabla>, /auth, /rbac, /docs
rbac/main.py ──▶ tai-api rbac push ──▶ permisos, roles y RLS en la base de datos o en Keycloak
tai-api generate ──▶ el cliente TypeScript del frontend
📖 El manual completo está en triplealpha-innovation.github.io/tai-api
Quickstart
Desde el directorio que contiene el proyecto de tai-sql (database/, con schemas/public.py):
pip install 'tai-api[run]' # generar, y levantar la API con tai-api dev
tai-api init mi-api --install # crea api/
export MAIN_DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
tai-api generate # endpoints, cliente de datos y diagrama
tai-api dev # http://localhost:8000/docs
curl 'http://localhost:8000/public/usuario?limit=5&includes=posts'
Con autenticación:
tai-api auth init # Database o Keycloak
tai-api rbac push # lleva rbac/main.py al backend
tai-api generate
tai-api dev --auth
Los principios que explican el resto
- La API es un derivado desechable. Se regenera entera desde el schema de tai-sql y el
fichero de permisos. Si un endpoint no hace lo que necesitas, no se edita: se arregla la
declaración, o se añade el tuyo en
routers/custom/. - El código generado nunca importa
tai_api. tai-api es una herramienta de desarrollo, no una dependencia de producción. - La misma forma en todos los proyectos. Los mismos endpoints, filtros, errores y sesión: un frontend sabe consultar una API de tai-api sin haberla visto antes.
- Dos modos de autenticación, una sola superficie. Database y Keycloak exponen las mismas rutas y los mismos permisos: un endpoint generado no sabe con cuál funciona.
Qué trae
| Endpoints por tabla | Lectura con filtros por tipo de columna, paginación, orden y relaciones anidadas; escritura uno a uno y masiva; agregaciones con GROUP BY |
| Autenticación | Usuarios en tu base de datos o en Keycloak, con una sesión por usuario, y login por redirección con PKCE |
| La sesión con cookie | El refresh token en una cookie httpOnly que el JavaScript no alcanza, con rotación, detección de reutilización y duraciones de jornada laboral |
| Permisos y RLS | rbac/<realm>.py declara roles y reglas de filtrado por fila, y rbac push los sincroniza con el backend |
| Cliente TypeScript | Tipado, sin dependencias, con la sesión resuelta —refresco de un solo vuelo, varias pestañas—, opciones de TanStack Query y esquemas zod. Avisa si la API cambió desde que se generó |
| Documentación | Swagger, Scalar y el diagrama entidad-relación, protegidos en producción |
| MCP | Las lecturas como herramientas para asistentes de IA (set-mcp) |
| Reglas para asistentes | rules install deja en el repositorio cómo funciona tai-api y cómo es tu API —endpoints, permisos, RLS—, junto a las de tai-sql |
El manual
| Sección | Qué responde |
|---|---|
| Instalación | Qué instalar, y por qué son dos instalaciones y no una |
| Tu primera API | De un schema de tai-sql a una API con login, paso a paso |
| La API | Qué endpoints genera y cómo se consultan |
| Autenticación | Database o Keycloak, la sesión con cookie, permisos y RLS |
| El cliente TypeScript | Consumir la API desde React o Svelte |
| El proyecto | Configuración, extender la API y desplegarla |
| Referencia | Comandos, variables de entorno y códigos de error |
Desarrollo
git clone https://github.com/triplealpha-innovation/tai-api
cd tai-api
poetry install --all-extras
poetry run pytest # todo lo que el entorno permita
poetry run pytest -m "not db and not keycloak" # lo que corre sin servicios
Los tests marcados db levantan la API generada contra PostgreSQL y se saltan si no lo hay;
los marcados keycloak, contra un Keycloak en TAI_API_TEST_KEYCLOAK_URL. Los del cliente
TypeScript necesitan Node 20.
El CI tiene tres workflows: tests.yaml ejecuta la suite en cada push y PR a main y dev,
docs.yaml publica el manual y publish.yaml publica a PyPI en push a main. La rama de trabajo
habitual es dev.
El manual, en local
pip install -r docs/requirements.txt
mkdocs serve # http://127.0.0.1:8000, con recarga en caliente
mkdocs build --strict # lo mismo que valida el CI
El manual vive en docs/ y es para quien usa tai-api. Para quien trabaja en tai-api están
DEV_README.md, el README.md de cada paquete y las reglas de .claude/rules/.
Licencia
MIT. Ver LICENSE.
Desarrollado por Triple Alpha Innovation · Issues
Metadata
Release files for tai-api 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| tai_api-0.5.0.tar.gz | 408.5 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tai_api-0.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 919.1 kB
Release files / tai_api-0.5.0.tar.gz
| Download URL | tai_api-0.5.0.tar.gz |
|---|---|
| Size | 408.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fc645618c48f6313965bc7e9211e3fc2323fbc0f26a48297250c0ab62ca69850
|
|
BLAKE2b-256 checksum How to use checksums |
f4294d692d9f28c10d4521ccc7b69dde2c5934b8d0d5c5458cdddbd85295103c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.11.0 Linux/6.17.0-1022-azure
|
Release files / tai_api-0.5.0-py3-none-any.whl
| Download URL | tai_api-0.5.0-py3-none-any.whl |
|---|---|
| Size | 510.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cab957e11917407e8ed100337e701134c6a432ef3294c6c9b9a6d53fa0b69dcf
|
|
BLAKE2b-256 checksum How to use checksums |
49858df3f4f9695008e56918b8b13a73c21e76db07c641aa5adfe52d1d9dbff4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.11.0 Linux/6.17.0-1022-azure
|
Security for tai-api 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
