Metadata-Version: 2.4
Name: mana-ciel
Version: 0.11.0
Summary: Ciel Agent Framework - Enterprise multi-agent harness, model-agnostic, deploy-agnostic
Author: Ciel Agent Framework Authors
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Ander-Labs/ciel-agent-framework
Project-URL: Repository, https://github.com/Ander-Labs/ciel-agent-framework
Project-URL: Issues, https://github.com/Ander-Labs/ciel-agent-framework/issues
Project-URL: Changelog, https://github.com/Ander-Labs/ciel-agent-framework/blob/master/CHANGELOG.md
Keywords: agent,harness,multi-agent,orchestration,llm,enterprise
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: aiofiles>=23.2
Requires-Dist: httpx>=0.27
Requires-Dist: tenacity>=9.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Requires-Dist: croniter>=5.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: uv>=0.5
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Provides-Extra: acp
Requires-Dist: fastapi>=0.112; extra == "acp"
Requires-Dist: uvicorn>=0.30; extra == "acp"
Provides-Extra: gateway
Requires-Dist: fastapi>=0.112; extra == "gateway"
Requires-Dist: uvicorn>=0.30; extra == "gateway"
Requires-Dist: mcp>=1.2; extra == "gateway"
Provides-Extra: security
Requires-Dist: python-dotenv>=1.0; extra == "security"
Provides-Extra: observability
Requires-Dist: opentelemetry-api>=1.20; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "observability"
Requires-Dist: prometheus-client>=0.20; extra == "observability"
Provides-Extra: messaging
Requires-Dist: slack-sdk>=3.27; extra == "messaging"
Provides-Extra: board
Requires-Dist: sqlalchemy>=2.0; extra == "board"
Provides-Extra: pg
Requires-Dist: psycopg[binary]>=3.1; extra == "pg"
Provides-Extra: oidc
Requires-Dist: PyJWT[crypto]>=2.8; extra == "oidc"
Requires-Dist: authlib>=1.3; extra == "oidc"
Requires-Dist: python-multipart>=0.0.9; extra == "oidc"
Provides-Extra: vault
Requires-Dist: hvac>=2.0; extra == "vault"
Provides-Extra: litellm
Requires-Dist: litellm>=1.40; extra == "litellm"
Provides-Extra: rag
Requires-Dist: chromadb>=0.5; extra == "rag"
Requires-Dist: pypdf>=4.0; extra == "rag"
Dynamic: license-file

# Ciel Agent Framework

[![Documentación](https://img.shields.io/badge/docs-MkDocs%20Material-teal?style=flat&logo=mkdocs&logoColor=white)](https://ander-labs.github.io/ciel-agent-framework/)
[Documentación oficial](https://ander-labs.github.io/ciel-agent-framework/)

Enterprise-grade framework to build model-agnostic, deploy-agnostic autonomous agents and multi-agent systems with harness-first principles.

## Packages

| Package | Purpose |
|---|---|
| `ciel` | Public SDK, CLI entrypoint |
| `ciel.providers` | Model provider interface + adapters |
| `ciel.runtime` | Agent runtime, tooling, memory, skills |
| `ciel.orchestration` | Multi-agent orchestration, durable state, supervisor |
| `ciel.gateway` | Platform adapters, messaging gateway |
| `ciel.security` | Approvals, secret redaction, PII scrubber, sandbox |
| `ciel.observability` | Traces, logs, metrics, audit |
| `ciel.entorno` | Execution backends: local, docker, ssh, processpool |
| `ciel.acp` | ACP server for IDE integrations |

## Installation

```bash
pip install mana-ciel        # PyPI distribution name
# or, with uv:
uv pip install mana-ciel
```

The import name stays `ciel`; the CLI command is `ciel`:

```bash
ciel --help
```

> Note: the PyPI package is named **mana-ciel** (the name `ciel` was already taken
> on PyPI). You still `import ciel` and run `ciel` — only the install name differs.

## Quick start

Con la API de alto nivel, un agente son ~15 líneas:

```python
import ciel

@ciel.tool
def add(a: int, b: int) -> int:
    "Suma dos enteros."
    return a + b

from ciel.providers import OpenAICompatibleProvider
provider = OpenAICompatibleProvider(base_url="https://api.openai.com/v1",
                                    api_key="sk-...", default_model="gpt-4o-mini")

agent = ciel.Agent(provider=provider, tools=[add], model="gpt-4o-mini")
resp = agent.run("¿Cuánto es 2 + 3?", tenant_id="acme")
print(resp.text)
```

¿Sin API key? El [Inicio rápido](https://ander-labs.github.io/ciel-agent-framework/guide/quickstart/)
trae un `DummyProvider` 100% offline. También:

```bash
pip install mana-ciel
ciel init my-agent          # scaffold a runnable project (offline-safe)
cd my-agent && uv run python my_agent_agent.py
```

Ciel is extensible via plugins: install a third-party package exposing a
`ciel.plugins` entry point and its providers/tools are auto-discovered — no core
edits. See `docs/guide/` for the developer guide.

> **Extensible vía plugins**: instala un paquete que exponga el entry point
> `ciel.plugins` y sus providers/tools se auto-descubren. Ver
> [`docs/guide/plugins.md`](docs/guide/plugins.md).

## Requirements

- Python >= 3.11
- Package manager/distribution: **uv** (recommended) or pip

## Example

End-to-end offline demo: `examples/end_to_end.py`

```bash
uv run examples/end_to_end.py
```

Covers:
- wiring 3 tools through `ciel.runtime.tools`
- running `DefaultAgentRuntime`
- persisting state with `MemoryStore`
- checkpoint/restore with `CheckpointStore`

## Status

**Release actual: v0.6.0 — ✅ Disponible (Fase 12: Autonomía I — Skill Library).**

La v0.6.0 entrega la **Autonomía I: Skill Library** (adelantada de la v1.2
original del roadmap): library dinámica con auto-verificación offline, versioning
+ changelog, composition engine, doc auto-generation, integración con
`ciel.Agent` (`@ciel.skill` / `agent.teach`), métricas por tenant y el CLI
`ciel skills`. Ver [`docs/roadmap.md`](docs/roadmap.md) y
[`docs/guide/skills.md`](docs/guide/skills.md).

### Fase 1 — Runtime básico: ✅ Cerrada
- `ciel.providers` OpenAI-compatible y Anthropic
- runtime agent loop con tool_calls
- tool registry/schema/dispatcher
- memoria SQLite + FTS5
- skills markdown + frontmatter
- checkpoint store
- project context discovery y render
- context compression head/tail/rewrite
- CLI: `ciel run`, `ciel chat -q`, `ciel compression`, `ciel checkpoints` y `ciel info`

### Fase 2 — Gobierno enterprise: ✅ Cerrada
- políticas de approval (manual / smart / yolo) y redacción integradas al runtime
- redacción de secretos + PII scrubber
- auditoría JSONL por session/tenant, traces por tool call
- multi-tenancy en providers/sinks y validación explícita de `tenant_id`
- credential pools, rotación, sandbox de ejecución

### Fase 3 — Multiagente durable: ✅ Cerrada
- orquestación durable por spec YAML (`AgentSpec`/`AgentStep`), supervisor con budget/rate-limit y topologías pipeline/fan-out/debate
- `KanbanBoard` con filtros por status, assignee y tenant; métricas e índices
- `DurableQueue` SQLite WAL
- CLI: `ciel swarm run`, `ciel board add/list/show/assign`

### Fase 4 — Superficies y despliegue: ✅ Cerrada
- `ciel serve` (FastAPI compuesta: control gateway + host MCP `/mcp` + router webhook), offline-safe con echo provider
- `ciel.gateway.mcp` (cliente/servidor), `ciel.acp` (IDE)
- Dockerfile multi-stage (uv), `docker-compose.yml`, Helm chart `deploy/helm/ciel`
- `deploy/example-enterprise`, docs SDK públicas
- release v0.1.0 (wheels + CHANGELOG)

### Fase 5 — Orquestación best-of-breed: ✅ Cerrada (`graph`, `flows`, `chat`, `root`, `session` entregados)
ADK.sub_agents + LangGraph + AutoGen.GroupChat + CrewAI.Flows.

Entregado en esta sesión:
- `ciel.orchestration.graph`: grafo de estado explícito (nodes/edges/estado) con checkpoint + reanudación/time-travel estilo LangGraph, montado sobre el `Supervisor` existente (hereda retry/timeout/budget).
- `ciel.orchestration.flows` (CrewAI.Flows): flows event-driven con `add_start`/`add_listen`/`add_router`/`add_branch`, estado mutable compartido y `resume` de long-running tras interrupción, sobre `Supervisor`.
- `ciel.orchestration.chat` (AutoGen.GroupChat): `GroupChat` + `GroupChatManager` multi-agente conversable, modelo-agnóstico y OFFLINE-SAFE (participantes = funciones locales sobre el transcripto; soporta `max_rounds`, `selector`, `terminate_keyword`, `terminate_if`).
- `ciel.orchestration.root` (ADK.sub_agents): `RootAgent` con ROUTING a `Specialist` agents sobre `Supervisor` (`router(prompt) -> nombre | None`, con `root_handler` de respaldo).
- `ciel.cli.graph`: `ciel graph demo|run|resume` (offline-safe).
- `ciel.cli.flow`: `ciel flow run|resume` (offline-safe, checkpointer opcional).
- `ciel.cli.chat`: `ciel chat group` (demo offline de 3 agentes que converge con TERMINATE).
- Checkpoint stores (`Graph`/`Flow`/`GroupChat`/`Root`) persisten sobre `MemoryStore` (multitenancy nativo).
- `ciel.orchestration.session` (ADK.session_state): `SessionStore` — session state persistente por tenant entre turnos, sobre `MemoryStore` (keys namespaced `session:`), con `append_turn`/`history`, `save_state`/`load_state`, `link_board_task`/`board_links` (integración board+session) y `list_sessions`.
- `ciel.RootRunner.route(prompt, *, session_id, session_store, tenant_id)` mantiene el historial de turnos entre invocaciones (rehidrata `RootState.history`).
- `ciel.cli.root`: `ciel root route <prompt>` (offline-safe, demo con 2 specialists + root handler; opciones `--db`/`--session-id`/`--tenant` para session state persistente).
- Tests de Fase 5: 37 tests verdes (graph 6, flows 6, chat 7, root 7, session 6, root+session 5).

Verificación actual: `uv run pytest tests/` → 153 passed, 1 skipped. `uv run ciel graph demo`, `uv run ciel flow run`, `uv run ciel chat group` y `uv run ciel root route` ejecutan offline.

### Fase 6 — Agencia autónoma en bucle: ✅ Cerrada (`agent` entregado)
AutoGen/ADK: `EventLoop` durable + `AutonomousAgent` sobre `Supervisor` y `SessionStore`.

Entregado en esta sesión:
- `ciel.orchestration.agent` (AutoGen/ADK): agencia autónoma en bucle montada SOBRE `Supervisor` (cada intento de tarea hereda retry/timeout/budget) y SOBRE `SessionStore` (estado por tenant).
  - `Task`: unidad de trabajo durable (`goal`, `payload`, `status`, `attempts`, `result`, `error`) con `snapshot()`/`from_snapshot()` y `mark_running()`/`mark_succeeded()`/`mark_failed()`.
  - `EventLoop`: bucle durable con reintentos exponenciales (backoff `base_delay_s * 2^(n-1)` capped). `run(task, handler, *, run_id)` ejecuta con reintentos y persiste checkpoint tras cada intento; `resume(run_id, handler)` rehidrata desde `MemoryStore` y continúa, completando la tarea tras reinicio (criterio Fase 6). Idempotente si el checkpoint ya está `succeeded`/`failed`.
  - `EventLoopCheckpointStore`: persistencia del estado del loop sobre `MemoryStore` (clave `loop:<run_id>`, multitenancy nativo).
  - `AutonomousAgent`: orquestador de nivel superior; `run_goal(goal, handler, *, plan=None)` descompone el objetivo en tareas y las ejecuta vía `EventLoop`, persistiendo turnos de session por tenant.
- `ciel.cli.loop`: `ciel loop run <goal>` (offline-safe, handler echo local; `--run-id`/`--db`/`--tenant`/`--session-id`) y `ciel loop resume --run-id <id> --db <db>` (reanuda tras reinicio).
- Tests de Fase 6: batería verde en `tests/test_agent_fase6_test.py`.

Verificación actual: `uv run pytest tests/` → 153 + N passed, 1 skipped. `uv run ciel loop run "..." --db /tmp/l.sqlite3 --tenant t1` y `uv run ciel loop resume --run-id <id> --db /tmp/l.sqlite3` ejecutan offline.

### Fase 7 — Enterprise duro: ✅ Cerrada (`enterprise` entregado)
RBAC/OIDC, audit inmutable, cost governance, secrets, rate-limit transversal.

Entregado en esta sesión:
- `ciel.enterprise` (OFFLINE-SAFE, sin dependencias duras): paquete de enterprise duro.
  - `ciel.enterprise.rbac`: `RBACEngine` (roles admin/operator/viewer; permisos con comodín `category:*`; orden tenant>global>denegado) + `OIDCVerifier` (JWT local, `OIDC_AVAILABLE` por detección de PyJWT). Excepciones `RBACError`, `FeatureUnavailable`.
  - `ciel.enterprise.audit`: `HashChainAuditSink(JsonlAuditSink)` — audit INMUTABLE (append-only hash-chained SHA-256); `verify()` detecta alteración; `last_hash()` para encadenar.
  - `ciel.enterprise.cost`: `CostGovernor` (presupuesto por modelo/tenant, alertas y corte) — `estimate`/`record`/`spent`/`budget_of`/`remaining`/`allowed`/`check_budget` (lanza `BudgetExceededError`) / `alerted`. Capa transversal (no acopla al `Supervisor`).
  - `ciel.enterprise.secrets`: `SecretStore` con backends pluggable por prioridad — `EnvSecretBackend`, `KubernetesSecretBackend` (OFFLINE-SAFE), `VaultSecretBackend` (requiere `hvac`; degrada a `FeatureUnavailable` si falta). `get`/`require` (lanza `SecretError`).
  - `ciel.enterprise.ratelimit`: `TenantRateLimiter` — cuotas transversales por tenant/usuario con ventana deslizante en memoria; `check`/`consume` (lanza `RateLimitError`) / `reset` / `remaining`.
- `ciel rbac` / `ciel cost`: CLI offline-safe (Typer + Rich). `ciel rbac check|assign|list-roles`; `ciel cost record|status|check`.
- Tests de Fase 7: 29 tests verdes (rbac 7, audit 5, cost 6, secrets 5, ratelimit 6).

Verificación actual: `uv run pytest tests/` → 194 passed, 1 skipped. `uv run ciel rbac list-roles` y `uv run ciel cost status --tenant t1` ejecutan offline.

### Fase 8 — Deploy HA + observabilidad + madurez: ✅ Cerrada
Helm HA, OTel centralizado, adapters de canal (Teams/Discord/WebUI) y HIL en grafo, runbooks y release v0.2.0 ya entregados y verificados.

Entregado en esta sesión:
- **Helm HA**: chart `deploy/helm/ciel` con `replicaCount: 2`, `PodDisruptionBudget` (minAvailable 1), `HorizontalPodAutoscaler` (2–10 réplicas), `podAntiAffinity` y `topologySpreadConstraints`.
- **OTel centralizado** (`ciel.observability.otel`): `init_tracing(*, otlp_endpoint)` (OTLP o in-memory offline-safe), `current_tracer()`, `span_count()` (corregido para opentelemetry-sdk 1.x). Comando `ciel observe` y flag `--otel`/`--otel-endpoint` en `ciel serve`.
- **Adapters de canal** (`ciel.adapters`): `TeamsAdapter`, `DiscordAdapter`, `WebUIAdapter` + `FakeAdapter` (offline-safe).
- **Routers de gateway** (`ciel.gateway.messaging`): `create_teams_webhook_router`, `create_discord_webhook_router`, `create_webui_router`, montados en `ciel serve`.
- **Human-in-the-loop (HIL)** en `ciel.orchestration.graph`: `GraphNode.require_approval`, `GraphRunner.approve()`/`deny()` con chequeo RBAC (`approve:*`). Pausa y reanuda tras aprobación de rol autorizado.
- **Runbooks** (`docs/runbooks/`): deploy, incidente, rollback, backup de audit/board, escalado HPA.

Verificación actual (smoke): `ciel observe` confirma exporter; grafo con `require_approval` pausa y reanuda tras `approve:*`; tests formales de Fase 8 cerrados (`test_fase8_hil_otel_test.py`, `test_fase8_adapters_test.py`).

### Fase 9 — Plugin system + extensibilidad: ✅ Cerrada
Plugin system, provider Gemini, tools de fábrica, scaffold offline y corrección de bug raíz en la firma de callable de tool.

Entregado en esta sesión:
- **Plugin system** (`ciel.plugins`): `default_registry` con auto-descubrimiento vía entry points `ciel.providers`, `ciel.tools` y `ciel.agents`. Los paquetes de terceros que exponen un entry point `ciel.plugins` se registran sin editar el core.
- **GeminiProvider** añadido a `ciel.providers` builtins (modelo-agnóstico, offline-safe con echo de respaldo).
- **Tools de fábrica** (`ciel.runtime.tools_builtins`): `echo`, `datetime`, `http_get`, `file_read`, `shell` — disponibles out-of-the-box y auto-registradas.
- **`ciel init` scaffold offline**: `ciel init my-agent` genera un proyecto ejecutable sin dependencias de red.
- **Bug raíz corregido**: `ciel.runtime.ToolProvider.execute` usa ahora la firma oficial de callable — `callable_(arguments, *, tool_call_id, tenant_id) -> ToolResult | dict | Any` — alineando tools builtin, de plugin y de usuario.

Verificación actual: `uv run pytest tests/` → 230 passed, 2 skipped (cifra global de la suite tras Fase 9).

### Fase 10 — Developer Experience & API pública: ✅ Cerrada
API de alto nivel que reduce el "hola mundo" de ~141 líneas de cableado a ~15,
sin romper el low-level (se construye como fachada encima del runtime).

Entregado en esta sesión:
- **`@ciel.tool`**: decorador que infiere el JSON schema desde type hints +
  docstring (Pydantic v2); soporta `List`/`Dict`/`Optional`/`Union` y funciones
  `async`. La función decorada sigue siendo llamable como Python normal.
- **`ciel.Agent`**: entrada de alto nivel (`run` sync / `arun` async) que cablea
  provider + registro de tools + dispatcher + runtime. Conserva multi-tenancy.
- **`ciel.Context`**: inyección de dependencias (tenant/session/user) a las tools
  que lo declaren; se excluye del schema que ve el modelo.
- **`ciel.AgentResponse`**: resultado ergonómico (`.text`, `.tool_results`,
  `.tool_calls`, `.messages`, `.raw`).
- **Docs públicas** reescritas para la API nueva + cookbook (5 recetas) sobre
  Material for MkDocs con navegación por pestañas y UI mejorada.
- **Ejemplos**: `examples/quickstart_agent.py` (API nueva, ~30 líneas) +
  `examples/lowlevel_agent.py` (cableado manual para usuarios avanzados).

Verificación actual: `uv run pytest tests/` → 242 passed, 2 skipped;
`uv run mkdocs build --strict` → exit 0.

### Fase 11 — Developer Experience II: ✅ Cerrada
Continúa la fachada de alto nivel (sin cambios incompatibles en el low-level).

Entregado en esta sesión:
- **Auto-provider desde `model=`**: `ciel.Agent(model="gpt-4o-mini")` infiere el
  provider y lee la API key del entorno según el prefijo del id
  (`gpt-*`/`o1*`/`o3*` → OpenAI-compatible; `claude-*` → Anthropic;
  `gemini-*`/`models/*` → Gemini). `provider=` explícito sigue ganando.
- **Loop ReAct multi-turno** en `Agent.run()`/`arun()`: itera
  `tool_calls → resultados` hasta `finish_reason == "stop"` o `max_turns`
  (default 10). `AgentResponse.tool_results` / `.tool_calls` exponen los
  resultados y llamadas de **todos** los turnos.
- **`agent.astream(prompt)`**: async iterator sobre `runtime.stream_tokens()`
  (streaming SSE real con OpenAI/Anthropic/Gemini; texto final como chunk para
  providers offline).
- **`@ciel.tool(timeout=, retries=, middleware=)`**: opciones de ejecución sin
  romper la inferencia de schema ni el docstring.
- **`require_tenant=True`** opcional en `Agent` para enforce de tenancy desde
  día 1 (lanza `ciel.common.TenantRequired` con mensaje DX-amigable).
- **Cookbook offline** Fase 11 (`docs/cookbook/auto_provider_multiturn.md`).

Verificación actual: `uv run pytest tests/` → 254 passed, 2 skipped;
`uv run mkdocs build --strict` → exit 0; `examples/quickstart_agent.py` y
`examples/lowlevel_agent.py` → exit 0.

### Fase 12 — Autonomía I: Skill Library: ✅ Cerrada
El agente **crea, verifica, versiona y enseña** sus propios skills (offline-safe).

Entregado en esta sesión:
- **`ciel.runtime.skills_lib`**: `SkillLibrary` (store escribible sobre el
  registry pasivo: `create_from_code`, `register`, `get`, `list_skills`,
  `history`, `update` con bump semántico, `remove`) y `SkillVerifier`
  (verificación offline: sintaxis + casos de prueba `{"call", "expect"}`).
- **`ciel.runtime.skill_versioning`**: `set_changelog` / `changelog` y
  `evolution_tree` (semilla del Skill Evolution Tree, lineage por versión).
- **`ciel.runtime.skill_composition`**: `SkillComposition.compose` fusiona N
  skills con combinadores `sequence` / `parallel` / `selector`.
- **`ciel.runtime.skill_doc`**: `generate_doc` y `to_markdown` (doc desde AST).
- **`ciel.runtime.skill_agent_integration`**: `@ciel.skill`,
  `global_skill_library` (singleton), `Agent(skills=[...])`, `agent.teach(...)`
  / `ciel.teach(agent, skill)` y `agent.load_skills(...)`.
- **`ciel.runtime.skill_metrics`**: `SkillMetrics` por `tenant_id` (llamadas,
  éxitos/fallos, tasa de éxito, latencia promedio).
- **`ciel skills`** (CLI offline): `list`, `create --name --description
  --code-file`, `verify --name --test-cases`, `remove --name`.



Ciel está diseñado para extenderse sin tocar el core:

- **Plugins**: instala cualquier paquete que exponga un entry point `ciel.plugins` (grupos `ciel.providers` / `ciel.tools` / `ciel.agents`) y Ciel lo auto-descubre vía `ciel.plugins.default_registry`. Ver [`docs/guide/plugins.md`](docs/guide/plugins.md).
- **Tools propias**: implementa la firma oficial de tool callable — `callable_(arguments, *, tool_call_id, tenant_id) -> ToolResult | dict | Any` — usada por `ciel.runtime.ToolProvider.execute` (builtins, plugins y tools de usuario comparten la misma firma). Ver [`docs/guide/tools.md`](docs/guide/tools.md).

## License

- Core framework: **AGPL-3.0-or-later**
- Commercial dual license available for regulated deployments.

## Documentación

La documentación oficial (MkDocs Material) se publica en GitHub Pages:

- **Sitio completo**: https://ander-labs.github.io/ciel-agent-framework/
- **Guía rápida**: https://ander-labs.github.io/ciel-agent-framework/quickstart/
- **Conceptos**: https://ander-labs.github.io/ciel-agent-framework/concepts/
- **Runbooks**: https://github.com/Ander-Labs/ciel-agent-framework/tree/master/docs/runbooks
- **Referencia API**: https://ander-labs.github.io/ciel-agent-framework/
