Valen Python SDK

Fast Decisions. Continuous Evolution.

Bring Valen’s multimodal System One decisions to Python.

English · 简体中文
Valen · Try Valen · Documentation · Models

Python SDK · JavaScript SDK · C++ integration

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.

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.

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, runnable reliability example and upgrade notes. Events exclude input bodies; explicit LLM debug histories can contain them.

Complete application tutorials

Complete workflows are maintained in the official Cookbook: ticket routing, when no option fits, product-image screening and 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.4.0

Published on PyPI. Install the base package for HTTP clients, or the ONNX extra for local inference:

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

The 0.2.0 GitHub artifacts remain available. PyPI publication uses GitHub Trusted Publishing without a long-lived PyPI token; see releasing. JavaScript SDK npm availability is tracked separately.

For a first try, use the web experience or free API. See version selection.

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:

git clone --branch v0.4.0 --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 follows; the Cookbook owns routing, thresholds and ranking:

from valen_sdk import Valen

with Valen.local("Valen-Team/Valen-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.51 GB. Later runs reuse the cache. See the 0.8B, 2B and 4B cards for model selection, downloads and measured memory.

To install the SDK directly in your own project:

python -m pip install "valen-sdk[onnx]==0.4.0"

Images and video

Minimal local media interface examples remain in examples/. Complete inputs, dependencies, commands, outputs and uncertainty handling live in product screening, video tagging and direct-video basics. Shared Valen/assets/cookbook/ URLs remain stable.

Local HTTP service

Start a CPU service on your machine:

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

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

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:

from valen_sdk import Choice, Noul, Score, Valen

with Valen.local("Valen-Team/Valen-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}")

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:

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:

from valen_sdk import Valen

with Valen.local(
    "Valen-Team/Valen-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:

from valen_sdk import Valen

with Valen.local("Valen-Team/Valen-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-0.8B-ONNX").

Option	Use
variant	CPU default fp32; q8-mlp for lower memory; 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 · C++ text integration · Free API documentation · Agent skill · llms.txt

Apache-2.0. See LICENSE and third-party notices.

User guides are maintained only on the website: Documentation · Fine-tuning · Probabilities · Cookbook.