Metadata-Version: 2.4
Name: tai-chat
Version: 0.4.2
Summary: 
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Author: MateoSaezMata
Author-email: msaez@triplealpha.in
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Provides-Extra: pdf
Requires-Dist: fpdf2 (>=2.7,<3.0) ; extra == "pdf"
Requires-Dist: pydantic (>=2,<2.14)
Requires-Dist: pyyaml (>=6,<7)
Requires-Dist: tai-alphi (>=2.0.1,<3.0)
Requires-Dist: tai-api[database] (>=0.7.2,<0.8)
Requires-Dist: tai-sql (>=0.8.0,<0.9)
Description-Content-Type: text/markdown

# tai-chat

[![PyPI](https://img.shields.io/pypi/v/tai-chat.svg)](https://pypi.org/project/tai-chat/)
[![Python](https://img.shields.io/pypi/pyversions/tai-chat.svg)](https://pypi.org/project/tai-chat/)
[![Licencia: propietaria](https://img.shields.io/badge/licencia-propietaria-red.svg)](LICENSE)
[![Manual](https://img.shields.io/badge/manual-github.io-blue.svg)](https://triplealpha-innovation.github.io/tai-chat/)

**CLI y plantillas para crear chatbots sobre [tai-sql](https://github.com/triplealpha-innovation/tai-sql)
y [tai-api](https://github.com/triplealpha-innovation/tai-api).** Con un comando monta en tu
repositorio un asistente con LLM que responde sobre los datos de la empresa: la API, el agente y sus
herramientas, el front en React, los usuarios y sus permisos, y lo que cuesta cada respuesta. Las
herramientas del agente leen **como el usuario que pregunta**: con sus permisos y sus reglas de fila,
las mismas que la API.

```
config.yaml         ──▶ tai-chat config generate ──▶ el agente, la marca del front, los puertos
rbac/chatbot.py     ──▶ tai-chat db push         ──▶ los roles, y quién ve qué
schemas/chatbot.py  ──▶ tai-chat db push         ──▶ las conversaciones, el catálogo y el consumo
                        tai-chat dev             ──▶ el chat en http://localhost:4713
```

📖 **[El manual completo está en triplealpha-innovation.github.io/tai-chat](https://triplealpha-innovation.github.io/tai-chat/)**

---

## Quickstart

En un repositorio, con PostgreSQL, Poetry, Node 22 y Graphviz:

```bash
pip install tai-chat
echo 'MAIN_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb' >> .env
set -a && . .env && set +a

tai-chat init          # chatbot/ (la API, el asistente y el front) y database/
# completar el .env con lo de chatbot/.env.example, y declarar los modelos en chatbot/config.yaml
tai-chat db push       # schemas, modelos, roles y el usuario admin
tai-chat config        # la tarifa de cada modelo
tai-chat dev           # http://localhost:4713
```

Una herramienta para el agente, en `agente/herramientas/`:

```python
@tool
async def mis_averias(estado: str, runtime: ToolRuntime[Contexto]) -> list[dict]:
    """Las averías del usuario en un estado: abierta, en_curso o cerrada."""
    runtime.context.exigir("read", "averia")                     # su permiso
    filas = await AveriaAsyncDAO.find_many(
        estado=estado, rls=runtime.context.reglas("mantenimiento"), limit=20,  # sus reglas de fila
    )
    return [{"id": f.id, "descripcion": f.descripcion} for f in filas]
```

---

## Los principios que explican el resto

1. **La declaración es la única fuente de verdad.** Un chatbot se declara en `config.yaml`,
   `rbac/chatbot.py` y `schemas/chatbot.py`. Lo demás se deriva y no se edita a mano.
2. **tai-chat consume tai-sql y tai-api, no los reimplementa.** El CRUD, la autenticación, los
   permisos y el cliente TypeScript son los suyos.
3. **El proyecto se despliega sin tai-chat.** Lo que copia `init` no importa `tai_chat`: es una
   herramienta de desarrollo, no una dependencia de producción.
4. **Lo de un usuario solo lo alcanza él,** por la API y a través del agente.
5. **Cada respuesta se cobra,** con la tarifa de su modelo, y sin tarifa, saldo o límite el chat lo
   dice en vez de responder.

---

## Qué trae

| | |
|---|---|
| **El agente** | LangChain y LangGraph, con streaming por WebSocket, memoria por conversación, un límite de vueltas y middlewares para filtrar herramientas por permisos |
| **Herramientas que leen como el usuario** | El token del usuario llega a cada herramienta, que pide su permiso y consulta con sus reglas de fila: las de `owner()` y los roles de tai-api |
| **Sub-agentes** | Herramientas que construyen su propio agente, con sus herramientas, el mismo usuario y el consumo sumado a la respuesta |
| **Modelos** | OpenAI, Azure OpenAI y Google, declarados en `config.yaml`, elegibles por conversación |
| **Consumo** | Tarifas con histórico, margen, límites mensuales por usuario y bolsas de crédito. Cada respuesta se apunta con todas sus llamadas al modelo |
| **El front** | React, Vite, Tailwind y shadcn sobre el cliente de tai-api: el chat, la gestión de usuarios, el consumo y el laboratorio con los pasos del agente. La marca, desde `config.yaml` |
| **Usuarios y roles** | La autenticación de tai-api, con realm y clave de firma propios. Cada uno ve sus conversaciones, también el Administrador |
| **Docker** | Un compose con la API y el front, con los puertos de `config.yaml` |
| **Reglas para asistentes de IA** | `tai-chat rules install` deja en el repositorio cómo funciona el chatbot, cómo se escriben sus herramientas y qué herramientas tiene este, junto a las de tai-sql y tai-api |
| **Valoraciones** | `tai-chat feedback`: un informe en Markdown o PDF de lo que los usuarios valoraron, con su contexto |

---

## El manual

| Sección | Qué responde |
|---|---|
| [Instalación](https://triplealpha-innovation.github.io/tai-chat/empezar/instalacion/) | Qué necesita tu máquina, y por qué |
| [Tu primer chatbot](https://triplealpha-innovation.github.io/tai-chat/empezar/primer-chatbot/) | De un repositorio vacío a un chat que responde |
| [Configurar](https://triplealpha-innovation.github.io/tai-chat/configurar/) | `config.yaml`, los modelos y su consumo, y los roles |
| [El asistente](https://triplealpha-innovation.github.io/tai-chat/asistente/) | Cómo funciona el agente, cómo darle herramientas y cómo construir sub-agentes |
| [El front](https://triplealpha-innovation.github.io/tai-chat/front/) | Qué trae la interfaz y cómo se personaliza |
| [Desplegar](https://triplealpha-innovation.github.io/tai-chat/desplegar/docker/) | Llevar el chatbot a Docker |
| [Referencia](https://triplealpha-innovation.github.io/tai-chat/referencia/comandos/) | Los comandos, la API del asistente, las variables y las migraciones |

---

## Desarrollo

```bash
git clone https://github.com/triplealpha-innovation/tai-chat
cd tai-chat
poetry install --all-extras

poetry run pytest -q -rs     # -rs: lo que se salta, y por qué
```

Los tests van por niveles de infraestructura: sin nada; con el proyecto generado por `init`
(marcador `proyecto`, que también pasa ESLint al front); contra PostgreSQL (`db`), que necesita
`TAI_CHAT_TEST_POSTGRES_URL`; y en el navegador (`navegador`), que además necesita Node y Chromium
(`cd tests/e2e && npm ci && npx playwright-core install chromium`). Lo que no tiene su
infraestructura se salta con el motivo, no falla; en el CI corren todos.

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`, después de pasar la
suite. La rama de trabajo 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-chat. Para quien trabaja **en** tai-chat están
`CLAUDE.md`, las reglas de `.claude/rules/` y las especificaciones de `specs/`.

---

## Licencia

Propietaria: © Triple Alpha Innovation, todos los derechos reservados. Ver [LICENSE](LICENSE).

---

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

