Metadata-Version: 2.5
Name: horcon
Version: 0.8.2a1
Summary: Horcón: framework que genera y valida sistemas multiagente deterministas. Perfil MILPA: library.
Project-URL: Homepage, https://codeberg.org/kasailabs/horcon
Project-URL: Documentation, https://codeberg.org/kasailabs/horcon/src/branch/main/docs/INDEX.md
Project-URL: Repository, https://codeberg.org/kasailabs/horcon
Project-URL: Changelog, https://codeberg.org/kasailabs/horcon/src/branch/main/CHANGELOG.md
Project-URL: Issues, https://codeberg.org/kasailabs/horcon/issues
Author: Kasai Labs
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-system,governance,human-in-the-loop,multi-agent,policy-engine,scaffold
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: jsonschema>=4.20
Requires-Dist: pyyaml>=6.0
Provides-Extra: api
Requires-Dist: fastapi<1,>=0.115; extra == 'api'
Requires-Dist: httpx>=0.27; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'api'
Provides-Extra: asilo
Requires-Dist: asilo-core<0.2,>=0.1.0a1; extra == 'asilo'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material==9.7.7; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
Provides-Extra: milpa
Requires-Dist: milpa-sdk<0.2,>=0.1.0a1; extra == 'milpa'
Provides-Extra: runtime
Requires-Dist: httpx>=0.27; extra == 'runtime'
Description-Content-Type: text/markdown

<!-- Generado con asistencia de IA (Claude Code, 2026-09-22); revisado por: pendiente -->
# Horcón

**Un modelo de lenguaje no debe decidir solo sobre las cosas que importan. Horcón monta, alrededor
de él, un despacho con reglas fijas y una persona que firma antes de que algo salga.**

## La analogía

Piensa en un despacho de traducción. Un traductor junior propone una versión; un traductor senior
la revisa; una recepcionista con una lista fija de reglas ("¿el cliente pagó?", "¿el documento
está completo?") decide si pasa al siguiente paso; y si el documento es un contrato importante,
alguien con firma lo revisa antes de entregarlo. Nadie espera que el traductor junior sea infalible
— el despacho está diseñado para que un error suyo no llegue solo al cliente.

Horcón es ese despacho, hecho de código: el traductor junior es un **especialista** (un modelo de
lenguaje con una ficha que dice qué puede y qué no puede hacer), la recepcionista es la **aduana**
(reglas deterministas, no otro modelo opinando), y la firma final es una **persona identificable**,
nunca automática cuando el riesgo es alto.

## Para quién es

- **Si no programas:** una consola con pantallas y botones (proyectos → equipo → encargos). No
  necesitas escribir un comando. Empieza en [Parte 0 · Empieza aquí](docs/00-inicio-rapido/README.md).
- **Si programas poco:** una terminal con comandos que se copian y pegan, y archivos de texto que
  se leen sin herramientas especiales. Sigue por [Parte III · Hacer](docs/03-operacion/README.md).
- **Si vas a auditar:** cada decisión queda en un expediente con firmas encadenadas
  (`receipts.jsonl`) y cada regla tiene su contrato técnico y su prueba. Empieza en
  [Parte IV · Referencia](docs/04-contratos/README.md).

## Instalación

Requiere Python 3.11 o mayor. Horcón todavía no está publicado en PyPI (ver "Estado de madurez"
abajo); mientras tanto, se instala desde el propio repositorio:

```bash
git clone https://codeberg.org/kasailabs/horcon.git
cd horcon
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m horcon doctor
```

### Integración local de ASILO y MILPA

Antes de publicar cualquiera de los tres paquetes, puedes construir los artefactos locales e
instalarlos en una venv limpia con la prueba de aceptación incluida:

```bash
scripts/instalar-local.sh --recreate
```

El instalador construye wheel y sdist de `asilo-core`, `milpa-sdk` y `horcon`; instala los tres
wheels desde `horcon/tmp/local-dist` con `--no-index`; resuelve únicamente dependencias de
terceros; y ejecuta `init`, `validate`, `agent add`, `doctor`, el loader real de MILPA y
`asilo.enforce_schema` sobre un proyecto generado. La venv queda en `horcon/tmp/local-venv` y el
proyecto de integración se conserva en `horcon/tmp/horcon-local-integration-*` si hay un error. No llama
a PyPI para los paquetes del ecosistema ni publica nada. En Windows usa
`scripts/instalar-local.ps1 --recreate`.

The canonical installer options are `--recreate` and `--skip-acceptance`; the previous Spanish
spellings remain accepted as hidden compatibility aliases.

For simultaneous development of all three repositories, use `--editable --recreate`. This creates
`horcon/tmp/editable-venv` and installs `asilo-core`, `milpa-sdk`, and `horcon` with `pip install -e`:

```bash
scripts/instalar-local.sh --editable --recreate
```

Changes made in any of the three source repositories are then used immediately by that venv. Use
the default command without `--editable` before publishing to verify the packaged artifacts.

El comando falla a propósito si MILPA no puede leer el manifest generado: ese resultado es un
bloqueo de compatibilidad que hay que resolver antes de publicar, no una razón para continuar con
`--skip-acceptance`. Esta última opción sólo sirve para inspeccionar los artefactos y la instalación
cuando se está trabajando en ese bloqueo.

## Un ejemplo mínimo, ejecutado de verdad

Esta es la salida real de dos comandos, copiada de una corrida el 22 de septiembre de 2026 contra
la versión 0.8.0 (sin editar, salvo acortar la ruta a `mi-proyecto`):

```text
$ horcon init mi-proyecto --project-name mi-proyecto --toca-salud no --toca-crisis no --toca-menores no
init escrito: mi-proyecto (perfil P2, 63 archivos)
template_digest=328fb598287d2f935b2fc549ce10a0f19dea6b19e87599ca16b8b4075515ca10
generation-receipt.json=mi-proyecto/generation-receipt.json
validación estructural: no es evidencia de comportamiento

$ horcon doctor
milpa: implementado
asilo: stub
docker: implementado
python: 3.14.5
proveedor de modelos: no configurado (HORCON_MODEL_BASE_URL no, HORCON_MODEL_API_KEY ausente, HORCON_MODEL_NAME no)
{"python": "3.14.5", "milpa": "implementado", "asilo": "stub", "docker": "implementado", "proveedor": "no configurado"}
```

Las tres preguntas `--toca-salud/--toca-crisis/--toca-menores` son obligatorias: `init` se niega
antes de escribir nada si falta alguna (decisión H-1 del fundador, `DECISIONES-CERRADAS.md`). La
última línea de `init` se imprime siempre: que la estructura generada esté bien no dice nada de
cómo se comporta un especialista dentro de ella.

El tutorial completo — crear dos especialistas, darlos de alta con firma, pedir un encargo, pasarlo
por la aduana y cerrarlo — está en
[`docs/00-inicio-rapido/03-tu-primer-proyecto.md`](docs/00-inicio-rapido/03-tu-primer-proyecto.md):
quince minutos, reejecutado de verdad el 22 de septiembre de 2026, con la salida real de cada paso.

## Qué hace hoy

- Genera un proyecto multiagente completo (`horcon init`) a partir de una plantilla versionada,
  con manifiestos, políticas, máquina de estados y expediente de gobernanza.
- Da de alta especialistas con firma (`agent register`), corre encargos en **simulación**
  determinista sin red (`run --provider fake`), y también contra un proveedor de modelos real bajo
  interfaz compatible con OpenAI (`run --provider openai_compatible`, con dos consentimientos
  explícitos y tope de gasto).
- Hace pasar cada propuesta por una aduana de doce políticas con reglas fijas (`gate`), nunca por
  otro modelo opinando.
- Firma decisiones con Ed25519 en una cadena de hashes append-only (`receipt`, `adr sign`), con una
  escalera de custodia de la llave (`keys init --custody`) de nivel gratis (archivo sin cifrar)
  hasta nivel que aísla al asistente de código de la llave (usuario aparte del sistema).
- Trae un botón de paro con receipt firmado (`kill`/`resume`), un contador de gasto encadenado
  (`charge`), una consola web para quien no programa, y un exportador de trazas a OTLP/HTTP sin
  datos personales.

## Qué NO hace hoy

La lista completa, honesta y con lo que falta por decisión pendiente está en
[`docs/03-operacion/10-que-no-esta-implementado.md`](docs/03-operacion/10-que-no-esta-implementado.md).
En resumen:

- **Ninguna corrida con un proveedor de modelos real está registrada todavía** en este repositorio;
  todo lo verificado en la suite de pruebas usa `--provider fake`.
- **No limpia datos personales.** Los detecta con tres expresiones regulares (correo, CURP,
  teléfono) y los manda a revisión humana; no los redacta ni los borra.
- **No orquesta con CrewAI ni LangGraph.** Hay un adaptador de CrewAI que construye Agentes y
  Tareas, pero nunca llama `kickoff()`; el orquestador de equipo (`team run`) es código propio,
  no un framework de terceros envuelto.
- **No es una frontera de seguridad completa.** Qué protege la aduana, qué protege el padrón, qué
  protege la custodia de la llave, y qué no protege ninguna de las tres, está explicado en llano en
  [`docs/04-contratos/11-fronteras-de-confianza.md`](docs/04-contratos/11-fronteras-de-confianza.md).
- **No declara conformidad con ningún estándar** ni se llama a sí mismo "seguro" o "certificado":
  ver [`docs/01-manifiesto/03-que-no-hace.md`](docs/01-manifiesto/03-que-no-hace.md).

## Estado de madurez

Versión 0.8.0. **Integrado en local y operable en simulación** (proveedor `fake`): 480 pruebas
en verde, `validate`, `audit-docs` y `docs build` limpios, cadena completa de comandos ejercitada a
mano. **Ninguna corrida con un proveedor de modelos real está registrada** en este repositorio;
nada aquí afirma que el sistema cumpla un estándar, sea seguro o esté certificado. Detalle completo
por versión en [`CHANGELOG.md`](CHANGELOG.md).

## Licencia

Apache License 2.0 ([`LICENSE`](LICENSE)). "Horcón" es un nombre en verificación de marca, sin
búsqueda de anterioridades resuelta todavía ([`NOTICE`](NOTICE)).

## Enlaces

| Qué | Dónde |
|---|---|
| Documentación (el libro completo) | [`docs/INDEX.md`](docs/INDEX.md) |
| Código fuente | https://codeberg.org/kasailabs/horcon |
| Registro de cambios | [`CHANGELOG.md`](CHANGELOG.md) |
| Incidencias | https://codeberg.org/kasailabs/horcon/issues |
| Contrato para agentes de código | [`AGENTS.md`](AGENTS.md) |
| Gobernanza y decisiones firmadas (ADR) | [`governance/README.md`](governance/README.md) |

Perfil MILPA `library` ([`.milpa-manifest.json`](.milpa-manifest.json)).
