Metadata-Version: 2.5
Name: despertar
Version: 0.1.0
Summary: Agentes que duermen como filas en tu aplicación y despiertan cuando se les necesita, gobernados por sustrato.
Author-email: Alejandro Andrade <alexlqi@gmail.com>
License-Expression: CC-BY-ND-4.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,ai-agents,durable,event-driven,fastapi,llm,sustrato
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: sustrato>=0.4
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34; extra == 'bedrock'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: sustrato[fastapi,postgres]; extra == 'dev'
Description-Content-Type: text/markdown

# despertar

**Agentes que duermen como filas en tu aplicación y despiertan cuando se les necesita.**

Un agente de despertar no corre todo el tiempo ni vive en otro sistema. Es un compromiso guardado en la base de datos de tu app: *cuando llegue un mensaje del inquilino, clasifícalo y responde*. Duerme sin consumir nada, despierta cuando llega su evento o su hora, decide y vuelve a dormir.

- **Despierta por evento o por tiempo.** Miles de agentes dormidos son miles de filas, no miles de procesos.
- **Decide con reglas o con un LLM acotado.** Un handler cognitivo le da al LLM un menú cerrado (`Intent`); el LLM solo elige una opción y llena campos tipados. El texto libre llega como `Untrusted` y nunca alcanza un efecto: el compilador lo demuestra.
- **Lo que se repite deja de necesitar al LLM.** La cristalización detecta secuencias repetidas en el ledger y las propone como reglas deterministas.
- **Gobernado por sustrato.** Todo lo que un agente decide es un plan que [sustrato](https://github.com/alexlqi/sustrato) valida y ejecuta: solo rutas expuestas, `undo`, confirmación humana, presupuestos, `deploy` por commit y ledger encadenado. Un agente de despertar no tiene más poder que cualquier otro cliente de tu API.

## Instalación

```bash
pip install "sustrato[agents]"      # sustrato + despertar
```

## Uso

```python
import sustrato, despertar
from despertar import Intent
from sustrato import Untrusted

engine = sustrato.attach(app, user=get_current_user)            # gobierno: sustrato
agents = despertar.attach(engine, llm=despertar.OpenAICompatibleLLM(base_url=..., model=...))


class IntentInquilino(Intent):
    class PromesaPago:
        fecha: date
    class Disputa:
        motivo: Untrusted[str]


@agents.on_event("MensajeInquilino", intents=IntentInquilino,
                 routes=["POST /contratos/{id}/recordatorio", "POST /contratos/{id}/tickets"])
def clasificar(ev, intent, ctx):
    match intent:
        case IntentInquilino.PromesaPago(fecha=f):
            ctx.schedule("recordar-promesa", "POST /contratos/{id}/recordatorio", at=f)
        case IntentInquilino.Disputa():
            ctx.do("POST /contratos/{id}/tickets")
```

Los handlers también se declaran en `handlers:` de `sustrato.yaml`; `despertar.attach` los carga. `sustrato compile` analiza su cognición y su taint cuando despertar está instalado.

## Relación con sustrato

| sustrato (gobierno) | despertar (agentes) |
| --- | --- |
| Compromisos, `on`/`schedule`/`cancel`, tick, leases | Handlers de eventos, deterministas y cognitivos |
| Planes con `settle` y `undo`, confirmaciones, presupuestos | Menús de intención y adaptadores LLM |
| Contrato `sustrato.yaml`, `deploy` por commit, ledger | Análisis de taint de handlers |
| Plano de datos para cualquier agente | Cristalización y `% sin LLM` |

La dependencia va en una sola dirección: despertar depende de sustrato, nunca al revés.

## Desde sustrato 0.3

Los imports viejos (`from sustrato import FakeLLM, Intent`, `sustrato.llm`, `sustrato.crystal`, `engine.on_event`) siguen funcionando en sustrato 0.4 con un `DeprecationWarning` y desaparecen en 0.5. Con despertar instalado, `sustrato.Sustrato(...)` lo instala solo; la forma recomendada es `despertar.attach(engine, llm=...)`.

## Desarrollo

```bash
pip install -e ../sustrato -e ".[dev]"
pytest
```

**Licencia:** CC BY-ND 4.0 (ver `LICENSE` y `NOTICE`), igual que sustrato; en revisión. **Autor:** Alejandro Andrade ([@alexlqi](https://github.com/alexlqi)).
