Metadata-Version: 2.4
Name: valen-sdk
Version: 0.4.0
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.

## 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.3.1

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

```sh
python -m pip install 'valen-sdk==0.3.1'
# Local CPU inference, Python 3.11+
python -m pip install 'valen-sdk[onnx]==0.3.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.3.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 follows; the Cookbook owns routing, thresholds and ranking:

```python
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](https://huggingface.co/Valen-Team/Valen-0.8B-ONNX), [2B](https://huggingface.co/Valen-Team/Valen-2B-ONNX) and [4B](https://huggingface.co/Valen-Team/Valen-4B-ONNX) cards for model selection, downloads and measured memory.

To install the SDK directly in your own project:

```bash
python -m pip install "valen-sdk[onnx]==0.3.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-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-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`:

```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:

```python
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:

```python
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](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/).
