Syntropy SDK & REST API Documentation — Python Client, CLI, MCP Server & OpenAI Bridge

1. Installation & Zero-Friction Authentication

# Install Official Python SDK, CLI & MCP Server from PyPI:
pip install --upgrade syntropy-client

# Fallback PEP 503 index or direct wheel URL:
pip install syntropy-client --extra-index-url https://synproof.ai/simple
pip install https://synproof.ai/sdk/syntropy_client-2.5.0-py3-none-any.whl

Supported Authentication Keys (Auto-Discovered from Environment):

• SYNTROPY_API_KEY — Managed key (syn_mng_...) or BYOK key (syn_byok_...) generated in the Syntropy Console.
• GEMINI_API_KEY / GOOGLE_API_KEY — Pass your existing Google Gemini key (AIza...) directly in X-API-Key or Authorization: Bearer for instant Zero-Friction BYOK!
• OPENROUTER_API_KEY — Pass your existing OpenRouter key (sk-or-v1-...) directly for multi-model verification (Claude 3.5 Sonnet, DeepSeek R1, GPT-4o, Gemini 2.5 Flash).

2. Python SDK Reference (SyntropyClient & @verify_agent_output)

from syntropy import SyntropyClient, verify_agent_output, SyntropyGuardrailError

client = SyntropyClient(
    base_url="https://api.synproof.ai",  # Default production endpoint
    # api_key="syn_mng_...",             # Optional if set in environment
)

# 2.1 Synchronous or Asynchronous Dialectical Verification
verdict = client.debate.verify(
    thesis="A distressed subsidiary may set off an unmatured shareholder loan 45 days before insolvency.",
    world="@law:civil-code-obligations",
    initial_axioms=[
        "Transfers or set-offs to related parties within 90 days prior to insolvency are voidable.",
        "Shareholder loans are statutorily subordinated during the 90-day twilight period."
    ],
    max_failures=3,
    enable_research=False,
    model_name="gemini-2.5-flash",
)

print("Confirmed:", verdict.is_confirmed)          # False
print("Status:", verdict.status)                   # "REFUTED"
print("Winning Thesis:", verdict.winning_thesis)
print("Refuting Argument:", verdict.refuting_argument)
print("Stopping Reason:", verdict.stopping_reason) # "THESIS_DEFEATED" | "SCEPTICAL_EXHAUSTION"

# 2.2 Decorator Guardrail for AI Agents (@verify_agent_output)
@verify_agent_output(
    world="@law:civil-code-obligations",
    max_failures=3,
    on_refuted="fallback",          # "fallback" | "raise" | "return_verdict"
    auto_ingest_confirmed=False,
    client=client,
)
def contract_compliance_agent(user_prompt: str) -> dict:
    return {"answer": "A consumer may withdraw from an online purchase within 7 days."}

# 2.3 Small Worlds Discovery, Private Forking & Live Database Axiomat Ingestion
worlds = client.worlds.list(domain="law")
axioms = client.worlds.get_axioms("@law:civil-code-obligations")
fork = client.worlds.fork("@law:civil-code-obligations", title="Acme Corp Private Compliance World")
client.worlds.ingest(
    fork["forked_world"]["handle"],
    payload={"max_liability_eur": 50000, "notice_period_days": 30},
    source_reference="PostgreSQL corporate_policies table",
)

3. CLI Reference (syntropy) & Model Context Protocol (MCP) Server

# Verify a thesis from the command line (exit code 0 = CONFIRMED, 2 = REFUTED):
python -m syntropy verify "Total entropy of an isolated system can spontaneously decrease." \
  --world "@physics:conservation-laws-thermo" \
  --max-failures 3 \
  --json

# List public Small Worlds & inspect axioms:
python -m syntropy worlds
python -m syntropy axioms @law:eu-gdpr-data-protection

# Fork a Small World & ingest a local document via Axiomat:
python -m syntropy fork @law:civil-code-obligations --title "My Company Rules"
python -m syntropy ingest @law:civil-code-obligations --file ./contract.pdf --source "MSA 2026"

# Install SKILL.md into the current workspace (.agents/skills, .claude/skills, .cursor/rules):
python -m syntropy install-skill

# Start the stdio MCP Server (exposes syntropy_verify, syntropy_list_worlds, syntropy_get_world_axioms, syntropy_fork_world, syntropy_ingest_axioms):
python -m syntropy mcp

4. Drop-In OpenAI & OpenRouter Compatible Bridge (POST /v1/chat/completions)

Use Syntropy from TypeScript, Node.js, Go, Rust, Python, LangChain, LlamaIndex, Vercel AI SDK, or Cursor by pointing any OpenAI SDK client to https://api.synproof.ai/v1:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.synproof.ai/v1",
  apiKey: process.env.SYNTROPY_API_KEY, // or GEMINI_API_KEY / OPENROUTER_API_KEY
});

const response = await client.chat.completions.create({
  model: "syntropy/epistemic-verifier", // or "syntropy/fast", "syntropy/claude-sonnet", "syntropy/deepseek-r1"
  messages: [
    { role: "system", content: "Verify against @law:eu-gdpr-data-protection\nAXIOM: Personal data breaches must be notified within 72 hours." },
    { role: "user", content: "A controller may wait 30 days before reporting a high-risk personal data breach to the supervisory authority." }
  ],
});

console.log(response.choices[0].message.content);

5. Complete REST API Endpoints & Parameters Matrix (https://api.synproof.ai)

• POST /v1/debate — Start an asynchronous 5-sieve dialectical verification job. Returns {"job_id": "...", "status": "queued"}.
• GET /v1/debate/{job_id} — Retrieve job status and complete formal verdict (CONFIRMED | REFUTED, winning_thesis, refuting_argument, argumentation_tree, telemetry).
• WS /v1/debate/ws (alias /ws/debate) — Real-time WebSocket stream emitting every dialectical node and sieve check live.
• POST /v1/chat/completions & GET /v1/models — OpenAI & OpenRouter compatible chat completion bridge.
• GET /v1/worlds (alias /v1/worlds/public) — List public and official verified Small Worlds.
• GET /v1/worlds/{id_or_handle}/axioms — Retrieve all atomic axioms for a Small World.
• POST /v1/worlds/axiomat/process — Compile an uploaded PDF, DOCX, TXT, or Markdown document into audited atomic axioms.
• POST /v1/worlds/{id_or_handle}/fork — Fork a Small World into an isolated private rulebase.
• POST /v1/worlds/{id_or_handle}/axiomat/ingest — Ingest new text or JSON database records into a Small World via Axiomat (on_conflict="flag" | "replace" | "keep").
• POST /v1/worlds/{id_or_handle}/axioms/push — Direct $0.00 batch push of pre-formulated axioms with deduplication.