Civitas

Civitas ist ein autonomes Multi-Agenten-System zur Lebensmittelbeschaffung, das Verhandlung, Evidenz-Herkunftsanalyse, adaptive Neuplanung, deterministische Optimierung und abgesicherte MCP-Ausführung kombiniert. Die angestrebte Produktschnittstelle ist ein Codex-kompatibler MCP-Server: Operatoren formulieren ein Beschaffungsziel in natürlicher Sprache, Codex ruft die Werkzeuge auf Absichtsebene von Civitas auf, und Civitas übernimmt den vollständigen Planungs- und Sicherheitsworkflow.

Spezialisierte Parliament-Agenten untersuchen konkurrierende Ziele und vergleichen die vom Solver erzeugten Beschaffungsalternativen. Eine evidenzbewusste Jury bewertet anschließend Herkunft, echte Quellenunabhängigkeit, Widersprüche und gegnerischen Dissens, bevor eine Aktion die Sicherheitsgrenze der Ausführung passieren kann.

Die React-Anwendung ist ein optionaler, schreibgeschützter Betrachter für Evidenz- und Ausführungsaudits und nicht der primäre Einstiegspunkt des Produkts. Das Repository enthält strenge eingehende MCP-Verträge, die transportneutrale Beschaffungsfassade, eine deterministische Integrationssuite und die betrachterbasierte False-Consensus-Demonstration. Die Bereitstellungskomposition, die diese Bausteine mit PostgreSQL, einem dauerhaften Worker und echten Beschaffungsanbietern verbindet, bleibt umgebungsspezifisch. Siehe MCP_INTERFACE.md, MCP_AGENT_WORKPLAN.md, PLAN.md, AGENTS.md, TECH_STACK.md und SECURITY.md.

Produktschnittstelle

Die beabsichtigte Bereitstellung hat MCP auf beiden Seiten der Anwendung:

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

Codex ist verantwortlich für Konversation, Absichtserfassung, Fortschrittsberichterstattung und die Präsentation von Genehmigungsanfragen. Civitas bleibt maßgeblich für typisierte Eingaben, Evidenzabruf, Optimierung, Parliament, Jury und Dissent, Neuplanung, Frische-Revalidierung, Genehmigungsbindung, Idempotenz und Ausführungsprüfung. Eine Modell- oder Chatnachricht kann diese Kontrollen nicht umgehen.

Die primäre Interaktion sollte so klein wie möglich sein:

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

Entwicklung

Voraussetzungen: Python 3.12, uv, Node.js 24, pnpm 10.31.0 und Docker Compose.

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

PostgreSQL hört standardmäßig auf Port 55432, um eine Kollision mit einer lokalen Installation zu vermeiden. Setzen Sie CIVITAS_POSTGRES_PORT, um diesen zu überschreiben.

Führen Sie die erforderlichen Prüfungen wie folgt aus:

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

Führen Sie die aktuelle Demonstrations-API und den optionalen Audit-Betrachter lokal wie folgt aus:

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

Der Vite-Entwicklungsserver leitet /api-Anfragen an http://127.0.0.1:8001 weiter.

civitas.api.app:create_app ist die lokale, simulierte Demonstrations-API. Sie verwendet keinen Live-Anbieter und verursacht keine echten Beschaffungsnebenwirkungen. Halten Sie sie an Loopback gebunden. Die persistenzgestützte API-Factory in civitas.api.guarded_api erfordert ein Bearer-Token von mindestens 32 Zeichen und eine Organisationsbindung, wenn sie durch eine Bereitstellung zusammengesetzt wird.

Demo

Die aktuelle End-to-End-Integrationsdemo ist eine False-Consensus-Fallakte. Sie beginnt damit, dass Anbieter A auf der Grundlage gemeinsamer veralteter Evidenz gewinnt, durchläuft eine Clean-Room-Dissent-Prüfung, öffnet die Planung erneut, genehmigt Anbieter B nach frischer öffentlicher Evidenz und führt anschließend eine Frische-Revalidierung und eine vor Duplikaten geschützte MCP-Ausführung durch.

Führen Sie die Golden-Suite wie folgt aus:

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

Führen Sie die integrationsorientierten Prüfungen wie folgt aus:

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

Für die Offline-Betrachterdemonstration öffnen Sie http://127.0.0.1:5173, wählen Sie False consensus with clean-room dissent und starten Sie den Lauf. Der SSE-Stream wird erzeugt, während das Szenario ausgeführt wird. Die Ereignisliste sollte diese Abfolge zeigen:

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