Civitas

Civitas는 협상, 증거 계보 분석, 적응형 재계획, 결정론적 최적화, 보호된 MCP 실행을 결합한 자율 멀티 에이전트 식품 조달 시스템입니다. 대상 제품 인터페이스는 Codex 호환 MCP 서버입니다. 운영자는 대화형으로 조달 목표를 진술하고, Codex는 Civitas의 의도 수준 도구를 호출하며, Civitas는 전체 계획 및 안전 워크플로를 소유합니다.

전문화된 Parliament 에이전트는 경쟁 목표를 조사하고 솔버가 생성한 조달 대안을 비교합니다. 그런 다음 evidence-aware Jury는 조치가 실행 안전 경계를 통과하기 전에 출처(provenance), 진정한 소스 독립성, 모순, 적대적 반대 의견을 평가합니다.

React 애플리케이션은 제품의 기본 진입점이 아니라 선택적 읽기 전용 증거 및 실행 감사 뷰어입니다. 이 저장소에는 엄격한 인바운드 MCP 계약, 전송 중립 조달 퍼사드, 결정론적 통합 스위트, 뷰어 기반 false-consensus 데모가 포함되어 있습니다. 이러한 구성 요소를 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

Vite 개발 서버는 /api 요청을 http://127.0.0.1:8001로 프록시합니다.

civitas.api.app:create_app은 로컬 시뮬레이션 데모 API입니다. 실제 공급자를 사용하지 않으며 실제 조달 부작용을 수행하지 않습니다. 루프백에 바인딩된 상태를 유지하십시오. civitas.api.guarded_api의 영속성 기반 API 팩토리는 배포로 구성될 때 최소 32자의 베어러 토큰과 조직 바인딩을 요구합니다.

데모

현재 엔드투엔드 통합 데모는 false-consensus 사례 파일입니다. 공유된 오래된 증거로 공급업체 A가 승리하는 것으로 시작하여, clean-room Dissent 검사를 거치고, 계획을 다시 열고, 새로운 공개 증거 후 공급업체 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