### Example

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Documentation for the Example constructor.

```APIDOC
## Example

### Description
Constructs an example demonstration for a question. The example is replayed into the prompt as the answer the model is asked to imitate.

### Constructor
`Example(state=..., answer=..., probabilities=None)`

### Parameters
- **state** (any JSON-serializable value) - Required - The input state for the example. Must be JSON-serializable; non-serializable values are refused.
- **answer** (str, int, or bool) - Required - The answer to the question. Can be a label (e.g., `"B"`), a `Choice` criteria key, a `Score` level index, or a bool for `Noul`.
- **probabilities** (dict) - Optional - A dictionary of probabilities. Only read by `method="structured"`. Defaults to a one-hot distribution over `answer`.

### Validation
- `probabilities` must carry exactly the option keys of a `Choice`, the level indexes of a `Score`, or a `True`/`False` key for a `Noul`. Wrong key sets raise `InvalidQuestionError`.
- Values must be finite and `>= 0`. For `Noul`, values must be in `[0, 1]`.
- Non-finite numbers or non-JSON-serializable `state` are refused.
```

--------------------------------

### Install, pull models, and serve ollaya

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Install ollaya 0.7.0, add its binary to PATH, pull the laya:en and laya:typed-decisions models, then start the server on 127.0.0.1:11435. The installer does not require root and installs to ~/.local.

```bash
curl -fsSL https://ollaya.dev/install.sh | sh      # 0.7.0; no root installs to ~/.local
export PATH="$HOME/.local/bin:$PATH"
ollaya pull laya:en
ollaya pull laya:typed-decisions
ollaya serve                                       # 127.0.0.1:11435
```

--------------------------------

### Development setup with uv, including pytest

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Set up the development environment for jevper. Clones the repository, creates a virtual environment with uv, installs with test extras, and runs the test suite.

```sh
git clone https://github.com/zhulinchng/jevper && cd jevper
uv venv && uv pip install -e '.[test]'
pytest -q
```

--------------------------------

### Install and run MLflow integration tests

Source: https://github.com/zhulinchng/jevper/blob/main/docs/mlflow.md

Install the test and MLflow extras, then run the MLflow integration suite. The suite skips unless MLflow is installed.

```sh
uv pip install -e '.[test,mlflow]'    # mlflow[gateway,langchain] + openai + anthropic + pytest
pytest tests/test_mlflow.py -q
```

--------------------------------

### Example source resolution flowchart (Mermaid)

Source: https://github.com/zhulinchng/jevper/blob/main/docs/few-shot.md

Flowchart showing the precedence of example sources: question.examples, then system_one, then SystemOneClient. The first non-empty level wins.

```mermaid
flowchart TD
    A["question.examples"] -->|"non-empty"| U["use them"]
    A -->|"empty"| B["system_one(examples=...)"]
    B -->|"mapping entry for this question id, or the bare sequence"| U
    B -->|"empty"| C["SystemOneClient(examples=...)"]
    C -->|"mapping entry, or the bare sequence"| U
    C -->|"empty"| D["no examples for this question"]
```

--------------------------------

### Run duck client example

Source: https://github.com/zhulinchng/jevper/blob/main/docs/complete-example.md

Runs the duck client example with no server, using a constant model.

```sh
python examples/duck_client.py
```

--------------------------------

### Install and run kev from source

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Install kev from source because the PyPI package named 'kev' is a different project (K.E.V. ORM). The serve command runs the Kev-4B model on port 8009; the first run downloads the adapter and base model from HuggingFace.

```bash
git clone https://github.com/jaredpalmer/kev.git && cd kev
pip install -e ".[serve]"
python -m kev.serve --run jaredpalmer/kev-4b --port 8009
```

--------------------------------

### Install and run CLM with vLLM encoder

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Install contrastive-lm and start the CLM server with a vLLM-served Qwen3-8B encoder. The encoder runs on port 8090 with pooling runner and last-token embeddings; clm-serve serves the API and playground on :8700 and fetches the 75 MB head into ~/.cache/clm/ on first run.

```bash
pip install contrastive-lm

# the encoder: Qwen3-8B, pooling runner, last-token embeddings
vllm serve Qwen/Qwen3-8B --served-model-name qwen3-8b --runner pooling \
  --max-model-len 2048 --port 8090 &

# the API and playground on :8700; fetches the 75 MB head into ~/.cache/clm/ on first run
clm-serve
```

--------------------------------

### Install incident-triage with uv

Source: https://github.com/zhulinchng/jevper/blob/main/examples/incident-triage/README.md

Creates a virtual environment and installs the project in editable mode from the wheel.

```sh
uv venv && uv pip install -e .
```

--------------------------------

### Define few-shot examples with Example(state, answer, probabilities)

Source: https://github.com/zhulinchng/jevper/blob/main/docs/few-shot.md

Constructs two few-shot examples for the System One wire format. The first uses a label answer; the second includes a probabilities distribution, which is only rendered by method="structured" but is validated for every method before any provider call.

```python
Example(state="Charged twice for one order", answer="billing")
Example(state="Login fails after reset", answer="technical", probabilities={"billing": 0.05, "technical": 0.9})
```

--------------------------------

### Attach few-shot examples at question, call, and constructor levels

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Attach few-shot examples as chat turns at three levels: question, per call, and constructor. Precedence is question → per call → constructor, and the first non-empty level wins. `examples` is excluded from `model_dump()`, so question dumps keep exactly the Jev wire keys.

```python
from jevper import Choice, Example, SystemOneClient

question = Choice(
    criteria={"billing": "...", "technical": "..."},
    examples=[Example(state="Charged twice for one order", answer="billing")],
)

client = SystemOneClient(OpenAI(), model="gpt-5.6-terra",
                         examples=[Example(state="Login fails", answer="technical")])  # fallback for every question

client.system_one(state=..., questions={"intent": question},
                  examples={"intent": [...]})  # or a bare sequence for all questions
```

--------------------------------

### Install jevper in editable mode with uv

Source: https://github.com/zhulinchng/jevper/blob/main/docs/getting-started.md

Installs the package in editable mode for a local checkout, using uv.

```sh
uv pip install -e .
```

--------------------------------

### Install dependencies for complete_call.py

Source: https://github.com/zhulinchng/jevper/blob/main/docs/complete-example.md

Install the required packages. The comment notes that the complete_call.py program uses the OpenAI client and Chat Completions only; to use Anthropic's Messages surface, install anthropic and pin api="messages".

```sh
pip install jevper openai
# The complete_call.py program uses the OpenAI client and Chat Completions only.
# To use Anthropic's Messages surface, install anthropic and pin api="messages".
```

--------------------------------

### Create a decision with SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/docs/decisions.md

Use client.decisions.create with a choice question. The response contains answers in question order and a usage object. The example prints the answer name, choice, confidence, probabilities, and total tokens.

```python
from openai import OpenAI
from jevper import SystemOneClient

client = SystemOneClient(OpenAI(), model="gpt-5.6-terra")

decision = client.decisions.create(
    input="I was charged twice for the same subscription this month.",
    questions=[
        {
            "type": "choice",
            "name": "department",
            "instructions": "Which department should handle this complaint?",
            "choices": [
                {"value": "billing", "description": "Payments, invoices, and refunds."},
                {"value": "technical", "description": "Problems using the product."},
                {"value": "sales", "description": "Pricing, plans and upgrades."},
            ],
        }
    ],
)

answer = decision.answers[0]
print(answer.name, answer.choice, answer.confidence)
print([(entry.value, entry.probability) for entry in answer.probabilities])
print(decision.usage.total_tokens)
```

--------------------------------

### SystemOneClient with OpenAI base_url and endpoint name as model

Source: https://github.com/zhulinchng/jevper/blob/main/docs/mlflow.md

Client setup for the standalone gateway. The base_url points to the gateway's /v1 root and the model must be the endpoint name (local-chat), not the backend model name; a wrong name is refused by the gateway. With method="auto", the client pays one 404 for the missing /v1/responses route and answers on chat.

```python
client = SystemOneClient(
    OpenAI(base_url="http://127.0.0.1:5000/v1", api_key="dummy"),   # the route's /v1 root
    model="local-chat",                                             # the endpoint name is the model
    method="auto",
)
```

--------------------------------

### Usage constructor example

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Shows the Usage object fields. A token count is None when any constituent call omitted it; a reported 0 is preserved. n_calls counts analysis passes and corrective retries, n_retries counts transient-failure retries only, and latency is wall-clock seconds for the whole system_one call.

```python
Usage(input_tokens=None, output_tokens=None, reasoning_tokens=None, cached_tokens=None, n_calls=0, n_retries=0, latency=0.0)
```

--------------------------------

### Install jevper with pip

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Install the jevper package with pip. Requires Python 3.10 or newer and the pydantic>=2.7 runtime dependency.

```sh
pip install jevper
```

--------------------------------

### Install jevper agent skill

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Add the official Agent skill for jevper using npx. This is an optional integration for agent environments.

```sh
npx skills add zhulinchng/jevper-skill
```

--------------------------------

### list_models() / alist_models()

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Documentation for the list_models() and alist_models() methods, which retrieve the models offered by the deployment from the System One endpoint's GET /v1/models.

```APIDOC
## list_models() / alist_models()

### Description
Lists the models offered by the deployment, read from the System One endpoint's `GET /v1/models` and parsed as the service's own OpenAPI declares it. The synchronous version is `list_models()` and the async twin is `alist_models()`.

### Method
GET

### Endpoint
/v1/models

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **models** (array) - List of model metadata objects.
  - **name** (string) - The model name.
  - **description** (string) - Model description; defaults to `""` if omitted.
  - **release_date** (string) - Release date; defaults to `None` if omitted.

#### Response Example
{
  "models": [
    {
      "name": "model-name",
      "description": "model description",
      "release_date": "2024-01-01"
    }
  ]
}

### Error Handling
- If the gateway answers with a different shape (e.g., OpenAI-style `{"object": "list", "data": [...]}`), the call raises `MalformedAnswerError`.
- Failures follow the `retry` policy and arrive as a `ProviderError` carrying the provider's status.
- A client whose `get` is a coroutine (or is not) is refused before the request, naming the class to use instead.
- The SDK's own retry loop is switched off for this request, so one call is one policy rather than two nested ones.
```

--------------------------------

### InvalidQuestionError for example answer not matching any option

Source: https://github.com/zhulinchng/jevper/blob/main/docs/few-shot.md

Error raised when an example answer does not match any option of the question. Shown as a validation failure before any provider call.

```text
InvalidQuestionError: question 'intent': example 1: answer 'nope' does not match any option of this question
```

--------------------------------

### Call ollaya /v1/systemone with SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Point a SystemOneClient at ollaya's /v1 base URL to call the TypeSafe-compatible /v1/systemone endpoint. The api_key is never checked unless the daemon was started with OLLAYA_API_KEY set; any non-empty string works. The response.answers["refund"].noul value shown was measured 2026-09-26.

```python
from openai import OpenAI
from jevper import Noul, SystemOneClient

with SystemOneClient(
    OpenAI(base_url="http://127.0.0.1:11435/v1", api_key="ollama"),
    model="laya:en",
    api="systemone",
) as client:
    response = client.system_one(
        state="I was charged twice for my subscription this month.",
        questions={"refund": Noul(instructions="Does the customer ask for a refund?")},
    )

response.answers["refund"].noul   # 0.8551, measured 2026-09-26
```

--------------------------------

### jevper_chat_model.py: MLflow ChatModel fixture

Source: https://github.com/zhulinchng/jevper/blob/main/docs/mlflow.md

Example fixture for hosting jevper as an MLflow ChatModel. The client is built in load_context (not pickled) and the predict method returns a ChatCompletionResponse. Logged with python_model="jevper_chat_model.py".

```python
# jevper_chat_model.py — logged with python_model="jevper_chat_model.py"
import mlflow
from mlflow.pyfunc import ChatModel
from mlflow.types.llm import ChatChoice, ChatCompletionResponse, ChatMessage
from jevper import Choice, SystemOneClient

class JevperChatModel(ChatModel):
    def load_context(self, context):                     # the client is built here, not pickled
        from openai import OpenAI
        config = context.model_config or {}
        self.client = SystemOneClient(
            OpenAI(base_url=config["base_url"], api_key="x"), model=config["model"],
            api="chat_completions", method="structured",
        )

    def predict(self, context, messages, params):
        state = "\n".join(str(getattr(m, "content", "")) for m in messages)
        answer = self.client.system_one(state=state, questions={"intent": Choice(criteria={...})})
        return ChatCompletionResponse(model="jevper", choices=[ChatChoice(
            index=0, message=ChatMessage(role="assistant", content=answer.answers["intent"].choice or ""),
            finish_reason="stop")])

mlflow.models.set_model(JevperChatModel())
```

--------------------------------

### Use system_one for the underlying Jev interface

Source: https://github.com/zhulinchng/jevper/blob/main/docs/index.md

Call client.system_one directly to get answers keyed by your own question IDs. The response can be converted to the Decisions schema with response.to_decision().

```python
from jevper import Choice, SystemOneClient

client = SystemOneClient(OpenAI(), model="gpt-5.6-terra")

response = client.system_one(
    state="I was charged twice for the same subscription this month.",
    questions={
        "intent": Choice(
            instructions="Pick the intent of the message.",
            criteria={
                "billing": "money, invoices, refunds, charges",
                "technical": "errors, crashes, login or performance problems",
                "sales": "pricing, plans, purchasing, upgrades",
            },
        )
    },
)

answer = response.answers["intent"]
print(answer.choice, answer.probabilities, answer.confidence)
```

--------------------------------

### Routing and LayaExtras example

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Shows the shape of the Routing and LayaExtras objects returned on the Ollaya native endpoint. route is the stable key to branch on; reason is informative prose that may change and is never parsed. LayaExtras is attached to every answer when extras=["laya"] is set, with act_probability None for models without an act head.

```python
Routing(router="laya:latest", model="laya:en", route="english", reason="English Latin text")
LayaExtras(confidence=0.615, act_probability=1.0)
```

--------------------------------

### Build and preview documentation with MkDocs

Source: https://github.com/zhulinchng/jevper/blob/main/docs/contributing.md

Run the strict build from the repository root to validate the documentation, then preview the rendered site locally. The build must pass before a documentation change is submitted.

```sh
uv run --extra docs mkdocs build --strict
```

```sh
uv run --extra docs mkdocs serve
```

--------------------------------

### SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Constructor documentation for the SystemOneClient class, including parameters and usage notes.

```APIDOC
## SystemOneClient

### Description
Creates a client for the Jev service, wrapping an underlying OpenAI or Anthropic SDK client. It provides a unified interface for making decisions via the Decisions API.

### Constructor
```python
SystemOneClient(client, *, model, method="auto", api="auto", reasoning=None, examples=(),
                structured_outputs=True, normalize_probabilities=True, top_logprobs=20,
                max_concurrency=8, n_retry_malformed=1, retry=None, temperature=None,
                extra_body=None, extra_headers=None, prompt_cache_key=None,
                native=False, noul_requires_question=True)
```

### Parameters
- **client** (object) - Required - Any object exposing `responses.create`, `chat.completions.create` and/or `messages.create` (or `post` when `api="systemone"`). The client stays owned by the caller.
- **model** (str) - Required - Model id sent with every call; overridable per `system_one` call.
- **method** (str) - Optional - Default `"auto"`. One of `"auto"`, `"logprobs"`, `"grammar"`, `"structured"` or `"discrete"`.
- **api** (str) - Optional - Default `"auto"`. One of `"auto"`, `"chat_completions"`, `"responses"` or `"messages"`.
- **reasoning** (ReasoningConfig) - Optional - Default `None`. A `ReasoningConfig`; `None` disables reasoning entirely.
- **examples** (tuple or dict) - Optional - Default `()`. Default few-shot examples: a sequence for all questions, or a mapping keyed by question id.
- **structured_outputs** (bool) - Optional - Default `True`.
- **normalize_probabilities** (bool) - Optional - Default `True`.
- **top_logprobs** (int) - Optional - Default `20`.
- **max_concurrency** (int) - Optional - Default `8`.
- **n_retry_malformed** (int) - Optional - Default `1`.
- **retry** (RetryPolicy) - Optional - Default `None`.
- **temperature** (float) - Optional - Default `None`.
- **extra_body** (dict) - Optional - Default `None`.
- **extra_headers** (dict) - Optional - Default `None`.
- **prompt_cache_key** (str) - Optional - Default `None`.
- **native** (bool) - Optional - Default `False`.
- **noul_requires_question** (bool) - Optional - Default `True`.

### Notes
- Only `client` is positional; every other option is keyword-only.
- Unknown keyword arguments raise `TypeError` from the constructor.
- The client object must not be asynchronous when using `SystemOneClient`; use `AsyncSystemOneClient` for async clients.
- The client's own retry loop is disabled when used through this client; `RetryPolicy` is the only retry loop.
- The `responses` surface speaks both OpenAI's Responses API and the OpenResponses specification.

### Example
```python
from jevper import SystemOneClient
from openai import OpenAI

client = OpenAI(base_url="https://api.typesafe.ai/v1", api_key="...")
system_one = SystemOneClient(client, model="gpt-4o")
```
```

--------------------------------

### Python client for opencode Zen with SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/docs/jev-comparison.md

Configures SystemOneClient to point at the opencode Zen host. The base URL must be the host, not the endpoint, because jevper appends /systemone itself. Using the full endpoint causes a 404 with an HTML page reported as ProviderError.

```python
client = SystemOneClient(
    OpenAI(base_url="https://opencode.ai/zen/v1", api_key=key),
    model="jev-1.13-free",
    api="systemone",
)
```

--------------------------------

### model_dump() excludes examples

Source: https://github.com/zhulinchng/jevper/blob/main/docs/few-shot.md

Shows that examples are excluded from the dump because the field is declared with Field(exclude=True). The output confirms the dump contains only type, instructions, and criteria.

```python
Choice(criteria={"billing": "...", "technical": "..."}, examples=[...]).model_dump()
# {"type": "choice", "instructions": None, "criteria": {"billing": "...", "technical": "..."}}
```

--------------------------------

### Connect to kev with SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Configure a SystemOneClient to talk to a local kev server. The base_url points at kev's /v1 endpoint and the model is set to kev-latest; the api parameter is "systemone" to match TypeSafe's System One API.

```python
from openai import OpenAI
from jevper import SystemOneClient

client = SystemOneClient(
    OpenAI(base_url="http://127.0.0.1:8009/v1", api_key="local"),
    model="kev-latest",
    api="systemone",
)
```

--------------------------------

### Connect jevper to a local server with SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Connects jevper to a local OpenAI-compatible server (Ollama at 127.0.0.1:11434) by passing a custom base_url and api_key. Uses extra_body to disable thinking and reads a real probability distribution from the server's logprobs.

```python
from openai import OpenAI
from jevper import Choice, SystemOneClient

client = SystemOneClient(
    OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="local"),
    model="qwen3.5:9b",
    extra_body={"reasoning": {"effort": "none"}},  # Responses thinking off; see below
)

response = client.system_one(
    state="I was charged twice for the same subscription this month.",
    questions={
        "intent": Choice(
            criteria={
                "billing": "money, invoices, refunds, charges",
                "technical": "errors, crashes, login or performance problems",
                "sales": "pricing, plans, purchasing, upgrades",
            }
        )
    },
)

response.answers["intent"].probabilities  # a real distribution, read from the server's logprobs
```

--------------------------------

### SystemOneClient with OpenAI gpt-5.6 for prompt caching

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Create a SystemOneClient for OpenAI's gpt-5.6 model. Call system_one twice with different states but the same rubric to demonstrate prompt caching: the shared prefix is reused. The client is shaped so the state comes last, enabling prefix caching.

```python
client = SystemOneClient(OpenAI(), model="gpt-5.6")

client.system_one(state=record_a, questions=rubric)
client.system_one(state=record_b, questions=rubric)   # the shared prefix is reused
```

--------------------------------

### Python client for System One with openai and jevper

Source: https://github.com/zhulinchng/jevper/blob/main/docs/jev-comparison.md

Creates a SystemOneClient using an OpenAI client with a custom base URL and the systemone API. The client object is duck-typed, so any object with post(path, body=…, cast_to=…) works. The model is set to "jev-latest" and the api to "systemone".

```python
from openai import OpenAI
from jevper import Choice, Noul, SystemOneClient

client = SystemOneClient(
    OpenAI(base_url="https://api.typesafe.ai/v1", api_key=key), model="jev-latest", api="systemone"
)

response = client.system_one(
    state="I was charged twice for the same order. Can someone look into this?",
    questions={
        "refund": Noul(instructions="Is the customer asking for a refund?"),
        "team": Choice(instructions="Which team should handle this?",
                       criteria={"billing": "Payments", "support": "Customer problems"}),
    },
)
```

--------------------------------

### Run kev live integration tests

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Run the live integration tests for kev. These tests require KEV_BASE_URL and KEV_MODEL to be set; they verify that kev answers three typed questions in one request, that usage.n_calls counts requests, and that a bare noul is answered when the rule is lifted.

```bash
KEV_BASE_URL=http://127.0.0.1:8009/v1 KEV_MODEL=kev-latest pytest tests/test_kev_integration.py
```

--------------------------------

### Configure SystemOneClient for ollaya without noul question

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Constructs a SystemOneClient for the ollaya provider with the laya:en model, enabling native mode and disabling the requirement for a question in nouls. Use this when the hosted Jev service would otherwise refuse a noul without instructions, as ollaya answers such requests by reading the question id.

```python
SystemOneClient(provider, model="laya:en", api="systemone",
                 native=True, noul_requires_question=False)
```

--------------------------------

### Run live test with LLM_MODEL and OPENAI_API_KEY

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Optional live test command that runs only when both `LLM_MODEL` and `OPENAI_API_KEY` environment variables are set. Otherwise the test is skipped.

```sh
LLM_MODEL=gpt-5.6-terra OPENAI_API_KEY=... pytest -q tests/test_live.py
```

--------------------------------

### Run a system_one call with jevper and OpenAI client

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Using the Jev interface through jevper's SystemOneClient with an OpenAI client. The `system_one` call takes state and questions, returning answers with choice, probabilities, and confidence. The `method` defaults to auto: it requests logprobs where available and otherwise answers in JSON, as shown for the reasoning model gpt-5.6-terra which returns no logprobs so probabilities arrive as JSON.

```python
from openai import OpenAI
from jevper import Choice, SystemOneClient

client = SystemOneClient(OpenAI(), model="gpt-5.6-terra")

response = client.system_one(
    state="I was charged twice for the same subscription this month.",
    questions={
        "intent": Choice(
            instructions="Pick the intent of the message.",
            criteria={
                "billing": "money, invoices, refunds, charges",
                "technical": "errors, crashes, login or performance problems",
                "sales": "pricing, plans, purchasing, upgrades",
            },
        )
    },
)

answer = response.answers["intent"]
answer.choice        # "billing"
answer.probabilities # {"billing": 0.88, "technical": 0.09, "sales": 0.03}
answer.confidence    # 0.82
```

--------------------------------

### Configure reasoning with ReasoningConfig

Source: https://github.com/zhulinchng/jevper/blob/main/docs/reasoning.md

Selects jevper's native or two-step reasoning path. The provider receives a reasoning parameter only if the fields are applicable to the selected surface and model.

```python
ReasoningConfig(effort="medium", summary="auto", mode="auto")
```

--------------------------------

### Make first system_one call with Choice

Source: https://github.com/zhulinchng/jevper/blob/main/docs/getting-started.md

Makes the first system_one call with a Choice question. Questions are independent and run concurrently; answers are keyed by question ID and preserve insertion order.

```python
from jevper import Choice, SystemOneClient

client = SystemOneClient(provider, model="gpt-5.6-terra")

response = client.system_one(
    state="The login page is blank after I clear my browser cache.",
    questions={
        "intent": Choice(
            instructions="Pick the intent of the message.",
            criteria={
                "technical": "an error, failure, crash, login, or performance problem",
                "billing": "an invoice, charge, refund, or payment question",
                "sales": "pricing, plans, purchasing, or an upgrade",
            },
        )
    },
)

answer = response.answers["intent"]
print(answer.choice)          # "technical"
print(answer.probabilities)  # mapping from criteria key to probability
print(answer.confidence)     # 0..1 confidence derived from the distribution
```

--------------------------------

### Run complete_call.py with environment variables

Source: https://github.com/zhulinchng/jevper/blob/main/docs/complete-example.md

Run the complete_call.py program with environment variables. The first command uses the default base URL and a model id; the second points to a local server at http://127.0.0.1:11434/v1 with a different model. The program reads JEVPER_BASE_URL, JEVPER_API_KEY, and JEVPER_MODEL.

```sh
JEVPER_API_KEY=sk-... \
    JEVPER_MODEL=gpt-5.6-terra \
    python examples/complete_call.py

JEVPER_API_KEY=local \
    JEVPER_BASE_URL=http://127.0.0.1:11434/v1 \
    JEVPER_MODEL=qwen3.5:9b \
    python examples/complete_call.py
```

--------------------------------

### Configure OpenAI client for hosted API

Source: https://github.com/zhulinchng/jevper/blob/main/docs/getting-started.md

Creates an OpenAI client for the hosted API. jevper uses the client's public attributes without importing the SDK itself.

```python
from openai import OpenAI

provider = OpenAI()
```

--------------------------------

### POST /system_one

Source: https://github.com/zhulinchng/jevper/blob/main/docs/index.md

Creates a response using the Jev interface, returning answers keyed by your own question ids. This is the underlying interface without the Decisions schema.

```APIDOC
## [POST] /system_one

### Description
Creates a response using the Jev interface, returning answers keyed by your own question ids. This is the underlying interface without the Decisions schema.

### Method
POST

### Endpoint
/system_one

### Parameters
#### Request Body
- **state** (string) - Required - The input state to process.
- **questions** (object) - Required - A dictionary mapping question ids to Choice objects.
- **model** (string) - Optional - The model to use (defaults to the client's model).

### Request Example
{
  "state": "I was charged twice for the same subscription this month.",
  "questions": {
    "intent": {
      "instructions": "Pick the intent of the message.",
      "criteria": {
        "billing": "money, invoices, refunds, charges",
        "technical": "errors, crashes, login or performance problems",
        "sales": "pricing, plans, purchasing, upgrades"
      }
    }
  }
}

### Response
#### Success Response (200)
- **answers** (object) - A dictionary mapping question ids to answer objects, each with choice, probabilities, and confidence.

#### Response Example
{
  "answers": {
    "intent": {
      "choice": "billing",
      "probabilities": {"billing": 0.95, "technical": 0.03, "sales": 0.02},
      "confidence": 0.95
    }
  }
}
```

--------------------------------

### Create a decisions.create choice request with SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Sends a choice question to a model via SystemOneClient over an OpenAI-compatible surfaceasi. Shows the expected decision, answer fields, confidence, and that raw is kept out of dumps.

```python
from openai import OpenAI
from jevper import SystemOneClient

client = SystemOneClient(OpenAI(), model="gpt-5.6-terra")

decision = client.decisions.create(
    input="I was charged twice for the same subscription this month.",
    questions=[
        {
            "type": "choice",
            "name": "intent",
            "instructions": "Pick the intent of the message.",
            "choices": [
                {"value": "billing", "description": "money, invoices, refunds, charges"},
                {"value": "technical", "description": "errors, crashes, login or performance problems"},
                {"value": "sales", "description": "pricing, plans, purchasing, upgrades"},
            ],
        }
    ],
)

decision.model_dump()    # {"model": …, "answers": [ … ], "usage": { … }} — the wire's own three keys
decision.answers[0].choice        # "billing", the option's own value
decision.answers[0].confidence    # 0.73
decision.raw                      # the jevper response behind it, kept and left out of every dump
```

--------------------------------

### Call local Anthropic-compatible server with jevper SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/README.md

Point the Anthropic client at a local jevper server and call system_one with api="messages". Use with the structured or discrete method; logprobs and grammar raise UnsupportedMethodError before a request, and max_tokens defaults to 1024. A thinking budget must be below max_tokens and can be sent via ReasoningConfig.

```python
from anthropic import Anthropic

from jevper import SystemOneClient

client = SystemOneClient(Anthropic(base_url="http://127.0.0.1:1234"), model="qwen3-4b-instruct")

client.system_one(state=record, questions=rubric, api="messages", method="structured")
```

--------------------------------

### Launch vLLM and SGLang servers on 12 GB GPU

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Commands to launch vLLM and SGLang servers on a 12 GB GPU. The vLLM command uses --gpu-memory-utilization 0.87 and --limit-mm-per-prompt to avoid vision tower memory overhead. The SGLang command uses --attention-backend triton and --sampling-backend pytorch to avoid the flashinfer JIT build failure. Both commands are required to run the models on the constrained GPU.

```bash
# vLLM 0.30.1rc1 — 7.55 GiB of weights, 14,043-token KV cache; 28 s to first token after a reboot
vllm serve ~/models/Qwen3.5-9B-AWQ-4bit --port 8000 \
  --max-model-len 4096 --gpu-memory-utilization 0.87 --enforce-eager \
  --max-num-batched-tokens 1024 --max-num-seqs 2 --reasoning-parser qwen3 \
  --limit-mm-per-prompt '{"image":0,"video":0}'
```

```bash
# SGLang 0.5.20 — ready in 4 s once the kernel cache exists
python -m sglang.launch_server --model-path ~/models/Qwen3.5-9B-AWQ-4bit --port 30000 \
  --mem-fraction-static 0.85 --context-length 4096 --max-running-requests 1 \
  --max-mamba-cache-size 8 --reasoning-parser qwen3 --disable-cuda-graph \
  --attention-backend triton --sampling-backend pytorch
```

--------------------------------

### Create a decision with the Decisions schema

Source: https://github.com/zhulinchng/jevper/blob/main/docs/index.md

Use SystemOneClient.decisions.create to classify a message into predefined choices. The default method='auto' uses logprobs when available and falls back to structured output. Debug and usage details are available in decision.raw.debug and decision.raw.usage.

```python
from openai import OpenAI
from jevper import SystemOneClient

client = SystemOneClient(OpenAI(), model="gpt-5.6-terra")

decision = client.decisions.create(
    input="I was charged twice for the same subscription this month.",
    questions=[
        {
            "type": "choice",
            "name": "intent",
            "instructions": "Pick the intent of the message.",
            "choices": [
                {"value": "billing", "description": "money, invoices, refunds, charges"},
                {"value": "technical", "description": "errors, crashes, login or performance problems"},
                {"value": "sales", "description": "pricing, plans, purchasing, upgrades"},
            ],
        }
    ],
)

answer = decision.answers[0]
print(answer.name, answer.choice, [entry.value for entry in answer.probabilities], answer.confidence)
```

--------------------------------

### curl POST to JEV endpoint with environment variables

Source: https://github.com/zhulinchng/jevper/blob/main/docs/jev-comparison.md

Use this curl command to reproduce the service-side measurement against the jev-1.13-free model. The key comes from the environment, and $JEV_BASE_URL must be the full endpoint including the /systemone path. Re-run this command when the model moves or to check agreement between the two paths.

```sh
curl -sS -X POST "$JEV_BASE_URL" \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "The invoice total does not match the amount I was charged.",
       "model": "jev-1.13-free",
       "questions": {"wrong": {"type": "noul", "instructions": "Do the numbers disagree?"}}}'
```

--------------------------------

### Configure OpenAI client for local server

Source: https://github.com/zhulinchng/jevper/blob/main/docs/getting-started.md

Configures an OpenAI-compatible client for a local server, such as Ollama. The api_key is often ignored by the server. Do not put real secrets in documentation or source control.

```python
from openai import OpenAI

provider = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="local",  # the server may ignore this value
)
```

--------------------------------

### Query CLM with SystemOneClient

Source: https://github.com/zhulinchng/jevper/blob/main/docs/local-servers.md

Query CLM through jevper's SystemOneClient with three typed questions in one request. The response exposes choice and probabilities keyed by the caller's criteria keys or the rubric's own levels. Requires the CLM server on :8700 and uses api="systemone" with noul_requires_question=False.

```python
from openai import OpenAI
from jevper import Choice, Noul, Score, SystemOneClient

with SystemOneClient(
    OpenAI(base_url="http://127.0.0.1:8700/v1", api_key="clm"),
    model="clm-latest",
    api="systemone",
    noul_requires_question=False,
) as client:
    response = client.system_one(
        state="Customer: my invoice was charged twice and nobody answers the phone!",
        questions={
            "urgency": Noul(instructions="Is this urgent?"),
            "department": Choice(instructions="Which team should handle this?",
                                 criteria={"billing": "Charges, invoices, refunds",
                                           "technical": "Bugs and outages"}),
            "frustration": Score(instructions="How frustrated is the customer?",
                                 criteria=["Calm", "Frustrated", "Very angry"]),
        },
    )

response.answers["department"].choice            # 'billing'
response.answers["department"].probabilities     # keyed by the caller's own criteria keys
response.answers["frustration"].probabilities    # {0: …, 1: …, 2: …} — the rubric's own levels
```

--------------------------------

### Choice

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Documentation for the Choice question constructor.

```APIDOC
## Choice

### Description
Constructs a Choice question. The question asks the model to select one of the provided options.

### Constructor
`Choice(instructions=None, criteria=None, examples=())`

### Parameters
- **instructions** (str or JSON value) - Optional - Instructions for the question. Non-string values are rendered as pretty-printed JSON.
- **criteria** (dict) - Required - A dictionary mapping option keys to descriptions. Must have between 1 and 255 options.
- **examples** (tuple of `Example`) - Optional - A tuple of example demonstrations. Excluded from `model_dump()`.

### Limits
- Must have between 1 and 255 options.
- When `logprobs` or `grammar` are used, the maximum is 26 options.
- When `structured` or `discrete` are used, the full range is supported with two-letter labels past `Z`.

### Errors
- Raises `InvalidQuestionError` if validation fails during construction or when passed to `system_one`.
```

--------------------------------

### SystemOneClient constructor signature

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Shows the full signature of the SystemOneClient constructor. Only 'client' is positional; all other options are keyword-only. The 'client' object must expose responses.create, chat.completions.create, or messages.create, and remains owned by the caller.

```python
SystemOneClient(client, *, model, method="auto", api="auto", reasoning=None, examples=(),
                structured_outputs=True, normalize_probabilities=True, top_logprobs=20,
                max_concurrency=8, n_retry_malformed=1, retry=None, temperature=None,
                extra_body=None, extra_headers=None, prompt_cache_key=None,
                native=False, noul_requires_question=True)
```

--------------------------------

### SystemOneResponse and NativeSystemOneResponse

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Documentation for the SystemOneResponse and NativeSystemOneResponse classes, including their fields, cached properties, methods, and usage details.

```APIDOC
## SystemOneResponse

### Description
Represents the response from a system_one call, containing model, answers, usage, reasoning, and debug information.

### Fields
- **model** (str) - The model the call asked for. On Ollaya's native endpoint this is the alias the caller named.
- **answers** (dict[str, Answer]) - Keyed by question id, in insertion order.
- **usage** (Usage) - Aggregated over every provider call and retry.
- **reasoning** (tuple[ReasoningContentPart, ...]) - Trace, in question order.
- **debug** (dict[str, Any]) - Attempts and normalization notes.

### Cached Properties
- **nouls**, **choices**, **scores** - Return `answers` filtered by answer type.

### Methods
- **to_decision()** - Returns this response in OpenAI's Decisions schema, echoing question ids, option keys, and criteria text.

## NativeSystemOneResponse

### Description
Returned when the client was built with `native=True`. Subclass of `SystemOneResponse`, so code reading a `SystemOneResponse` reads this one unchanged.

### Fields
- **routing** (Routing or None) - A router's choice of checkpoint, or `None` when a model named directly answered.
- **state_truncated** (bool) - Whether part of the `state` was dropped to fit the model's context.
- **done_reason** (str) - `"decide"`, or `"load"`/`"unload"`.
- **created_at** (str) - When the endpoint produced the response, in the service's own timestamp format.
- **total_duration** (int or None) - Request to response, queueing included, in nanoseconds.
- **load_duration** (int or None) - Time spent waiting for the model to load; `0` when it was warm.
- **eval_duration** (int or None) - Tokenization, forward pass and calibration, in nanoseconds.

### Routing
```python
Routing(router="laya:latest", model="laya:en", route="english", reason="English Latin text")
LayaExtras(confidence=0.615, act_probability=1.0)
```

`route` is the stable key to branch on. `reason` is the router's own prose, carried but never parsed. `LayaExtras` is the `laya` object `extras=["laya"]` puts on every answer: the model's own confidence, a different number computed by a different head, and `act_probability`, which is `None` for a model with no act head. It is `None` on every answer on every other surface.

`routing` is `null` when a model named directly answered. Any other value that is not an object is a `MalformedAnswerError`. An explicit `null` `reason` reads as the empty string, and `act_probability` is bounded to `[0, 1]`.

### Usage
```python
Usage(input_tokens=None, output_tokens=None, reasoning_tokens=None, cached_tokens=None, n_calls=0, n_retries=0, latency=0.0)
```

A token count is `None` when any constituent call omitted it (a reported `0` is preserved). `n_calls` counts analysis passes and corrective retries; `n_retries` counts transient-failure retries only. `latency` is wall-clock seconds for the whole `system_one` call.

`cached_tokens` is the prompt tokens the provider read from its own prompt cache, read from `usage.prompt_tokens_details.cached_tokens` on Chat Completions, `usage.input_tokens_details.cached_tokens` on the Responses surface, and `usage.cache_read_input_tokens` on Messages. It is the one number that says caching worked; a provider that reports nothing leaves it `None`. Not every server reports it at all, and two need a flag to: vLLM's `--enable-prompt-tokens-details` and SGLang's `--enable-cache-report` for its Chat Completions route.
```

--------------------------------

### Import jevper public API

Source: https://github.com/zhulinchng/jevper/blob/main/docs/api.md

Imports the core client classes and types from the jevper package root. Use this to access SystemOneClient, AsyncSystemOneClient, and the various data types.

```python
from jevper import SystemOneClient, AsyncSystemOneClient, Choice, Noul, Score, Example, ReasoningConfig
```