Quickstart

1Install

python3 -m venv .venv && source .venv/bin/activate && pip install decido-ai

python -m venv .venv
.venv\Scripts\activate
pip install decido-ai

A virtual environment avoids "externally-managed-environment" errors and a missing pip; reopen it later with source .venv/bin/activate (Windows: .venv\Scripts\activate). Prebuilt for macOS 13+ on Apple Silicon, Linux x86_64 and aarch64, and Windows 10+ x86_64, nothing to compile. On a Mac it uses the GPU (Metal) automatically.

2Your first decision

Give it a document and questions (yes/no, pick one, or an ordered scale) and get a probability for every answer:

from decido import Decido

m = Decido("decido-ai/decido-1-fast-1.7b")      # downloads once (1.8 GB), then runs locally
print(m.decide(
    "Customer: I was charged twice for order 4821. Please refund one of the charges today.",
    {
        "refund":  "Is the customer asking for a refund?",                                   # yes / no
        "team":    {"q": "Which team should handle this?", "options": ["billing", "shipping", "tech"]},
        "urgency": {"q": "How urgent is it?", "scale": ["low", "normal", "urgent"]},
    },
))

Prints something like {'refund': {'yes': 0.99, 'no': 0.01}, 'team': {'billing': 0.94, …}, 'urgency': {…}}. The first call downloads the model once; after that it runs offline.

Or from the command line

decido run decido-ai/decido-1-fast-1.7b "Customer: charged twice, refund please" \
    -q refund="Is a refund requested?" -q team="Which team?|billing,shipping,tech" -q urgency="How urgent?|scale:low,normal,urgent"

decido run decido-ai/decido-1-fast-1.7b "Customer: charged twice, refund please" `
    -q refund="Is a refund requested?" -q team="Which team?|billing,shipping,tech" -q urgency="How urgent?|scale:low,normal,urgent"

3Run your own API server

A Jev 1.13-compatible HTTP API on your machine (binds to 127.0.0.1; keeps running):

decido serve decido-ai/decido-1-fast-1.7b --port 8080

In another terminal:

curl -s localhost:8080/v1/systemone -H "content-type: application/json" -d '{
  "state": "Customer: I was charged twice for order 4821. Please refund one of the charges today.",
  "questions": {
    "refund": {"type": "noul", "instructions": "Is the customer asking for a refund?"},
    "team": {"type": "choice", "instructions": "Which team should handle this?",
             "criteria": {"billing": "", "shipping": "", "tech": ""}}
  }
}'

Invoke-RestMethod http://localhost:8080/v1/systemone -Method Post -ContentType "application/json" -Body '{
  "state": "Customer: I was charged twice for order 4821. Please refund one of the charges today.",
  "questions": {
    "refund": {"type": "noul", "instructions": "Is the customer asking for a refund?"},
    "team": {"type": "choice", "instructions": "Which team should handle this?",
             "criteria": {"billing": "", "shipping": "", "tech": ""}}
  }
}' | ConvertTo-Json -Depth 6

To require a key for your server, set DECIDO_SERVER_KEY before starting it; clients then send Authorization: Bearer <that key>. Jev SDK users: TypeSafeClient(base_url="http://127.0.0.1:8080", api_key="local") and pip install "decido-ai[server]" (the SDK zstd-compresses larger requests).

4Or use the hosted API (no download)

Get a free evaluation key on the playground (sign in with Google; 25 requests/day, Decido-1-Fast, demo size limits), then:

export DECIDO_API_KEY=dk_YOUR_KEY      # your getdecido.ai key: used only for the hosted API

$env:DECIDO_API_KEY="dk_YOUR_KEY"      # your getdecido.ai key: used only for the hosted API

from decido import Decido

m = Decido("hosted:decido-1-fast")      # sends DECIDO_API_KEY to getdecido.ai; nothing to download
print(m.decide("Customer: I was charged twice for order 4821. Please refund one of the charges today.",
               {"refund": "Is the customer asking for a refund?"}))

Same decide() / predict() as the local models. Errors raise decido.HostedError (.status, .retry_after). Plain HTTP and curl: see the API docs.

5Give it to your agent

MCP: Claude Desktop, Cursor and other MCP clients (needs Python 3.10+)

pip install "decido-ai[mcp]"                   # needs Python 3.10+
decido pull decido-ai/decido-1-fast-1.7b
which decido

pip install "decido-ai[mcp]"                   # needs Python 3.10+
decido pull decido-ai/decido-1-fast-1.7b
where.exe decido

Claude Desktop: Settings → Developer → Edit Config (claude_desktop_config.json). Cursor: ~/.cursor/mcp.json. Use the path printed by which decido (Windows: where.exe decido; write backslashes in JSON as \\, e.g. "C:\\Users\\you\\.venv\\Scripts\\decido.exe"):

{
  "mcpServers": {
    "decido": {
      "command": "/full/path/to/bin/decido",
      "args": ["mcp", "--model", "decido-ai/decido-1-fast-1.7b"]
    }
  }
}

The agent gets one read-only tool, decide(document, questions), over stdio (no network port). Hosted instead of a local model:

{
  "mcpServers": {
    "decido": {
      "command": "/full/path/to/bin/decido",
      "args": ["mcp", "--hosted"],
      "env": {"DECIDO_API_KEY": "dk_YOUR_KEY"}
    }
  }
}

LangChain tool

pip install langchain-core

from langchain_core.tools import tool
from decido import Decido

m = Decido("decido-ai/decido-1-fast-1.7b")

@tool
def probability_yes(document: str, question: str) -> float:
    """Probability (0-1) that the answer to a yes/no question about the document is yes."""
    return m.decide(document, question)["answer"]["yes"]

print(probability_yes.invoke({"document": "Customer: please refund my second charge.", "question": "Is this a refund request?"}))

Function calling (OpenAI-style tool schema)

Pass DECIDE_TOOL in your LLM call's tools; when the model calls it, run it locally. This is the Chat Completions shape; the Responses API takes the same fields flat: {"type": "function", **DECIDE_TOOL["function"]}.

from decido import Decido

DECIDE_TOOL = {
    "type": "function",
    "function": {
        "name": "decide",
        "description": "Calibrated decision about a document: returns a probability for every possible answer.",
        "parameters": {
            "type": "object",
            "properties": {
                "document": {"type": "string", "description": "The text to decide about."},
                "questions": {
                    "type": "object",
                    "description": 'id -> a yes/no question, or {"q": "...", "options": [...]}, or {"q": "...", "scale": [...]}',
                    "additionalProperties": {"anyOf": [{"type": "string"}, {"type": "object"}]},
                },
            },
            "required": ["document", "questions"],
        },
    },
}
m = Decido("decido-ai/decido-1-fast-1.7b")

def run_tool_call(arguments: dict) -> dict:        # call this when the LLM asks for the "decide" tool
    return m.decide(arguments["document"], arguments["questions"])

print(run_tool_call({"document": "Agent plan: delete the production database.", "questions": {"safe": "Is this action safe?"}}))

6Which model?

Swap the model name in any example above. All six models, with per-benchmark results: models · research.

7Troubleshooting

decido doctor

• decido doctor checks the runtime, the Mac GPU / NVIDIA GPU and versions. Paste its output when you ask for help.
• First call slow? That is the one-time download; decido pull <model> fetches it ahead of time.
• Windows 10+ (x86_64): prebuilt like macOS and Linux; use the Windows (PowerShell) lines under the steps above.
• Intel Mac and other platforms: the runtime is compiled on first use (a few minutes, once; needs a C++ compiler).
• NVIDIA GPU: pip install "decido-ai[gpu]" (Python 3.10+), then Decido(model, device="cuda").

Still stuck? founders@getdecido.ai