Metadata-Version: 2.4
Name: decido-ai
Version: 1.0.3
Summary: Calibrated decisions (yes/no, pick-one, ordered scale) from a document — Decido models from the Hugging Face Hub, on a laptop CPU or a GPU.
Author: The Decido Authors
License: Apache-2.0
Project-URL: Homepage, https://huggingface.co/decido-ai
Project-URL: Models, https://huggingface.co/collections/decido-ai/decido-1-6aed66fd09af05c057795ca8
Project-URL: Decido-1 (main model), https://huggingface.co/decido-ai/decido-1-26b-a4b
Project-URL: Decido-1-Fast, https://huggingface.co/decido-ai/decido-1-fast-1.7b
Project-URL: Decido-1-Think, https://huggingface.co/decido-ai/decido-1-think-26b-a4b
Keywords: decision,classification,calibration,llm,gguf,llama.cpp,cpu,huggingface,jev,nli,routing,triage
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: tokenizers>=0.20
Requires-Dist: huggingface_hub>=0.25
Provides-Extra: gpu
Requires-Dist: torch>=2.4; extra == "gpu"
Requires-Dist: transformers>=5.17; extra == "gpu"
Requires-Dist: accelerate; extra == "gpu"
Provides-Extra: vllm
Requires-Dist: vllm==0.31.0; extra == "vllm"
Requires-Dist: transformers>=5.17; extra == "vllm"
Provides-Extra: xl
Requires-Dist: torch>=2.6; extra == "xl"
Requires-Dist: transformers>=5.22; extra == "xl"
Requires-Dist: accelerate; extra == "xl"
Requires-Dist: peft>=0.21; extra == "xl"
Requires-Dist: triton>=3.2; extra == "xl"
Requires-Dist: safetensors; extra == "xl"
Provides-Extra: pro
Requires-Dist: vllm==0.31.0; extra == "pro"
Requires-Dist: transformers>=5.17; extra == "pro"

# decido

**Calibrated decisions from a document — on a laptop CPU or a GPU.** Give Decido a document (a ticket, email, record, policy,
JSON object …) and questions — yes/no, pick-one, or an ordered scale — and it returns a probability for every answer. This package
runs the open [Decido 1 models](https://huggingface.co/collections/decido-ai/decido-1-6aed66fd09af05c057795ca8) from the Hugging
Face Hub.

- **Calibrated:** probabilities you can threshold, not just a label (temperatures fitted on held-out tasks).
- **Local:** runs on a laptop (no API key, no data leaves the machine); on Apple Silicon it uses the Mac GPU (Metal) automatically.
- **Deterministic:** the same input gives bit-identical output every time (CPU and Mac GPU).
- **Jev-compatible:** `decido serve` exposes the Jev 1.13 (TypeSafe "System One") HTTP API, so existing Jev clients work unchanged.

## Install
```bash
pip install decido-ai
decido build-runtime      # only on Linux / Intel Macs (one-time, needs cmake + a C++ compiler); Apple Silicon Macs: skip
```
NVIDIA GPU: `pip install "decido-ai[gpu]"` (adds torch + transformers), then `Decido(model, device="cuda")`.

## Quick start
```python
from decido import Decido

m = Decido("decido-ai/decido-1-fast-1.7b")      # downloads once from the Hub, then runs locally
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"]},
    },
)
# -> {'refund': {'yes': 0.99, 'no': 0.01}, 'team': {'billing': 0.94, 'shipping': 0.03, 'tech': 0.03},
#     'urgency': {'low': 0.24, 'normal': 0.44, 'urgent': 0.32}}
```

**Question formats**

| you write | question type |
|---|---|
| `"Is the customer asking for a refund?"` | yes / no |
| `{"q": "Which team?", "options": ["billing", "shipping"]}` | pick one |
| `{"q": "Which team?", "options": {"billing": "charges, refunds", "shipping": "delivery"}}` | pick one, with option descriptions |
| `{"q": "How urgent?", "scale": ["low", "normal", "urgent"]}` | ordered scale |
| `{"q": "...", "yes": "what yes means", "no": "what no means"}` | yes / no with definitions |

`m.predict({"state": ..., "questions": ...})` takes the full Jev 1.13 wire format (`noul`, `choice` with 2–255 options, `score`
with 2–10 levels) and returns Jev-style answers (`noul`; `choice` + `probabilities` + `confidence`; `score` + `legend`). The
document may be text or JSON and is treated as untrusted data (instructions inside it are not followed).

## Command line and HTTP server
```bash
decido models                                                     # the family, with scores and latency
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-26b-a4b --request request.json      # wire format in, wire format out
decido serve decido-ai/decido-1-26b-a4b --port 8080 --workers 2   # POST /v1/systemone, GET /v1/models, GET /health
```
The server binds to 127.0.0.1 by default; set `DECIDO_API_KEY` to require `Authorization: Bearer <key>`. Jev SDK users:
`TYPESAFE_BASE_URL=http://127.0.0.1:8080`.

## Models

| model | built on | runs on | six-group score (Jev 1.13 = 83.85) | latency, M4 Pro: CPU · Mac GPU (1k-token document, 5 questions) |
|---|---|---|---|---|
| [decido-1-26b-a4b](https://huggingface.co/decido-ai/decido-1-26b-a4b) | Gemma-4-26B-A4B | laptop (~30 GB RAM) · GPU | **85.38** | 4.1 s · 1.1 s |
| [decido-1-fast-1.7b](https://huggingface.co/decido-ai/decido-1-fast-1.7b) | Qwen3-1.7B | laptop (~3 GB RAM) | 73.01 | 0.64 s · 0.30 s |
| [decido-1-ultra-0.6b](https://huggingface.co/decido-ai/decido-1-ultra-0.6b) | Qwen3-0.6B | laptop (~1.5 GB RAM) | 62.16 | 0.41 s · 0.13 s |
| [decido-1-think-26b-a4b](https://huggingface.co/decido-ai/decido-1-think-26b-a4b) | Gemma-4-26B-A4B | GPU · laptop (slow) | **88.71** (GPU), most accurate | ~19 s · ~10 s / question |
| [decido-1-xl](https://huggingface.co/decido-ai/decido-1-xl) | DeepSeek-V4-Flash | 4× A100 80 GB | 87.25 (GPU) | GPU only |

Six-group score = mean over JevBench, Kev, OpenJev, Nimble, VitaminC and MASSIVE (the benchmark groups used to compare open
reproductions of TypeSafe's Jev 1.13; Jev's number is its published run). Per-group results, calibration (Brier / ECE),
option-order robustness, training details, disclosures and limitations are on each model card.

## Platforms
- **macOS on Apple Silicon (M1–M4):** prebuilt runtime included (llama.cpp). Runs on the Mac GPU (Metal) by default, 2–4× faster
  than CPU; `device="cpu"` reproduces the published CPU numbers bit for bit.
- **Linux / Intel macOS:** run `decido build-runtime` once (~3 min) — it downloads llama.cpp at the pinned commit and compiles
  the runtime into `~/.cache/decido/runtime` (cmake via `pip install cmake`, plus a C++ compiler). A prebuilt Linux runtime is
  coming in the next release.
- **NVIDIA GPU:** `Decido(..., device="cuda")` with the `gpu` extra runs the bf16 weights with transformers.
  Decido-1-XL: `pip install "decido-ai[xl]"`, one node with 4× A100 80 GB.

Environment variables: `DECIDO_THREADS` (CPU threads), `DECIDO_VERBOSE=1` (runtime logs), `DECIDO_VSERVE` (custom runtime binary),
`HF_HOME` (model download location).

## License
Apache-2.0. The CPU runtime links llama.cpp (MIT). Model licences: see each model card (Apache-2.0; Decido-1-XL: MIT).
