Metadata-Version: 2.4
Name: valen-sdk
Version: 0.5.1
Summary: Typed local ONNX, HTTP and LLM-comparison access to Valen decisions
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/valen-team/valen-sdk-python
Project-URL: Source, https://github.com/valen-team/valen-sdk-python
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.9
Provides-Extra: onnx
Requires-Dist: onnxruntime<2,>=1.31; extra == "onnx"
Requires-Dist: numpy>=1.26; extra == "onnx"
Requires-Dist: packaging>=23; extra == "onnx"
Requires-Dist: tokenizers<1,>=0.22; extra == "onnx"
Requires-Dist: huggingface-hub<3,>=1; extra == "onnx"
Requires-Dist: Pillow>=10; extra == "onnx"
Requires-Dist: jinja2<4,>=3.1; extra == "onnx"
Provides-Extra: cuda
Requires-Dist: onnxruntime-gpu[cuda,cudnn]<2,>=1.31; extra == "cuda"
Requires-Dist: numpy>=1.26; extra == "cuda"
Requires-Dist: packaging>=23; extra == "cuda"
Requires-Dist: tokenizers<1,>=0.22; extra == "cuda"
Requires-Dist: huggingface-hub<3,>=1; extra == "cuda"
Requires-Dist: Pillow>=10; extra == "cuda"
Requires-Dist: jinja2<4,>=3.1; extra == "cuda"
Provides-Extra: video
Requires-Dist: av<20,>=16; extra == "video"
Requires-Dist: Pillow>=10; extra == "video"
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.115; extra == "server"
Requires-Dist: uvicorn<1,>=0.30; extra == "server"
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Dynamic: license-file

<p align="center">
  <a href="https://github.com/Valen-Team/Valen"><img src="assets/branding/valen-mark-white.png" alt="Valen" width="112"></a>
</p>
<h1 align="center">Valen Python SDK</h1>
<p align="center"><strong>Fast Decisions. Continuous Evolution.</strong></p>
<p align="center">Bring Valen’s multimodal System One decisions to Python.</p>

<p align="center">
  <strong>English</strong> · <a href="README_zh.md">简体中文</a><br>
  <a href="https://github.com/Valen-Team/Valen">Valen</a> · <a href="https://valen-team.github.io/">Try Valen</a> · <a href="https://valen-team.github.io/docs/">Documentation</a> · <a href="https://huggingface.co/Valen-Team">Models</a>
</p>

<p align="center">
  <strong>Python SDK</strong> · <a href="https://github.com/Valen-Team/valen-sdk-js">JavaScript SDK</a> · <a href="https://github.com/Valen-Team/valen-sdk-cpp">C++ integration</a>
</p>

[Valen](https://github.com/Valen-Team/Valen) is a multimodal System One decision model that returns structured decision probabilities for your tasks. This repository provides the Python SDK for Valen.

Run text, image and video decisions inside your Python application. Get categories, yes/no probabilities and scores for ticket routing, content screening and ranking. Use local CPU inference, NVIDIA CUDA or a remote HTTP service. Local inference uses ONNX Runtime without PyTorch or Transformers. `Valen.remote` on the hosted API reaches Valen-Decision-1.5 0.8B, 2B and 4B through the model IDs `valen-0.8b`, `valen-2b` and `valen-4b`; `Valen.local` runs the Valen-Decision-1.5 ONNX bundles (`Valen-Decision-1.5-0.8B-ONNX`, `2B`, `4B`, `9B`, `27B`) with results that match the native model, answers `bbox` questions with them, and runs the Valen-Decision-1.0 ONNX models (`Valen-0.8B-ONNX`, `Valen-2B-ONNX`, `Valen-4B-ONNX`).

## Reliability and integration controls

Typed methods validate returned answers against the questions you sent. Invalid or incomplete responses raise `ValenResponseError` with a field path; raw `predict` retains the compatibility interface.

```python
from valen_sdk import Valen, Noul

with Valen.remote("https://api.valen-team.workers.dev/v1",
                  timeout=10, total_timeout=25,
                  on_event=lambda event: print(event)) as client:
    response = client.system_one("The order arrived.", {
        "arrived": Noul(instructions="The order arrived.")
    })
```

Durations are seconds. `total_timeout` includes retry waits. For cancellable concurrent LLM comparisons, use `async with AsyncValen.llm(provider, model, ...)`; it supports the same question and response interfaces, normalization diagnostics and correction accounting as `Valen.llm`. `normalize_probabilities=False` rejects LLM distributions that need rescaling.

Pass `http_client=` to borrow an existing `httpx.Client` / `httpx.AsyncClient`; closing Valen leaves that client open. Pass `on_event=` to local clients for loading stages, inspect `client.info`, and use `client.warmup(request)` to load lazy graphs with a representative request.

See the [complete behavior and timeout contract](contracts/README.md), [runnable reliability example](examples/reliability.py) and [upgrade notes](CHANGELOG.md). Events exclude input bodies; explicit LLM debug histories can contain them.

## Complete application tutorials

Complete workflows are maintained in the [official Cookbook](https://valen-team.github.io/cookbook/): [ticket routing](https://valen-team.github.io/cookbook/ticket-routing/), [when no option fits](https://valen-team.github.io/cookbook/unknown-categories/), [product-image screening](https://valen-team.github.io/cookbook/product-screening/) and [video tagging](https://valen-team.github.io/cookbook/video-tagging/). Code, samples and measured outputs share one source. This repository retains SDK interface and installation examples. `Valen.local` loads ONNX; connect to GGUF services over HTTP. C++ support remains scoped by this repository's reference.


## Stable version 0.5.1

Published on [PyPI](https://pypi.org/project/valen-sdk/0.5.1/). Install the base package for HTTP clients, or the ONNX extra for local inference:

```sh
python -m pip install 'valen-sdk==0.5.1'
# Local CPU inference, Python 3.11+
python -m pip install 'valen-sdk[onnx]==0.5.1'
```

The 0.2.0 [GitHub artifacts](https://github.com/Valen-Team/valen-sdk-python/releases/tag/v0.2.0) remain available. PyPI publication uses GitHub Trusted Publishing without a long-lived PyPI token; see [releasing](RELEASING.md). JavaScript SDK npm availability is tracked separately.

For a first try, use the [web experience or free API](https://valen-team.github.io/). See [version selection](https://valen-team.github.io/docs/valen/choosing/).

## Quick start

The repository example below needs Python 3.11+ and Git. It runs on CPU; no GPU is required. Installing the PyPI wheel itself does not require Git:

```bash
git clone --branch v0.5.1 --depth 1 https://github.com/valen-team/valen-sdk-python.git
cd valen-sdk-python
python -m pip install ".[onnx]"
python examples/local_decisions.py
```

A minimal protocol call with Valen-Decision-1.5 follows (the scripts in `examples/` use the same 0.8B bundle); the Cookbook owns routing, thresholds and ranking:

```python
from valen_sdk import Valen

with Valen.local("Valen-Team/Valen-Decision-1.5-0.8B-ONNX", variant="fp32") as client:
    result = client.decisions(input="A cat is on the sofa.", questions=[
        {"name": "cat", "type": "predicate", "instructions": "A cat is present."},
    ])
    print(result.by_name("cat").probability)
```

The first run downloads and caches the selected variant; the full 0.8B FP32 download is about 3.52 GB. Later runs reuse the cache. See the Valen-Decision-1.5 [0.8B](https://huggingface.co/Valen-Team/Valen-Decision-1.5-0.8B-ONNX), [2B](https://huggingface.co/Valen-Team/Valen-Decision-1.5-2B-ONNX), [4B](https://huggingface.co/Valen-Team/Valen-Decision-1.5-4B-ONNX), [9B](https://huggingface.co/Valen-Team/Valen-Decision-1.5-9B-ONNX) and [27B](https://huggingface.co/Valen-Team/Valen-Decision-1.5-27B-ONNX) cards for model selection and downloads, and the [ONNX guide](https://valen-team.github.io/docs/valen/onnx/#models-and-variants) for sizes and validation against the native model.

To install the SDK directly in your own project:

```bash
python -m pip install "valen-sdk[onnx]==0.5.1"
```

## Images and video

Minimal local media interface examples remain in `examples/`. Complete inputs, dependencies, commands, outputs and uncertainty handling live in [product screening](https://valen-team.github.io/cookbook/product-screening/), [video tagging](https://valen-team.github.io/cookbook/video-tagging/) and [direct-video basics](https://valen-team.github.io/cookbook/local-inference/). Shared `Valen/assets/cookbook/` URLs remain stable.

## Local HTTP service

Start a CPU service on your machine:

```bash
python -m pip install ".[onnx,server]"
valen serve --model Valen-Team/Valen-Decision-1.5-0.8B-ONNX --model-name valen --port 8000
```

In another terminal, run `python examples/http_client.py`, or call the service from your application:

```python
from valen_sdk import Valen

with Valen.remote("http://127.0.0.1:8000/v1", model="valen") as client:
    result = client.decisions(
        input="Please send my order to my new address.",
        questions=[{"name": "change_address", "type": "predicate",
                    "instructions": "Is the customer requesting a delivery address change?"}],
    )
    print("Address change probability:", result.by_name("change_address").probability)
```

For an existing Valen service, install just the base SDK; the HTTP client does not need ONNX Runtime. The `Valen.remote` URL ends in `/v1`; pass `api_key` when the server uses authentication. `AsyncValen` provides an asynchronous HTTP client with the same `api_key`, `timeout`, `max_retries` and `headers` options. Failures raise `ValenAPIError` with `status_code`, `request_id` and the service's error detail.

## SystemOne

Decisions uses a question list; SystemOne uses questions keyed by ID. Both formats run the same model. Run `python examples/system_one.py` independently:

```python
from valen_sdk import Choice, Noul, Score, Valen

with Valen.local("Valen-Team/Valen-Decision-1.5-0.8B-ONNX", variant="fp32") as client:
    result = client.system_one(
        "I moved. Please ship my order to 12 Elm Street instead.",
        {
            "intent": Choice(instructions="What does the customer want?", criteria={
                "address": "Change the delivery address", "cancel": "Cancel the order"}),
            "change_address": Noul(instructions="The customer requests a delivery address change."),
            "explicitness": Score(instructions="How explicit is the request?", criteria=[
                "No request", "Asks whether a change is possible", "Explicitly requests a change"]),
        },
    )
    print("Intent:", result.answers["intent"].choice)
    print(f"Address change probability: {result.answers['change_address'].noul:.3f}")
    print(f"Explicitness score (0–2): {result.answers['explicitness'].score:.3f}")
```

## Bbox questions

A `bbox` question locates something in an image and returns `bbox` `[x1, y1, x2, y2]`, `point` `[x, y]` and `confidence`, normalized to 0–1. Local inference answers it with the grounding graph of a Valen-Decision-1.5 bundle, next to other question types in one request. Download the [example image](https://valen-team.github.io/cookbook/code/media/mug-counter.jpg) as `mug-counter.jpg`:

```python
from valen_sdk import Bbox, Noul, Valen

with Valen.local("Valen-Team/Valen-Decision-1.5-0.8B-ONNX", variant="fp32") as client:
    result = client.system_one(
        {"messages": [{"role": "user", "content": [
            {"type": "image_url", "image_url": {"url": "mug-counter.jpg"}}]}]},
        {"mug": Bbox(instructions="The blue mug.", image=0),
         "full": Noul(instructions="The mug has coffee in it.")},
    )
    mug = result.bboxes["mug"]
    print(mug.bbox, mug.point, mug.confidence)
    print(result.nouls["full"].noul)
```

Decisions requests use `{"name": "mug", "type": "bbox", "instructions": "The blue mug.", "image": 0}` and return `BboxAnswer` through `result.by_name("mug")`. `image` is the zero-based index of the image to search. See [bbox questions](https://valen-team.github.io/docs/valen/onnx/#bbox-questions) for measured output.

## Compare with an LLM

`Valen.llm` sends the same `system_one` or `decisions` request to a general LLM and returns the same typed response, so routing rules, thresholds and tests run unchanged against either. Use it to measure what Valen saves on your own data. It ships in the base package; video inputs need `valen-sdk[video]`. Run `python examples/llm_compare.py`:

```python
from valen_sdk import Choice, Valen

questions = {"queue": Choice(instructions="Which team should handle this ticket?", criteria={
    "billing": "Payments, charges and refunds", "technical": "Bugs and crashes in the app"})}
valen = Valen.remote("https://api.valen-team.workers.dev/v1", model="valen-2b")
llm = Valen.llm("openai", "gpt-4o-mini")  # reads OPENAI_API_KEY
for client in (valen, llm):
    result = client.system_one("I was charged twice.", questions)
    print(result.model, result.choices["queue"].choice, result.usage.input_tokens)
```

`provider` is `openai` (Chat Completions, also any OpenAI-compatible endpoint through `base_url`), `anthropic` or `gemini`; keys come from `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` or `GEMINI_API_KEY`, or `api_key=`. Question IDs are not sent to the LLM. Images are sent inline; videos as evenly spaced frames.

| Option | Use |
| --- | --- |
| `structured` | Default `True` uses the provider's JSON Schema output; `False` asks for JSON in the prompt, for endpoints without structured output |
| `answer_mode` | `probabilities` (default): the LLM states a probability per candidate; `discrete`: it picks one candidate, returned as probability 1 |
| `n_retry_malformed` | Corrective retries when the output does not match the schema, default 2 |
| `max_retries` | Retries for rate limits, overload and connection failures, default 2 |
| `max_tokens` | Output limit; Anthropic defaults to 4096 |
| `video_frames` | Frames sent per video, default 8 |
| `extra_body` | Extra provider fields, such as `{"temperature": 0}` or `{"reasoning_effort": "low"}` |

LLM probabilities are the model's stated estimates, not Valen's candidate scores; compare decisions and accuracy on labelled cases rather than probability values. `usage` adds `n_retries`, `n_retries_malformed` and `latency`, summing tokens over every attempt (`None` when the endpoint omits a count). `debug["llm_attempts"]` records each provider request and response in order; post a `request` to the same endpoint to replay it. Truncated output, refusals and context overflow raise `ValenAPIError` without corrective retries, with the attempts in `error.debug`.

## CUDA

In a separate environment, install `python -m pip install ".[cuda]"`, then select the CUDA variant. Every Valen-Decision-1.5 bundle, 0.8B to 27B, includes `cuda-fp16`:

```python
from valen_sdk import Valen

with Valen.local(
    "Valen-Team/Valen-Decision-1.5-0.8B-ONNX", variant="cuda-fp16",
    providers=[("CUDAExecutionProvider", {"use_tf32": "0"}), "CPUExecutionProvider"],
) as client:
    result = client.decisions(
        input="Please send my order to my new address.",
        questions=[{"name": "change_address", "type": "predicate",
                    "instructions": "Is the customer requesting a delivery address change?"}],
    )
    print(result.by_name("change_address").probability)
```

## Cache and options

After downloading the model, run from the cache offline:

```python
from valen_sdk import Valen

with Valen.local("Valen-Team/Valen-Decision-1.5-0.8B-ONNX", local_files_only=True) as client:
    result = client.decisions(
        input="Please send my order to my new address.",
        questions=[{"name": "change_address", "type": "predicate",
                    "instructions": "Is the customer requesting a delivery address change?"}],
    )
    print(result.by_name("change_address").probability)
```

You can also pass a local directory, such as `Valen.local("./models/Valen-Decision-1.5-0.8B-ONNX")`.

| Option | Use |
| --- | --- |
| `variant` | CPU default `fp32`; `q8-mlp` for a smaller download; `cuda-fp16` for CUDA |
| `cache_dir` / `revision` | Choose a cache location or HF model revision |
| `num_threads` | CPU inference threads, default 4 |
| `execution` | Default `shared_state` shares one forward pass within a request; `question` compiles each question separately |
| `temperature` | Request temperature, default 1 |
| `media_kwargs` | Set image size, video frame count or FPS |

One local client executes requests serially. `predict` accepts raw requests and returns dictionaries; `decisions` and `system_one` return typed results. HTTP-only clients support Python 3.10+.

## More

[JavaScript / browser SDK](https://github.com/valen-team/valen-sdk-js) · [C++ text integration](https://github.com/valen-team/valen-sdk-cpp) · [Free API documentation](https://valen-team.github.io/docs/valen/api/) · [Agent skill](https://github.com/Valen-Team/skills) · [llms.txt](https://valen-team.github.io/llms.txt)

Apache-2.0. See [LICENSE](LICENSE) and [third-party notices](THIRD_PARTY_NOTICES.md).

User guides are maintained only on the website: [Documentation](https://valen-team.github.io/docs/) · [Fine-tuning](https://valen-team.github.io/docs/valen/training/) · [Probabilities](https://valen-team.github.io/docs/valen/probabilities/) · [Cookbook](https://valen-team.github.io/cookbook/).
