Civitas

Civitas — это автономная мультиагентная система закупок продуктов питания, объединяющая переговоры, анализ происхождения доказательств, адаптивное перепланирование, детерминированную оптимизацию и защищённое исполнение MCP. Её целевой продуктовый интерфейс — это MCP-сервер, совместимый с Codex: операторы формулируют цель закупки в разговорной форме, Codex вызывает инструменты уровня намерений Civitas, а Civitas полностью контролирует весь процесс планирования и безопасности.

Специализированные агенты Parliament исследуют конкурирующие цели и сравнивают сгенерированные солвером альтернативы закупок. Затем учитывающее доказательства Jury оценивает происхождение, подлинную независимость источников, противоречия и состязательное инакомыслие, прежде чем действие сможет пересечь границу безопасности исполнения.

React-приложение — это опциональное, доступное только для чтения средство просмотра доказательств и аудита исполнения, а не основная точка входа в продукт. Репозиторий включает строгие входящие MCP-контракты, транспортно-нейтральный фасад закупок, детерминированный интеграционный набор тестов и демонстрацию ложного консенсуса на основе просмотрщика. Композиция развертывания, соединяющая эти части с PostgreSQL, устойчивым воркером и реальными поставщиками закупок, остаётся специфичной для окружения. См. MCP_INTERFACE.md, MCP_AGENT_WORKPLAN.md, PLAN.md, AGENTS.md, TECH_STACK.md и SECURITY.md.

Интерфейс продукта

Целевое развертывание предусматривает MCP с обеих сторон приложения:

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

Codex отвечает за диалог, захват намерений, описание хода выполнения и представление запросов на утверждение. Civitas остаётся авторитетом в отношении типизированных входных данных, поиска доказательств, оптимизации, Parliament, Jury и Dissent, перепланирования, повторной проверки свежести, привязки утверждений, идемпотентности и аудита исполнения. Ни модель, ни сообщение чата не могут обойти эти механизмы контроля.

Основное взаимодействие должно быть минимальным:

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

Разработка

Предварительные требования: Python 3.12, uv, Node.js 24, pnpm 10.31.0 и Docker Compose.

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

PostgreSQL по умолчанию слушает порт 55432, чтобы избежать конфликта с локальной установкой. Чтобы переопределить его, задайте CIVITAS_POSTGRES_PORT.

Запустите требуемые проверки с помощью:

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

Запустите текущий демонстрационный API и опциональное средство просмотра аудита локально с помощью:

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

Dev-сервер Vite проксирует запросы /api на http://127.0.0.1:8001.

civitas.api.app:create_app — это локальный симулируемый демонстрационный API. Он не использует реального провайдера и не выполняет реальных побочных эффектов закупок. Держите его привязанным к loopback. Фабрика API с поддержкой постоянного хранения в civitas.api.guarded_api требует bearer-токен длиной не менее 32 символов и привязку к организации, когда она компонуется развертыванием.

Демо

Текущая сквозная интеграционная демонстрация — это кейс ложного консенсуса. Он начинается с победы поставщика A на основе общих устаревших доказательств, проходит через проверку Dissent в чистой комнате (clean-room), переоткрывает планирование, утверждает поставщика B после свежих публичных доказательств, затем выполняет повторную проверку свежести и защищённое от дублирования исполнение MCP.

Запустите эталонный набор тестов с помощью:

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

Запустите проверки, ориентированные на интеграцию, с помощью:

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

Для автономной демонстрации просмотрщика откройте http://127.0.0.1:5173, выберите False consensus with clean-room dissent и запустите выполнение. Поток SSE генерируется во время выполнения сценария. Журнал событий должен показать следующую последовательность:

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