Ploidy

Context-asymmetric structured debate for difficult decisions.

CI Docs PyPI License: MIT

Ploidy gives one side of a debate project context and keeps the other side fresh, then records positions before either side can anchor on the other. It ships as a Python 3.11+ MCP server with SQLite persistence.

Install

pip install ploidy

Add the API extra only when the server itself will generate an automatic debate:

pip install "ploidy[api]"

Recommended local setup: stdio

stdio is the default transport. One MCP client starts one server on demand, so there is no port or background process to manage.

{
  "mcpServers": {
    "ploidy": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "ploidy"]
    }
  }
}

The primary tool is debate:

• mode="solo": the caller supplies independently generated Deep and Fresh positions. No external model API is required.
• mode="auto": the server generates both sides through an OpenAI-compatible API. Non-empty context_documents are required so the Deep and Fresh sides are actually asymmetric.

Example auto call:

await debate(
    prompt="Should we split the ingestion service?",
    mode="auto",
    context_documents=["Current topology, incident history, and constraints…"],
    context_sources=["architecture-notes"],
)

Configure the API backend before using auto mode:

export PLOIDY_API_BASE_URL=https://api.openai.com/v1
export PLOIDY_API_KEY=...
export PLOIDY_API_MODEL=your-model

Shared server: Streamable HTTP

Use HTTP when multiple MCP clients must share one debate or when Ploidy is deployed as a service:

PLOIDY_TRANSPORT=streamable-http python3 -m ploidy
export PLOIDY_URL=http://127.0.0.1:8765

Configure each client with ${PLOIDY_URL}/mcp (substitute the value; JSON does not expand shell variables):

{
  "mcpServers": {
    "ploidy": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

PLOIDY_URL is the base URL used by ploidy-ask and other HTTP clients. The MCP endpoint is /mcp, and the live HTTP/SSE endpoint is /v1/debate/stream.

MCP tools

Ploidy 0.4.0 exposes exactly 13 tools. New integrations should use the unified debate tool. The other 12 remain available for explicit two-client, phase-by-phase, history, cancellation, and HITL workflows.

Tool	Purpose
debate	Unified auto or solo debate
debate_start	Create a Deep session
debate_join	Join as Fresh or Semi-Fresh
debate_position	Submit an independent position
debate_challenge	Submit a semantic challenge
debate_converge	Produce the convergence result
debate_cancel	Cancel an active debate
debate_delete	Permanently delete a debate
debate_status	Read current state
debate_history	List visible debate history
debate_solo	Legacy alias for caller-supplied debate
debate_auto	Legacy alias for API-generated debate
debate_review	Approve, override, or reject a paused auto debate

Service configuration

Common environment variables:

PLOIDY_TRANSPORT=stdio             # stdio (default) or streamable-http
PLOIDY_PORT=8765
PLOIDY_DB_PATH=~/.ploidy/ploidy.db
PLOIDY_MAX_CONTEXT_TOKENS=20000    # recommended for hosted auto mode
PLOIDY_RATE_CAPACITY=20
PLOIDY_RATE_PER_SEC=1
PLOIDY_RETENTION_DAYS=30

Authentication modes and their limits:

• Admission-controlled self-hosting: PLOIDY_AUTH_MODE=bearer with PLOIDY_TOKENS='{"token":"tenant"}'.
• OAuth interoperability: PLOIDY_AUTH_MODE=oauth and an exact public PLOIDY_OAUTH_ISSUER; v0.4.0 auto-approves clients and therefore is not user login or public admission control.
• Migration only: PLOIDY_AUTH_MODE=both adds the static-token fallback.

Bearer mode without a configured token is intentionally unauthenticated and is suitable only for loopback development. Public services need a private ingress/gateway or controlled static tokens until OAuth gains resource-owner login and consent.

Container

The published image is immutable by release version:

docker run --rm \
  -p 127.0.0.1:8765:8765 \
  -v ploidy-data:/data \
  ghcr.io/heznpc/ploidy:0.4.0

Or run the checked-in Compose configuration:

docker compose up --build

The image defaults to streamable-http and contains the API, dashboard, metrics, Redis, and CLI runtime extras.

Documentation

• Getting started
• API reference
• v0.4 migration
• Custom Connector
• Deployment

License

MIT