Consensus

A collaborative intelligence platform that orchestrates structured reasoning between (optional) humans and AI models. Multiple participants — each with their own knowledge, tools, and analytical methods — work together under moderation to investigate questions, stress-test hypotheses, and synthesize conclusions. Supports eighteen analytical frameworks from Delphi estimation to adversarial trials, with built-in web search, document RAG, vision, persistent memory, sandboxed code execution, and extensible tooling via MCP.

Features

Discussion Engine

Turn-based discussions between any mix of human and AI participants
Designated moderator (human or AI) that summarizes after each turn, mediates conflicts, and produces final synthesis
Automatic turn rotation with manual reassignment option
Max rounds limit — set a maximum number of rounds (auto-concludes when reached, 0 = unlimited)
Devil's Advocate role — assign participants a constructive-critic role with dedicated prompt templates that challenge assumptions and identify weaknesses
Storyboard panel showing running summaries and conclusions alongside the conversation
AI-to-AI conversations run automatically without manual intervention
Participant-driven context loading — each AI participant loads context from the database using a configurable strategy (full history, sliding window, summary-compressed, or semantic RAG). The semantic strategy uses embedding-based retrieval to include the most relevant older messages alongside recent ones. Per-entity configuration with discussion-level defaults
Pause & resume — pause discussions and resume them later, even after conclusion
Dynamic participation — add or remove participants mid-discussion
Export — save discussions as JSON or HTML (desktop mode uses native save dialog)

Pluggable Discussion Methods

Different problems demand different reasoning structures. Consensus provides a DiscussionMethod abstraction that controls phases, prompts, response processing, and synthesis — while reusing the core infrastructure for turn-taking, message persistence, and tool execution.

Open Discussion (default) — the standard moderated round-robin with optional Devil's Advocate; a solid general-purpose method
Analysis of Competing Hypotheses (ACH) — from intelligence analysis. Participants enumerate all plausible hypotheses, gather evidence, then systematically rate each hypothesis against each piece of evidence (consistent/inconsistent/neutral). Focuses on disconfirming evidence and diagnostic evidence that distinguishes between hypotheses. Four phases: Hypothesise → Gather Evidence → Evaluate → Analyse
Belief State Diffusion — an LLM-native method. Each participant maintains an explicit probability distribution over hypotheses (not prose opinions). Over multiple rounds, participants see others' distributions and reasoning, update their own beliefs, and show the math. Automatic convergence detection stops when belief deltas fall below a threshold. Produces graphable belief trajectories showing which arguments were actually persuasive. Three phases: Prior → Diffuse → Diagnose
Delphi Method — independent anonymous responses across multiple rounds; facilitator shares statistical distribution and anonymised reasoning; participants revise. Avoids anchoring, authority bias, and social pressure. Phases: Estimate → Revise → Synthesise
Premortem Analysis — assume a preliminary conclusion is reached, then each participant independently constructs a narrative of how and why it failed. Psychologically easier than critiquing a live idea. Phases: Frame → Premortem → Consolidate
Key Assumptions Check — explicitly surface and challenge the assumptions underlying the question before analysis begins. Can function standalone or as a first phase in other methods. Phases: Surface → Challenge → Assess
Adversarial Collaboration (Kahneman-style) — participants who genuinely disagree jointly design the criteria that would settle the question before gathering evidence. Prevents post-hoc rationalisation. Phases: Positions → Criteria → Evidence → Adjudicate
Red Team / Blue Team — rotating adversarial role each round; red team sees only the current conclusion and tries to break it. Phases: Construct → Attack → Revise → Assess
Participant Voting — structured deliberation followed by formal voting. Participants propose motions during deliberation, then vote for/against/abstain on each motion. Configurable thresholds (simple majority, supermajority, unanimous). Double-vote prevention, tally with pass/fail. Phases: Deliberate → Vote → Tally
Counterfactual Stress Testing — systematically tests which beliefs are load-bearing vs. decorative in a developing consensus. For each key claim, participants argue from the premise that it is false and score the impact. Produces a ranked classification of claims by structural importance. Phases: Deliberate → Extract Claims → Stress Test → Synthesize
Recursive Decomposition — breaks complex multi-faceted questions into manageable sub-questions, analyses each independently, then recomposes findings into a coherent synthesis. Phases: Decompose → Analyze Sub-questions → Integrate → Recompose
Recursive Self-Distillation — an LLM-native method that separates persuasiveness from validity. Participants generate rich reasoning, then strip it to a pure logical skeleton (premises → inferences → conclusion). A blind evaluator assesses only the skeleton, preventing rhetorical flourishes from masking weak logic. Phases: Generate → Distill → Evaluate → Synthesize
Court of Law — a structured adversarial trial. Participants are assigned to opposing legal teams (prosecution/plaintiff vs defence) and the moderator acts as judge, delivering a reasoned verdict. Teams with multiple members privately huddle before speaking, with per-recipient context filtering. Criminal or civil mode is inferred from the assigned roles. Phases: Arraignment → Opening Statements → Prosecution Case → Defence Case → Closing Arguments → Verdict
Nominal Group Technique — the catalogue's first generative method: instead of critiquing an existing position, the group creates and prioritises options. Participants silently and independently propose ideas (anonymised), the moderator merges duplicates, one clarification round ensures shared understanding, then each participant distributes a fixed pool of points. Produces a ranked shortlist. Phases: Generate → Cluster → Clarify → Allocate → Rank
Weighted Decision Matrix (MCDA) — multi-criteria decision analysis for choosing between options. Participants enumerate alternatives, jointly define weighted criteria, and score every option against every criterion. Weighted totals produce a ranked result plus a deterministic sensitivity analysis (does the winner survive weight changes?) and a machine-readable decision artifact. Phases: Options → Criteria → Score → Sensitivity → Decide
Double Crux — rather than sharpening opposing positions, this searches for the underlying factual belief that actually drives a disagreement, then focuses evidence on that alone. Belief shift on the crux is the success metric; where no factual crux exists, a clean map ("this is a values difference") is itself the successful outcome. Phases: Positions → Hunt → Identify → Test → Resolve
Tree of Thoughts — LLM-native iterative parallel exploration. Participants independently propose distinct approaches (anonymised to avoid anchoring), everyone scores them on feasibility/impact/risk, and a deterministic beam prune keeps the strongest few. Survivors get a deep-dive round and are re-scored; the loop repeats until the ranking stabilises or a depth budget is spent. Phases: Propose → Score → Prune → Expand → Synthesise
Guided Triage — a meta-method for collaborative method selection. The moderator interviews human participants about the problem type, decision context, and uncertainty structure, then an LLM-based recommender suggests the most appropriate method. The group confirms or adjusts before the discussion switches to the chosen method automatically. Phases: Intake → Recommend → Confirm

Methods are selected per-discussion at setup time, or recommended by the built-in Method Recommender — an LLM-based classifier that suggests the best method given a topic and answer type. The architecture is extensible — new methods implement the DiscussionMethod ABC and register in the method registry.

Panel-independence warning: Delphi and Belief State Diffusion assume independent estimators. When a single model covers more than half the AI estimator panel, Consensus shows a non-blocking warning at setup and discloses the panel's model composition in the conclusion prompt, so convergence claims can be caveated rather than silently overstated.

Composable Phase Library

Internally, all structured methods are built from composable PhaseHandler instances — self-contained units that encapsulate prompts, response processing, state initialization, and advancement logic for a single phase. Methods are assembled declaratively as ordered tuples of handlers:

class KeyAssumptionsCheck(DiscussionMethod):
    phase_handlers = (
        SurfaceAssumptionsHandler(),
        ChallengeAssumptionsHandler(),
        AssessAssumptionsHandler(),
    )

This design means phases can be reused across methods (e.g. Double Crux reuses Adversarial Collaboration's StatePositionsHandler as its opening phase), and new methods can be created by composing existing handlers without writing boilerplate. The library includes 68 handlers and 15 shared helper modules in consensus/methods/phases/.

Structured Phase Outputs

Phases whose results must be machine-readable (belief distributions, ACH matrices, MCDA scores, votes) don't parse prose — they declare an output tool schema and the model is forced to call it via tool_choice. Payloads are validated by the handler's validate_output hook, with validation errors fed back for a bounded number of retries. Models without tool-calling support are rejected at discussion setup rather than failing mid-discussion.

Schema-driven human input — when a human takes a turn in a structured phase, the frontend renders an input form generated from that phase's schema, so humans never have to hand-write JSON. Submissions go through the same validation and recording path as AI turns.
Loud failure — unparseable input surfaces a visible error instead of being silently dropped.

Evidence Tracking

Phases can opt into turn-level provenance tracking. Each contribution is classified in code (never by the model) as grounded — backed by a successful evidence-tool call, a bare URL, or an [evidence: …] marker — or reasoning-based, then annotated in the display text and recorded to an evidence log that the conclusion draws on.

This is deliberately soft: an ungrounded turn is annotated and logged, never rejected. Grounding means a citation is present, not that the source was fetched or actually supports the claim. Currently enabled on Double Crux's Test phase.

Multi-Provider AI Support

OpenAI-compatible API support — works with OpenAI, Anthropic, Ollama, DeepSeek, LMStudio, vLLM, and any compatible endpoint
Provider registry with pre-seeded defaults (Ollama, Anthropic, DeepSeek, OpenAI)
Dynamic model discovery — automatically fetches available models from each provider
Per-entity configuration — temperature, max tokens, and custom system prompts per participant
Secure API key handling — keys referenced by environment variable name, never stored on disk
Retry with exponential backoff — transient API failures (429, 5xx, timeouts) retry up to 3 times with backoff; failed participants are skipped gracefully

Web Access

web_search tool — Brave Search API when BRAVE_SEARCH_API_KEY is set, with automatic DuckDuckGo fallback so search works with no key at all
fetch_webpage tool — retrieves and extracts the readable text of a page, so participants can read a source found via search rather than relying on the snippet
Native function calling — tools are invoked through the provider's own tool-call API, with a bounded execution loop per turn
Opt-in per entity — web tools are assigned via the Profiles tab, with optional per-discussion overrides

Institutional Memory (Optional)

Long-term personal memory — AI entities store and recall observations, positions, and insights across discussions
Semantic discussion search — search past discussion messages by meaning, not just keywords
Knowledge graph — AI entities assert and query structured concept/relationship triples (e.g. "free will contradicts hard determinism")
Proactive memory use — default prompts encourage AI participants to recall past context before responding and store key insights after contributing
Per-entity memory — each AI entity maintains its own private memory, scoped by entity ID
Graceful degradation — if the embedding service (Ollama) is unavailable, discussions continue without memory; tools return informative errors
Opt-in per entity — memory tools are assigned via the Profiles tab, keeping them invisible to entities that don't need them
Requires Ollama running with an embedding model. The embedding backend, model, and endpoint are configured in the UI (stored in the memory_config table), defaulting to nomic-embed-text-v2-moe:latest at http://localhost:11434

Document RAG (Optional)

Reference document ingestion — add documents to a discussion by URL or inline text; supports PDF (via pdfplumber/PyPDF2), HTML (via trafilatura), and plain text/Markdown
Automatic chunking & embedding — documents are split into overlapping chunks with paragraph-aware boundaries, then embedded in the background for semantic search
RAG-powered Q&A — doc_ask retrieves the top-k most relevant chunks via cosine similarity and calls an LLM to answer with passage citations
Structured navigation — doc_get_sections, doc_get_chapter, doc_get_text let participants browse documents by section headers or character ranges
Map-reduce summarization — doc_summary handles arbitrarily long documents by summarizing chunks then synthesizing
Cross-discussion document library — doc_list with full_library=true searches all documents across all discussions by semantic similarity
Per-discussion document binding — documents are associated with specific discussions; participants see only relevant documents by default
Opt-in per entity — document tools are assigned via the Profiles tab, like memory tools
Requires Ollama running with an embedding model (shared infrastructure with Institutional Memory)

Images & Vision

Image attachments — attach images to a discussion by upload or URL (PNG, JPEG, GIF, WebP, SVG; up to 20 MB)
Automatic vision routing — vision-capable participants receive images directly in their multimodal context. Capability is determined from authoritative OpenRouter modality data, falling back to model-name pattern matching
describe_image tool — non-vision models can still participate: a vision-capable model generates a description they can reason over
list_images and add_image_url tools — participants can browse discussion images and introduce new ones mid-discussion
Automatic resizing — images larger than 2048px are downscaled before being sent to models

Prompt Template System

Customizable prompt templates for every AI task (turn generation, summarization, mediation, conclusion, opening)
Role-aware templates — separate templates for moderator vs participant, AI vs human
Template variables — {entity_name}, {topic}, {participants}, {speaker_name}, {turn_number}, {context}
Default templates seeded on first run, fully editable

Entity Profiles

Reusable participant profiles with name, type (human/AI), and avatar color
AI configuration per profile — provider, model, temperature, max tokens, system prompt
Color-coded avatars with 8 presets or custom hex colors

Persistence & History

SQLite database with thread-safe concurrent access (WAL mode)
File-based migration system — versioned SQL migrations in consensus/migrations/, tracked in a migrations table, run idempotently on startup
Platform-aware storage — macOS: ~/Library/Application Support/consensus/, Linux: ~/.local/share/consensus/, Windows: %APPDATA%/consensus/
Full discussion history — browse, load, and review past discussions
Message metadata — model name, token counts, latency tracking per AI response

User Interface

Tabbed setup — New Discussion, Providers, Profiles, Prompts, Memory, History
Three-panel discussion view — participants sidebar, chat center, storyboard sidebar
Dark/light theme with automatic system preference detection
Markdown rendering in messages (headers, bold, italic, code blocks, lists)
Toast notifications with auto-dismiss
Speaking indicator animation for active participant
Pure HTML/CSS/JS frontend — no framework dependencies

Dual-Mode Application

Desktop mode via pywebview — lightweight native window (1280x800 default, 900x600 minimum)
Web mode via aiohttp — accessible from any browser or mobile device
Multi-user mode — per-session isolation with individual SQLite databases for public deployments
Both modes share the same backend and feature set

Authentication (Multi-User Mode)

Email/password registration with PBKDF2-SHA256 hashing (600k iterations, OWASP 2023)
OAuth sign-in via GitHub, Google, LinkedIn, and Apple (Authorization Code flow)
Multiple OAuth identities per user account (link GitHub + Google to the same account)
Secure token management — SHA-256 hashed token storage, httpOnly cookies, 30-day TTL
CSRF protection — Content-Type enforcement on all POST endpoints
Brute-force protection — per-email rate limiting (5 attempts per 5-minute window)
Login/register UI with OAuth provider buttons and form validation

Cost Tracking

Automatic per-message cost calculation using pricing data from OpenRouter
Model pricing cache in SQLite with 7-day auto-refresh
Fuzzy model name matching — handles naming variants (hyphens vs dots, date suffixes, provider prefixes)
Model aliases for known name mappings (e.g. deepseek-reasoner → deepseek/deepseek-r1)
Per-message and per-discussion cost display in the UI
Per-discussion cost limit — set a spend ceiling at setup; the discussion concludes gracefully when it is reached (0 = unlimited)

Interactive User Input

ask_user tool — AI participants can pause mid-turn to request input from the human user
Inline input bubble — question appears in the message flow with a textarea and submit button
Seamless continuation — the user's response is fed back as a tool result; the AI continues its turn incorporating the answer
Reconnection-safe — pending input requests survive page reloads via state synchronization
5-minute timeout — graceful handling if the user doesn't respond
Assign the ask_user tool to AI entities via the Profiles tab

Sandboxed Python Code Execution

execute_python tool — AI participants can write and run Python code during discussions for calculations, data analysis, and ML experiments
Multi-layered sandbox — AST pre-analysis, subprocess isolation, restricted builtins, whitelisted imports, sandboxed file I/O, and optional macOS sandbox-exec
Dynamic resource limits — allocates 70% of available free RAM and 70% of CPU cores, scaling automatically with the host machine
Scientific/ML libraries — numpy, scipy, pandas, torch, hypercomplex, matplotlib, sympy, and many more are allowed if installed
REPL-like output — captures stdout, stderr, and the last expression value (like a Jupyter cell)
install_python_package tool — participants can request missing PyPI packages; the user sees an approval prompt before uv pip install runs
Command injection protection — package names validated against a strict PEP 508 regex; code passed via stdin (not shell args)
Assign execute_python and install_python_package to AI entities via the Profiles tab

MCP Expert Plugins

MCP (Model Context Protocol) server integration — register external MCP servers via JSON-RPC 2.0 over stdio (local processes) or Streamable HTTP (remote servers)
Dual transport — stdio for local MCP servers (subprocess) and HTTP+SSE for remote MCP servers with session management (Mcp-Session-Id), retry with exponential backoff
Expert entities — a new entity type (expert) that wraps an MCP tool as a consultable participant
consult_expert meta-tool — AI participants can consult expert entities during turn generation; expert responses are added to the discussion
MCP server management — add, update, test, and delete MCP server configurations via the UI; transport selector toggles between stdio and HTTP fields
Config file-based MCP servers — load MCP server definitions from JSON or TOML config files at startup. Searches CONSENSUS_MCP_CONFIG env var, ./mcp_servers.json, ~/.consensus/, and the platform data directory. New servers are added to the DB; changed servers are updated
Real-time progress — SSE endpoint (GET /api/events) for tool execution progress notifications
Event emitter — lightweight pub/sub system in ConsensusApp for real-time event dispatch

MCP Server for External AI Agents

Consensus as an MCP server — the consensus-mcp command exposes Consensus data and operations to external AI agents (e.g. Claude Code) via stdio JSON-RPC 2.0
13 tools for reading, searching, and writing:
- Passive: list_discussions, read_discussion, search_discussions, list_entities, search_memories, query_knowledge_graph, list_documents, read_document, search_documents
- Active: store_memory, delete_memory, assert_knowledge, run_discussion
Persistent agent memory — the coding agent gets its own entity ("Claude Code Agent") with private long-term memory that persists across sessions
Run full discussions programmatically — run_discussion creates, moderates, and concludes an AI discussion on any topic, returning the synthesised result
Memory deletion safeguards — agents can only delete their own memories; ownership is hardcoded and double-enforced at the DB layer
Graceful degradation — listing and reading tools work without an embedding service; semantic search tools return helpful errors if Ollama is unavailable

Evaluation Framework

Ablation study platform for testing multi-agent discussion configurations against medical case vignettes
10 seed cases with gold diagnoses, key findings, and differential diagnoses
5 ablation conditions — progressively complex setups from baseline single-agent to full multi-agent with Devil's Advocate, memory, and tools
Batch runner with automated scoring (string-match + optional LLM-judge)
Per-participant provider/model overrides — mix different AI backends within a single evaluation run
Web UI at /eval/ for case management, condition editing, batch execution, and results analysis
Accessible from both desktop mode (opens in browser) and web mode

Multi-User Deployment

Session isolation — each browser session gets its own ConsensusApp instance and SQLite database
BYOK (Bring Your Own Key) — users provide their own LLM API keys via the browser UI; keys are stored in sessionStorage and never persisted server-side
Rate limiting — per-session/IP rate limiting (120 requests/minute default)
Security headers — CSP, X-Frame-Options, X-Content-Type-Options
CORS controls — configurable allowed origins via CONSENSUS_ALLOWED_ORIGINS
Health endpoint — GET /health for load balancer health checks
TTL-based session expiry — sessions auto-expire after 24h of inactivity (configurable)

Installation

Requires Python 3.11+. Recommended: uv (curl -LsSf https://astral.sh/uv/install.sh | sh).

# Install from PyPI as a global command (recommended)
uv tool install consensus-app

# Or with pip into the current environment
pip install consensus-app

macOS users can instead download the notarized Consensus-<version>.dmg from the releases page and drag Consensus into Applications.

Note: The PyPI distribution is named consensus-app (the name consensus was taken), but the command and the import package are plainly consensus.

From source (development)

git clone https://github.com/hherb/consensus.git
cd consensus
uv tool install -e .          # editable global command
# or: uv pip install -e .     # editable, into the active venv

All features (desktop, web, documents, memory, images) are installed by default. The old extras ([all], [desktop], …) still parse but are empty.

Linux desktop mode: Install GTK dev libraries first so PyGObject can compile inside the uv venv:
sudo apt install libgirepository-2.0-dev libcairo2-dev pkg-config python3-dev gir1.2-gtk-3.0 gir1.2-webkit2-4.1
On Ubuntu 22.04 or older, use libgirepository1.0-dev instead of libgirepository-2.0-dev.

Alpha testers: see docs/alpha_testing.md for a step-by-step install and feedback guide.

Usage

# Desktop mode (default)
consensus

# Web server mode (accessible from browser/mobile)
consensus --web
consensus --web --host 0.0.0.0 --port 8080

# Multi-user mode (public deployment with per-session isolation)
consensus --web --multi-user
consensus --web --multi-user --host 0.0.0.0 --port 8080

# Debug mode
consensus --web --debug

MCP Server for AI Agents

Consensus includes an MCP server that lets external AI agents (like Claude Code) search discussions, query memories, and even trigger full discussions:

# Install (if not already)
uv pip install -e .

# Test the server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | consensus-mcp

To configure in Claude Code, add to your MCP settings:

{
  "mcpServers": {
    "consensus": {
      "command": "consensus-mcp"
    }
  }
}

Setting Up AI Providers

API keys are configured via environment variables. Set the relevant variables before launching:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export DEEPSEEK_API_KEY="sk-..."

For local providers like Ollama, no API key is needed — just ensure the service is running.

In multi-user mode, users provide their own API keys via the browser UI (stored in sessionStorage, never persisted on the server). Environment-based keys serve as a fallback.

Environment Variables

Variable	Description
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`DEEPSEEK_API_KEY`	DeepSeek API key
`BRAVE_SEARCH_API_KEY`	Brave Search API key for the `web_search` tool (falls back to DuckDuckGo if unset)
`CONSENSUS_MCP_CONFIG`	Path to MCP server config file (JSON or TOML); overrides default search paths
`CONSENSUS_ALLOWED_ORIGINS`	Comma-separated allowed CORS origins (multi-user mode)
`CONSENSUS_SESSION_DIR`	Custom directory for per-session SQLite databases
`CONSENSUS_BASE_URL`	Public base URL for OAuth redirects (e.g. `https://yourdomain.com`)
`CONSENSUS_GITHUB_CLIENT_ID`	GitHub OAuth app client ID
`CONSENSUS_GITHUB_CLIENT_SECRET`	GitHub OAuth app client secret
`CONSENSUS_GOOGLE_CLIENT_ID`	Google OAuth client ID
`CONSENSUS_GOOGLE_CLIENT_SECRET`	Google OAuth client secret
`CONSENSUS_LINKEDIN_CLIENT_ID`	LinkedIn OAuth client ID
`CONSENSUS_LINKEDIN_CLIENT_SECRET`	LinkedIn OAuth client secret
`CONSENSUS_APPLE_CLIENT_ID`	Apple OAuth client ID
`CONSENSUS_APPLE_CLIENT_SECRET`	Apple OAuth client secret

Embedding settings (backend, model, endpoint) are not environment variables — they are configured in the UI and stored in the database, defaulting to Ollama with nomic-embed-text-v2-moe:latest at http://localhost:11434.

Architecture

Frontend (static HTML/CSS/JS)
    ↕ pywebview bridge OR aiohttp REST API
ConsensusApp — orchestrator, state management, event emitter
    ├── app_providers.py — provider management
    ├── app_entities.py — entity CRUD
    ├── app_discussion_setup.py — discussion creation & configuration
    ├── app_discussion_flow.py — turn flow operations
    ├── app_discussion_state.py — discussion state management
    ├── Moderator — turn flow, AI generation, summaries
    ├── DiscussionMethod (methods/) — pluggable analytical frameworks
    │     ├── PhaseHandler (methods/phase_handler.py) — composable phase ABC
    │     ├── 18 method classes assembled from 68 phase handlers
    │     ├── MethodRecommender (methods/recommender.py) — LLM-based method classification
    │     ├── panel_diversity.py — same-model estimator-panel warning
    │     └── methods/phases/ — reusable handler implementations + helpers
    ├── structured_output.py — forced tool-call generation for structured phases
    ├── structured_input.py — schema-driven input specs for human structured turns
    ├── evidence.py — turn-level grounded/reasoning-based provenance tracking
    ├── ContextStrategies (context_strategies.py) — per-participant DB context loading (incl. semantic RAG)
    ├── AIClient — async OpenAI-compatible HTTP client (httpx)
    ├── Database (db/) — thread-safe SQLite persistence (domain-specific mixins)
    ├── PricingCache — model cost lookup + modality/capability data via OpenRouter
    ├── MCPToolProvider — MCP stdio transport (JSON-RPC 2.0 over subprocess)
    ├── MCPHTTPToolProvider — MCP Streamable HTTP transport (JSON-RPC 2.0 over HTTP+SSE)
    ├── mcp_config.py — MCP server definitions loaded from JSON/TOML config files
    ├── WebSearch (tools_builtin.py) — Brave Search + DuckDuckGo fallback, page fetching
    ├── DocumentRAG (tools_document.py) — document ingestion, chunking, RAG Q&A
    ├── ImageTools (tools_image.py) — image storage, vision routing, description
    ├── AskUser (tools_ask_user.py) — interactive user input during AI turns
    ├── PythonExec (tools_python.py) — sandboxed Python code execution + package install
    ├── AuthManager (auth.py) — password + OAuth authentication (multi-user mode)
    ├── Migrator — file-based SQL migration runner
    └── Evaluation — ablation study framework (cases, runner, scorer)

MCP server (consensus-mcp):
    ConsensusMCPServer (mcp_server.py)
        ├── Database — direct SQLite access (read/search/write)
        ├── EmbeddingClient — semantic search via Ollama
        └── ConsensusApp — programmatic discussion orchestration

Multi-user mode:
    SessionManager (session.py)
        ├── Session A → ConsensusApp A → SQLite A
        ├── Session B → ConsensusApp B → SQLite B
        └── ...TTL-based expiry, max session cap

Key dependencies (all installed by default):

httpx — async HTTP client for OpenAI-compatible API calls
pywebview — lightweight cross-platform desktop webview
aiohttp — web server for browser/mobile access
sqlite-vec + numpy — vector similarity search for institutional memory, document RAG, and semantic context
pdfplumber / trafilatura — PDF and HTML parsing for document RAG
Pillow — image dimension detection and resizing

Development

git clone https://github.com/hherb/consensus.git
cd consensus
uv pip install -e .
python -m pytest          # 2505 tests

Developer documentation lives in docs/devel/; the end-user manual is in docs/user_manual/. Planned and completed features are tracked in ROADMAP.md.

See DEPLOYMENT.md for production deployment instructions (Oracle Cloud Free Tier).

License

AGPL-3.0 — see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 523 Commits
.claude/skills		.claude/skills
assets		assets
consensus		consensus
docs		docs
packaging/macos		packaging/macos
scripts		scripts
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
DEPLOYMENT.md		DEPLOYMENT.md
HANDOVER.md		HANDOVER.md
HOWTO_MCP_SERVER.md		HOWTO_MCP_SERVER.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
ROADMAP.md		ROADMAP.md
code_statistics.py		code_statistics.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Consensus

Features

Discussion Engine

Pluggable Discussion Methods

Composable Phase Library

Structured Phase Outputs

Evidence Tracking

Multi-Provider AI Support

Web Access

Institutional Memory (Optional)

Document RAG (Optional)

Images & Vision

Prompt Template System

Entity Profiles

Persistence & History

User Interface

Dual-Mode Application

Authentication (Multi-User Mode)

Cost Tracking

Interactive User Input

Sandboxed Python Code Execution

MCP Expert Plugins

MCP Server for External AI Agents

Evaluation Framework

Multi-User Deployment

Installation

From source (development)

Usage

MCP Server for AI Agents

Setting Up AI Providers

Environment Variables

Architecture

Development

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages