Metadata-Version: 2.4
Name: tai-api
Version: 0.5.1
Summary: FastAPI framework with TAI ecosystem integration
License: MIT
License-File: LICENSE
Keywords: fastapi,api,tai,web-framework
Author: MateoSaezMata
Author-email: msaez@triplealpha.in
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Provides-Extra: database
Provides-Extra: rbac
Provides-Extra: run
Requires-Dist: asyncpg (>=0.30.0,<1.0) ; extra == "run"
Requires-Dist: bcrypt (>=4.0.0,<6.0) ; extra == "run"
Requires-Dist: cryptography (>=49.0.0,<50.0.0) ; extra == "run"
Requires-Dist: fastapi[standard] (>=0.116.1,<1.0) ; extra == "run"
Requires-Dist: python-jose (>=3.5.0,<4.0) ; extra == "run"
Requires-Dist: python-multipart (>=0.0.9,<1.0) ; extra == "run"
Requires-Dist: sqlalchemy[asyncio] (>=2.0.0,<3.0) ; extra == "run"
Requires-Dist: tai-alphi (>=2.0.1,<3.0)
Requires-Dist: tai-keycloak (>=0.3.3,<0.4) ; extra == "rbac"
Requires-Dist: tai-sql (>=0.7.13,<1.0)
Requires-Dist: tai-sql[diagrams,hashing] (>=0.7.13,<1.0) ; extra == "database"
Requires-Dist: uvicorn[standard] (>=0.30.0,<1.0) ; extra == "run"
Project-URL: Homepage, https://www.triplealpha.in/es/
Project-URL: Issues, https://github.com/triplealpha-innovation/tai-api/issues
Project-URL: Repository, https://github.com/triplealpha-innovation/tai-api
Description-Content-Type: text/markdown

# tai-api

[![PyPI](https://img.shields.io/pypi/v/tai-api.svg)](https://pypi.org/project/tai-api/)
[![Python](https://img.shields.io/pypi/pyversions/tai-api.svg)](https://pypi.org/project/tai-api/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Manual](https://img.shields.io/badge/manual-github.io-blue.svg)](https://triplealpha-innovation.github.io/tai-api/)

**Framework declarativo de Python, sobre FastAPI, que convierte un schema de
[tai-sql](https://github.com/triplealpha-innovation/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](https://triplealpha-innovation.github.io/tai-api/)**

---

## Quickstart

Desde el directorio que contiene el proyecto de tai-sql (`database/`, con `schemas/public.py`):

```bash
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
```

```bash
curl 'http://localhost:8000/public/usuario?limit=5&includes=posts'
```

Con autenticación:

```bash
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

1. **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/`.
2. **El código generado nunca importa `tai_api`.** tai-api es una herramienta de desarrollo, no
   una dependencia de producción.
3. **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.
4. **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](https://triplealpha-innovation.github.io/tai-api/empezar/instalacion/) | Qué instalar, y por qué son dos instalaciones y no una |
| [Tu primera API](https://triplealpha-innovation.github.io/tai-api/empezar/primer-proyecto/) | De un schema de tai-sql a una API con login, paso a paso |
| [La API](https://triplealpha-innovation.github.io/tai-api/api/) | Qué endpoints genera y cómo se consultan |
| [Autenticación](https://triplealpha-innovation.github.io/tai-api/auth/) | Database o Keycloak, la sesión con cookie, permisos y RLS |
| [El cliente TypeScript](https://triplealpha-innovation.github.io/tai-api/cliente/) | Consumir la API desde React o Svelte |
| [El proyecto](https://triplealpha-innovation.github.io/tai-api/proyecto/configuracion/) | Configuración, extender la API y desplegarla |
| [Referencia](https://triplealpha-innovation.github.io/tai-api/referencia/comandos/) | Comandos, variables de entorno y códigos de error |

---

## Desarrollo

```bash
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

```bash
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](DEV_README.md), el `README.md` de cada paquete y las reglas de `.claude/rules/`.

---

## Licencia

MIT. Ver [LICENSE](LICENSE).

---

<sub>Desarrollado por [Triple Alpha Innovation](https://www.triplealpha.in/es/) ·
[Issues](https://github.com/triplealpha-innovation/tai-api/issues)</sub>

