state + typed questions → candidate scores → probabilities → typed answers

TurboJev is a Rust-first decision layer for applications that need a model to choose, route, assess, or approve. It scores the allowed candidates directly and returns structured choice, noul, and score answers. The optimized path does not ask a model to generate JSON and does not rely on parsing a natural-language reply.

It runs locally with open-weight models, keeps inference and decision semantics separate, and exposes the same contract through Rust, Node/TypeScript, Python, C, .NET, and browser/WASM hosts.

Get a real model running

The fastest path is one of the runnable samples. It builds the native libraries, downloads a small verified GGUF model, then runs the same local model through four language bindings.

py samples/build.py native --download-model
py samples/run.py ts
py samples/run.py python
py samples/run.py csharp
py samples/run.py rust

On Linux or macOS, use python in place of py. See the complete samples guide, including architecture selection and the browser-only JavaScript example.

Ask a typed question

from turbojev import TurboJev

with TurboJev.load("./model.gguf", n_gpu_layers=0) as jev:
    result = jev.classify(
        "My package arrived broken.",
        ["billing", "shipping", "technical", "other"],
    )

print(result["choice"])
print(result["probabilities"])

Use evaluate when one state needs several typed decisions at once:

{
  "state": {"message": "My package arrived broken.", "customerTier": "plus"},
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoices, or refunds",
        "shipping": "Delivery, damage, or replacement",
        "technical": "Product or application problem"
      }
    },
    "urgent": {
      "type": "noul",
      "instructions": "Does this need urgent human intervention?"
    },
    "resolution": {
      "type": "score",
      "instructions": "How complete is the proposed resolution?",
      "criteria": ["Not started", "Partly resolved", "Resolved"]
    }
  }
}

The response preserves each question's type, candidate distribution, selected answer, zero-generation usage, execution path, and calibration provenance.

Why TurboJev

Stable option ordering when order is irrelevant

Many models favor the first or last presented option. For unordered choice questions, enable cyclic order robustness:

{
  "model": "./model.gguf",
  "execution": { "orderRobustness": "cyclic" }
}

TurboJev evaluates each cyclic option order, maps scores back to the original keys, averages the raw logits, and then calibrates the result. The response records both the active policy and the actual number of model evaluations. The feature applies to classify as well as evaluate; it deliberately leaves ordered scores and boolean decisions unchanged. Read the full contract and cost model.

Calibrated confidence is explicit

A softmax distribution is useful for ranking but is not automatically a calibrated probability. TurboJev keeps calibration separate from inference and records whether a fitted calibration profile was used. This lets applications set thresholds based on evidence instead of treating every high model score as a guarantee. See calibration tooling.

Text and multimodal models

Text models can use the built-in llama.cpp/GGUF route or a custom runtime adapter. For models that accept media, TurboJev carries a model-independent envelope for text, image, audio, and video evidence. The selected runtime owns the processor and candidate scoring; TurboJev still validates the input and produces the same typed response.

The repository includes local CPU examples for:

• SmolVLM2 image and short-video decisions.
• LFM2.5-Audio spoken-intent decisions.

The generic protocol does not claim that every GGUF, ONNX, or safetensors model is multimodal. Runtime support is declared by the adapter and documented in multimodal compatibility.

Pick your host

Built for evidence, not opaque claims

The Windows validation run used a real small GGUF model with complete response parity across Node/TypeScript, Python, C, and .NET, including typed answers and the zero-generation invariant. The multimodal SmolVLM2 CPU sample also has a recorded real image/video validation run. Reproduce the commands and inspect the limits in Windows validation and multimodal validation.

TurboJev keeps an independent reference path and treats runtime optimizations as capabilities that require parity evidence. It does not advertise cross-request fusion merely because a runtime can batch tokens.

Design commitments

• Portable core: semantic logic has no operating-system, filesystem, network, hardware, tokenizer, or model dependency.
• Truthful runtime boundaries: adapters use the real model template and tokenizer; they never invent candidate token IDs.
• Local by default: no mandatory hosted service and no mandatory telemetry.
• Typed output: model backends return scores; TurboJev validates, normalizes, calibrates, and builds one canonical response.
• Open integration: custom runtimes and model families plug into the scoring contract without forking the decision engine.

Documentation

• Architecture
• Samples and build commands
• Multimodal input contract
• Candidate-order robustness
• Calibration tooling
• Runtime qualification
• Testing and validation
• Release and package publishing

License

TurboJev is available under the Apache License 2.0, which permits commercial use and redistribution subject to its terms.