Skip to content

System One

A vendor-neutral SDK for System One models. One contract — ask(state, questions) -> answers — over three question primitives (noul, choice, score). Switching providers is one config object, not a code change.

These are decision models, not chat models: no messages, no streaming, no temperature. You hand the model a state and a set of typed questions; it hands back a calibrated answer per question.

Installation

pip install "system-one[http]"   # hosted providers
pip install "system-one[onnx]"   # local, in-process
pip install "system-one[mcp]"    # expose an agent over MCP
pip install "system-one[all]"    # all of the above

The core install pulls only pydantic and pydantic-settings; every backend lives behind an extra.

Quickstart

from system_one import SystemOne, TypesafeConfig

agent = SystemOne(TypesafeConfig())  # reads $SYSTEM_ONE_API_KEY
response = agent.ask(
    "Customer is furious about a double charge.",
    {
        "urgent": {"type": "noul", "instructions": "Does this need a human now?"},
        "topic": {
            "type": "choice",
            "instructions": "Which queue?",
            "criteria": ["billing", "technical", "other"],
        },
        "severity": {
            "type": "score",
            "instructions": "How severe?",
            "criteria": ["minor", "normal", "major", "critical"],
        },
    },
)

print(response.nouls["urgent"].noul, response.nouls["urgent"].confidence)
print(response.choices["topic"].choice, response.choices["topic"].probabilities)
print(response.scores["severity"].score)

from system_one import AsyncSystemOne, TypesafeConfig

agent = AsyncSystemOne(TypesafeConfig())
response = await agent.ask(
    "Customer is furious about a double charge.",
    {"urgent": {"type": "noul", "instructions": "Does this need a human now?"}},
)

AsyncSystemOne has the same shape and the same method names as SystemOne, awaited: await agent.ask(...).

Where to go next

  • Questions — the three primitives and how to write them.
  • Answers — what comes back, and what the numbers mean.
  • Configuration — SYSTEM_ONE_* and the config classes.
  • Backends — hosted HTTP vs local ONNX.
  • Local model — fetch or export laya as ONNX and run offline.
  • Errors — the exception tree and retry behaviour.
  • MCP server — expose an agent as MCP tools.