WEIPING_COUNCIL - Multi-LLM deliberation system with 6 protocols: co

项目说明

WEIPING_COUNCIL

!WEIPING_COUNCIL banner

Honest multi-model deliberation for local and OpenAI-compatible runtimes.

WEIPING_COUNCIL is the repository identity for Weiping Council. It asks several configured council members to reason through a question, then preserves the route, model e, dissent, timings, warnings, and degraded runtime state. The goal is not to make a chatbot look more confident. The goal is to make deliberation inspectable enough that you can tell when it worked, when it was partial, and why.

Compatibility note: this project was pre published as Vipin Council (). The legacy vc.py CLI and vc console script remain supported while the public repository identity moves to WEIPING_COUNCIL.

Agents maintaining this repository should read AGENTS.md, this README, CLAUDE.md, and .codex/skills/weiping-council/SKILL.md before non-trivial work.

What Changed in v2.4.1

v2.4.1 is the release-hardening update for the v2.4 protocol runtime:

every real protocol result now satisfies the persisted session schema, including

structured council peer-review records;

the browser and CLI expose protocol-specific stage e instead of hiding

debate, red-team, specialist, tournament, and council fields;

default OpenRouter model IDs use pro slugs while an empty

OPENROUTER_MODEL keeps the role-specific defaults;

the public release guard covers common provider tokens, private credential files, and

alternati lockfiles that could o the audited npm lock.

What Changed in v2.4

v2.4 is the protocol-fidelity and resilient-runtime release:

named protocols now execute exactly as selected; smart routing can no longer silently

replace debate, redteam, consensus, specialist, tournament, or council;

the new auto mode owns cost-aware fast/standard/full-council routing and optional

task decomposition;

every result stores a separate, redacted routing record with the requested protocol,

selected path, assigned members, reason, and difficulty;

provider retries are bounded and error-aware: transient failures retry, while

authentication, in, and schema failures stop immediately;

recalled context is passed as untrusted user-le material instead of being

appended to model system instructions;

session JSON uses atomic replacement, malformed artifacts are skipped safely, request

sizes are bounded, and li is separated from strict readiness.

v2.3 established the honest-runtime foundation that v2.4 retains:

provider credentials are en, loaded from the process en or the

exact project-root .env (parent directories are ne);

council member identity is separate from provider model identity, so six roles no longer collapse into one map key;

each query gets session-scoped model traces, including concurrent requests;

/api/health, CLI status, and the React UI expose redacted readiness instead of raw provider endpoints;

missing provider config, provider errors, and una agentmemory recall are explicit degraded states;

default CORS is local-first through , not wildcard;

the project includes a Codex skill at .codex/skills/weiping-council/SKILL.md for future reproduction, maintenance, monitoring, releases, and upgrade passes.

Why It Exists

Single-model answers often hide the uncertainty that matters most. Weiping Council gives you several structured ways to ask for disagreement, review, synthesis, and :

| Protocol | Best For | Shape |
| --- | --- | --- |
| auto | cost-aware general use | inspectable routing to one model, decomposition, or council |
| council | open-ended questions, research, design review | first opinions, peer review, chairman synthesis |
| debate | trade-offs and contentious choices | pro, con, rebuttal, judge |
| redteam | finding weaknesses | defenders, attacker critique, impro |
| consensus | alignment and policy choices | repeated rounds until enough members agree |
| specialist | domain routing | classify, specialist answer, checks |
| tournament | choosing the strongest answer | bracketed comparisons and winner |

Architecture

Core files:

backend/runtime.py - .env/en loading, provider readiness, CORS origins, trace dataclasses.

backend/pro/router.py - provider calls, retry/degraded handling, context-local trace collection.

backend/council/orchestrator.py - run pipeline, timings, context recall, degraded semantics.

backend/main.py - FastAPI API, health, models, session persistence.

backend/session_store.py - atomic session writes and corruption-tolerant indexes.

vc.py - terminal interface.

frontend/src/components/ResultView.jsx - runtime e in the UI.

Installation

Prerequisites:

Python 3.11+

Node.js 22.18+

an OpenAI-compatible provider key such as OpenRouter, or role-specific provider credentials

Run e:

start.cmd resol path from the checkout, uses the project's .venv, and fails
with installation guidance when the en, npm, or frontend/node_modules
is missing. Set =1 to inspect the resol without copying
.env or opening terminal windows.

Manual run:

The CLI keeps the acti encoding and escapes only glyphs that encoding cannot
represent. This prevents UnicodeEncodeError crashes on legacy Windows code pages such as
GBK while preserving full Unicode output in UTF-8 terminals. Model, session, health, and
memory text is stripped of ANSI/OSC and unsafe control characters before terminal rendering.

Configuration

Minimal .env:

Only OPENROUTER_API_KEY is required for the default six-role council. The bulk-worker
inherits the shared OpenRouter endpoint unless a non-empty DEEPSEEK_API_KEY enables the
optional DeepSeek o. A partial <ROLE>_* block o only its
non-empty fields and inherits the remaining shared endpoint fields.

Per-role o use this pattern:

Replace ARCHITECT with COORDINATOR, IMPLEMENTER, RE, SPEEDSTER, or BULK_WORKER for other council roles.

Public health and session e intentionally do not expose raw provider URLs or API keys. They expose only source labels, configured/missing fields, provider model names, attempts, latency, and error classes.

Named protocols are authoritati auto only when you want the runtime to select
a single-model, decomposition, or full-council path based on query complexity.
Set AGENTMEMORY_URL= explicitly to disable optional recall; a disabled memory service is
reported as not configured and does not by itself degrade a run.

Relationship to Neighbor Projects

WEIPING_COUNCIL, deepseek-cli, WEIPING_LAB, WEIPING_WIKI, AGENT_RESOURCE, and AGENTIC_SCIENCE should complement each other without becoming tightly coupled:

WEIPING_COUNCIL is the deliberation runtime. It owns protocols, routing e, degraded-state semantics, sa JSON, and the React/CLI interface for council-style reasoning.

deepseek-cli is a terminal-first DeepSeek client. It can provide a con way to test DeepSeek credentials and workflows, but Weiping Council must remain pro through OpenAI-compatible and per-role provider settings.

WEIPING_LAB is the broader lab/workbench layer. It can consume Weiping Council session artifacts, but lab-specific state should not be required to run this repository.

WEIPING_WIKI is the public route map and durable operating context, not a runtime dependency.

AGENT_RESOURCE provides shared skills and workflow references; do not copy its caches, local clones, or private notes into this repo.

AGENTIC_SCIENCE provides optional audit methods such as UUPF for workflow upgrades. Generated UUPF reports are planning e only and must stay in ignored work areas unless deliberately released.

Historical compatibility: older local checkouts, session artifacts, or notes may still mention , , or Vipin Council. Treat those names as legacy aliases unless a document explicitly describes historical release context.

The only shared memory dependency in this repo is optional agentmemory recall via
AGENTMEMORY_URL. When the service requires authentication, set AGENTMEMORY_SECRET;
the credential is sent as Bearer auth only to HTTPS or loopback URLs and is never
included in public health/session output. Anonymous agentmemory instances remain supported.

What Good Looks Like

After setup:

Healthy output means:

backend reachable;

at least the configured pro are ready;

agentmemory is reachable if AGENTMEMORY_URL is set;

status is ok.

Degraded output is still useful. It means the backend is alive but one subsystem is partial. Common examples:

no provider key: queries return explicit una text rather than fake model answers;

agentmemory down: answers run without recalled context and mark the session degraded;

provider schema or HTTP failure: the answer includes a provider failure marker and the trace stores the error class.

REST API

Submit a query:

Response shape:

Other endpoints:

| Method | Endpoint | Purpose |
| --- | --- | --- |
| GET | /api/live | process li only |
| GET | /api/health | redacted backend, provider, and memory readiness |
| GET | /api/ready | strict readiness; returns 503 when dependencies are degraded |
| GET | /api/models | council member IDs, roles, and provider model names |
| GET | /api/protocols | a protocol list |
| GET | /api/sessions | recent sa |
| GET | /api/sessions/{id} | sa JSON |

Session Artifact Contract

Sa handoffs li data/sessions/<uuid>.json. The directory is runtime state and should stay out of maintenance commits unless the user explicitly asks to curate a public example.

Each sa JSON should preserve:

id, query, protocol, and created_at

stages, final_answer, confidence, dissent, and audit_trail

routing with the requested protocol and selected execution path

metrics with timing fields

pro with redacted readiness only

model_call_traces with role, model name/id, attempts, latency, and error class

degraded and warnings

Lab and wiki workflows may point to these files as artifacts, but they should not require Council's .env, acti, frontend build output, local caches, or private provider logs.

Monitoring

Use four levels, inspired by current open-source AI runtime practice:

1. Basic process check:

The backend process is reachable if this returns status: ok.

2. Diagnostic and strict readiness checks:

/api/health always returns the diagnostic snapshot. /api/ready returns 503 when
that snapshot is degraded.

3. Configuration check:

Confirm member IDs and provider models are what you expect.

4. End-to-end check:

Treat this as passing only when degraded is false and at least one trace has error_kind: null.

Troubleshooting

| Symptom | Meaning | Fix |
| --- | --- | --- |
| Backend not reachable in the UI | Vite can load, but FastAPI is not responding | Start .\.ven\python.exe -m u backend.main:app --reload --port 8000 |
| /api/health returns status: degraded | Backend is alive, but a provider or memory dependency is incomplete | Inspect warnings, pro[].missing, and agentmemory.status |
| /api/ready returns 503 while /api/live returns 200 | The process is alive but dependencies are incomplete | Use /api/health for the redacted diagnostic snapshot |
| A named protocol appears expensive | Named protocols deliberately preser full workflow | Select auto when cost-aware routing is desired |
| Query returns [Name una: missing provider configuration (...)] | The selected role has no usable provider endpoint or key | Fill .env or the relevant <ROLE>_* |
| Query returns provider call failed (schema_error) | Provider responded, but not in the expected schema | Check *_API_FORMAT, provider compatibility, and provider logs |
| CLI status is degraded but UI works | This is a partial runtime, not downtime | Use the Runtime E panel to see which dependency is partial |
| Tests try to use real keys | A test is not hermetic | Prefer RuntimeSettings.from_en, env={}) or pass an explicit temporary doten in the test |

De Gate

The repository includes .github/workflows/ci.yml with the same backend test, backend lint, frontend build, and secret/retired-path scan used locally.

On Windows, powershell -ExecutionPolicy Bypass -File scripts\.ps1 runs the same local gate. The final scan should return no real source secrets, retired acti dependencies, mirror registry lockfiles, or drift.

Python follows a library-style, latest-compatible-resolution CI policy: its declared minimum
ranges are intentionally not an immutable lock. The frontend is reproducibly locked with
lockfile v3, official-registry URLs, and SHA-512 integrity pins.

Design References

This project does not code from these systems. v2.4 uses original implementation
inspired by compatible architectural patterns from their official repositories:

LangGraph separates workflow state from checkpoint persistence and documents explicit

durability modes; Council applies that idea through an atomic session-store boundary.

OpenAI Agents SDK separates run traces from nested spans using context-local state;

Council keeps route e separate from pro traces.

Microsoft AutoGen uses explicit team participants and bounded termination controls;

Council treats named protocol selection as authoritative and keeps auto opt-in.

LiteLLM distinguishes retryable routing failures from permanent failures; Council uses

bounded status-aware retries without importing LiteLLM or its code.

Open WebUI separates process health and dependency readiness; Council exposes

/api/live, diagnostic /api/health, and strict /api/ready.

Useful source files:

LangGraph checkpointer documentation

OpenAI Agents SDK tracing documentation

Microsoft AutoGen selector group chat

Open WebUI main.py

LiteLLM router.py

Release Notes

See:

docs/releases/v2.4.1-release-hardening.md

docs/releases/v2.4-protocol-fidelity-resilience.md

docs/releases/2026-06-04-weiping-council-uupf-upgrade.md

docs/releases/v2.3-honest-runtime-obser.md

License

MIT

项目信息

开发语言：Python

Star 数：133

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Multi-LLM deliberation system with 6 protocols: council, debate, red-team, consensus, specialist, tournament展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。