choiceone

A type-safe decision layer between your Python code and an AI model.

Instead of generating prose and parsing it back, choiceone sends an unstructured state plus a closed set of typed questions and returns typed, probabilistic decisions your code can branch on directly. Answers cannot have a type error: they are always a distribution over the options you supplied.

Implements the "ChoiceOne" protocol: state in, typed probabilistic decisions out.

Install

pip install choiceone            # core, no model dependencies
pip install 'choiceone[local]'   # + local Hugging Face backend (torch, transformers)
pip install 'choiceone[server]'  # + HTTP server (fastapi, uvicorn)

Quick start

from choiceone import ChoiceOne, Choice

so = ChoiceOne()  # default local model
response = so(
    state="My running shoes arrived in the wrong size.",
    questions={
        "department": Choice(
            instructions="Which team should handle this?",
            criteria={
                "returns": "Exchanges, wrong or damaged items",
                "shipping": "Delivery status, delays, lost packages",
                "billing": "Charges, invoices, payment problems",
            },
        ),
    },
)

answer = response.answers["department"]
print(answer.choice, answer.probabilities, answer.confidence)

Primitives

Every Choice/Score answer includes a confidence derived from how peaked the distribution is, so your code can act automatically, ask, or escalate.

Backends

The model side is a pluggable Backend. choiceone ships with two:

• LocalBackend — a local Hugging Face causal LM (default Qwen/Qwen3-0.6B). Text-generation-free: reads the next-token distribution.
• OpenAIBackend — any OpenAI-compatible logprobs endpoint (DeepSeek, OpenAI, vLLM, ...). Stdlib only.

Embed your own AI by subclassing Backend and implementing three methods:

from choiceone import Backend

class MyBackend(Backend):
    def build_prompt(self, user_content): ...
    def count_tokens(self, texts): ...
    def probs_over_labels(self, prompts, labels_per_prompt): ...

HTTP server

choiceone-serve --model Qwen/Qwen3-0.6B --port 8000
# POST /v1/choiceone  {"state": ..., "questions": {...}}

License

MIT