Civitas

Civitas es un sistema autónomo multiagente de aprovisionamiento de alimentos que combina negociación, análisis de linaje de evidencia, replanificación adaptativa, optimización determinista y ejecución MCP protegida. Su interfaz de producto objetivo es un servidor MCP compatible con Codex: los operadores expresan conversacionalmente un objetivo de aprovisionamiento, Codex invoca las herramientas a nivel de intención de Civitas, y Civitas controla todo el flujo de planificación y seguridad.

Los agentes especializados de Parliament investigan objetivos en conflicto y comparan las alternativas de aprovisionamiento generadas por el solucionador. Un Jury consciente de la evidencia evalúa entonces la procedencia, la independencia real de las fuentes, las contradicciones y el disentimiento adversarial antes de que una acción pueda cruzar el límite de seguridad de ejecución.

La aplicación React es un visor opcional, de solo lectura, de evidencia y auditoría de ejecución, más que el punto de entrada principal del producto. El repositorio incluye contratos MCP entrantes estrictos, la fachada de aprovisionamiento independiente del transporte, una suite de integración determinista y la demostración de falso consenso basada en el visor. La composición de despliegue que conecta esas piezas a PostgreSQL, un trabajador persistente y proveedores de aprovisionamiento reales sigue siendo específica del entorno. Véase MCP_INTERFACE.md, MCP_AGENT_WORKPLAN.md, PLAN.md, AGENTS.md, TECH_STACK.md y SECURITY.md.

Product interface

El despliegue previsto tiene MCP en ambos lados de la aplicación:

Operator → Codex → Civitas MCP server → planning / Jury / execution services
                                      → procurement-provider MCP servers

Codex es responsable de la conversación, la captura de intenciones, la narración del progreso y la presentación de solicitudes de aprobación. Civitas sigue siendo la autoridad para las entradas tipadas, la recuperación de evidencia, la optimización, Parliament, Jury y Dissent, la replanificación, la revalidación de frescura, el vinculado de aprobaciones, la idempotencia y la auditoría de ejecución. Un modelo o mensaje de chat no puede eludir esos controles.

La interacción principal debería ser tan pequeña como:

User: Protect seven days of demand across our warehouses while minimizing waste.
Codex: Civitas found false consensus on a stale lead-time source and replanned.
       The revised plan has Integrity 92/100 and all hard gates pass.
       Approve the exact plan for execution?

Related MCP server: mendicant-mcp-server

Development

Requisitos previos: Python 3.12, uv, Node.js 24, pnpm 10.31.0 y Docker Compose.

uv sync --frozen --all-groups
pnpm install --frozen-lockfile
docker compose up -d postgres
uv run alembic upgrade head

PostgreSQL escucha en el puerto 55432 por defecto para evitar chocar con una instalación local. Establece CIVITAS_POSTGRES_PORT para modificarlo.

Ejecuta las comprobaciones requeridas con:

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
pnpm format
pnpm lint
pnpm typecheck
pnpm build

Ejecuta la API de demostración actual y el visor de auditoría opcional localmente con:

uv run uvicorn civitas.api.app:create_app --factory --host 127.0.0.1 --port 8001
pnpm --filter @civitas/web dev

El servidor de desarrollo de Vite hace de proxy de las solicitudes /api hacia http://127.0.0.1:8001.

civitas.api.app:create_app es la API de demostración local simulada. No utiliza ningún proveedor en vivo y no realiza efectos secundarios reales de aprovisionamiento. Mantenla vinculada a loopback. La fábrica de API respaldada por persistencia en civitas.api.guarded_api requiere un token de portador de al menos 32 caracteres y una vinculación de organización cuando es compuesta por un despliegue.

Demo

La demo de integración de extremo a extremo actual es un expediente de caso de falso consenso. Comienza con el proveedor A ganando sobre evidencia compartida obsoleta, pasa por una comprobación de Dissent en sala limpia, reabre la planificación, aprueba al proveedor B después de evidencia pública fresca, y luego realiza la revalidación de frescura y la ejecución MCP protegida contra duplicados.

Ejecuta la suite dorada con:

uv run pytest tests/golden/test_scenarios.py -q

Ejecuta las comprobaciones centradas en la integración con:

uv run pytest tests/integration/test_demo_api.py tests/unit/execution/test_service.py tests/contract/test_mcp_integration.py -q

Para la demostración del visor sin conexión, abre http://127.0.0.1:5173, elige False consensus with clean-room dissent y comienza la ejecución. El flujo SSE se produce mientras el escenario se ejecuta. El registro de eventos debería mostrar esta secuencia:

evidence retrieval
→ Parliament proposal / challenge / concession
→ Jury investigate
→ clean-room Dissent evidence
→ replanning
→ Jury approve
→ freshness revalidation
→ execution succeeded
→ duplicate execution downgraded to duplicate