Crate semantic_operators 

Typed semantic questions, confidence-aware answers, and provider-neutral composition.

Default features require no network or particular async runtime. Enable typesafe, images, tokio, or blocking for optional integrations.

Semantic Operators

Native Rust questions and confidence-aware answers for interchangeable semantic model providers. The implementation is validated with frozen Python outputs and offline scripted/localhost tests. Hosted inference and model quality have not been qualified.

Version 0.1.0-alpha.2 is an experimental alpha with an unstable API. It is a native Rust counterpart to Python semantic-operators 0.12 and C++ libsemop. No Python interpreter or C++ FFI is required. The implementation preserves the frozen Python normalization and text wire contracts with documented Rust adaptations.

[dependencies]
semantic-operators = "=0.1.0-alpha.2"

Default features provide Boolean, Choice, Score and Box questions, typed operators, async provider contracts, uncertainty-only cascades, traced flows, filtering, reranking, evaluation and Python-compatible text wire translation. No network client or Tokio runtime is required by default.

Feature	Adds
default (empty)	Core types, providers, operators, flows, recipes, evaluation and text wire
typesafe	Explicit-config HTTP provider; includes tokio
images	Assets, frames and localization
tokio	Deadline wrapper using a caller-owned runtime
blocking	Synchronous facade with its own runtime; includes tokio

For hosted images select both typesafe and images. Edition 2024; minimum supported Rust version 1.85, tested with stable Rust on Linux, macOS and Windows.

use semantic_operators::{Boolean, Operator};

fn main() -> semantic_operators::Result<()> {
    let complaint = Operator::new(
        "complaint",
        Boolean::new("Is the customer reporting a problem?")?.with_min_confidence(0.8)?,
    )?;
    assert_eq!(complaint.name(), "complaint");
    Ok(())
}

Call complaint.ask(&provider, &state).await from your application’s executor. The result is Answer<bool>: Some(true), Some(false), or None when undecided. Probability evidence and optional reported call metadata remain available. Provider failures are Result errors, never ordinary undecided answers.

Runnable examples included in this package use an explicit synthetic provider and make no hosted calls: cargo run --example hello, triage, filter, rerank, and cargo run --features images --example images. They demonstrate APIs and control flow, not inference accuracy.

See the repository, API guide, and compatibility contract. Provider confidence is not a guarantee of correctness; evaluate your own task.

Pin an exact prerelease while evaluating the alpha. The versioning policy explains API and compiler compatibility; repository main may include unreleased changes.

Original project code uses the MIT License. CPython-derived numeric code retains Python-2.0 terms; the current source declares the aggregate license MIT AND Python-2.0. See NOTICE.md. New contributions use MIT terms; preserve upstream licenses and notices. See Contributing and Governance.

Re-exports

pub use answer::Answer;

pub use answer::AnswerType;

pub use answer::AnswerValue;

pub use answer::Call;

pub use answer::Probabilities;

pub use answer::complement;

pub use answer::make_answer;

pub use answer::token_count;

pub use cascade::Cascade;

pub use cascade::TimeLimited;tokio

pub use error::Error;

pub use error::ErrorKind;

pub use operator::NamedQuestion;

pub use operator::Operator;

pub use operator::apply;

pub use provider::Answers;

pub use provider::FunctionProvider;

pub use provider::Provider;

pub use provider::ProviderFuture;

pub use provider::Questions;

pub use provider::Request;

pub use provider::ask;

pub use question::Boolean;

pub use question::BoxQuestion;

pub use question::Choice;

pub use question::Question;

pub use question::Region;

pub use question::Score;

pub use question::TypedQuestion;

pub use state::State;

Modules

answer

Central answer normalization and typed projections.

bench

Offline scoring and explicit, bounded benchmark execution.

blockingblocking

An explicit synchronous facade owning its Tokio runtime.

cascade

Uncertainty-only escalation and optional per-call deadlines.

each

Bounded independent calls, preserving input order and per-item failures.

error

Structured errors without automatic inclusion of request data.

filter

Boolean filtering with one recorded outcome per input.

flow

Ordinary Rust control flow with explicit uncertainty and retained traces.

imageimages

Explicit request-owned images and frame sequences.

locateimages

Presence-gated localization in one provider invocation.

operator

Named typed questions and heterogeneous one-call application.

provider

Async provider contracts and the checked request/response boundary.

providerstypesafe

Optional hosted-provider integrations.

question

Validated provider-independent questions and regions.

rerank

Independent relevance scoring and stable ranking without synthetic scores.

state

Validated text and JSON state.

wire

Strict Python-compatible text wire schema 1.

Structs

IndexMap

A hash table where the iteration order of the key-value pairs is independent of the hash values of the keys.

Type Aliases

Result

A library result. Uncertainty is represented inside a successful answer.