rust_multi_ranking_engine

A Rust library for combining scores from multiple sources and selecting a constrained subset of candidates, with evidence for every selection and rejection.

Use it between retrieval or scoring and the component that consumes the selected items. Candidates can be documents, events, products, or any application type with a stable identifier. The engine supplies fusion, bounded candidate admission, set selection, and result accounting. Your application supplies the data and scorers.

This guide describes the current checkout. A published package or an older tag may not contain the same result-contract fixes. Minimum Rust versions are declared requirements, not a claim that every optional dependency resolution has been tested on those versions.

Research foundations

These references explain algorithms and assumptions behind the implementation. They do not certify every combination of callbacks and constraints accepted by the API.

GUARANTEE_KNAPSACK_MODULAR = 1/2 corresponds to standard modified-greedy comparison with the best singleton. Every factor remains conditional on the assumptions in Constraints, objectives, and guarantees.

Contents

1. Capabilities and scope
2. Quick start
3. Installation and features
4. Execution model
5. Core types and callback contracts
6. Rust API reference
7. Fusion, scales, and missing scores
8. Constraints, objectives, and guarantees
9. Selection budgets
10. Results and audit evidence
11. Python binding reference
12. Pipeline integration
13. Extension points
14. Build and test
15. Performance, limits, and troubleshooting
16. Repository layout
17. License

1. Capabilities and scope

• Combine heterogeneous scores with Reciprocal Rank Fusion (RRF), or explicitly normalize scores for weighted value fusion.
• Evaluate cheap scorers across the input and expensive scorers only on a bounded pool.
• Apply candidate filters, group caps, total-count caps, and cost constraints.
• Add a coverage objective whose marginal gain depends on the items already selected.
• Choose a fixed count, derive a count from a fitted score distribution, or select within an integer cost budget.
• Require a minimum number of matching candidates and return an error when repair cannot satisfy the requirements.
• Return axis scores, fusion terms, rejection reasons, selection metadata, and execution counters.
• Use Rust traits or the Python dictionary interface without linking a model into the core.

A single score with an unconstrained top-K requirement usually needs only sorting or a heap. This library is useful when several scoring sources, set constraints, or auditable decisions must work together. It does not retrieve candidates, deduplicate identities, train models, tokenize text, or solve arbitrary constrained optimization exactly.

2. Quick start

Rust

After adding the dependency described in Installation and features, place this in src/main.rs. It selects two documents while allowing at most one per source.

use rust_multi_ranking_engine::{
    constraint, Budget, Candidate, CandidateId, Engine, Fusion,
    ScoreScale, Scorer, ScorerCost, ScorerId,
};

struct Doc {
    id: u64,
    source: &'static str,
    relevance: f32,
}

impl Candidate for Doc {
    fn id(&self) -> CandidateId { CandidateId::Num(self.id) }
}

struct Relevance;
impl Scorer<Doc> for Relevance {
    fn id(&self) -> ScorerId { ScorerId::new("relevance") }
    fn scale(&self) -> ScoreScale { ScoreScale::Unit }
    fn cost(&self) -> ScorerCost { ScorerCost::Cheap }
    fn score(&self, doc: &Doc) -> Option<f32> { Some(doc.relevance) }
}

fn main() -> rust_multi_ranking_engine::Result<()> {
    let engine = Engine::new()
        .scorer(Relevance)
        .fuse(Fusion::weighted_sum())
        .set_constraint(constraint::max_per_group(
            "one_per_source", 1, |doc: &Doc| doc.source,
        ))
        .budget(Budget::TopK(2));
    engine.validate()?;

    let out = engine.run([
        Doc { id: 1, source: "manual", relevance: 0.9 },
        Doc { id: 2, source: "manual", relevance: 0.8 },
        Doc { id: 3, source: "wiki", relevance: 0.7 },
    ])?;

    let ids: Vec<_> = out.ranked.iter().map(|r| r.candidate.id).collect();
    assert_eq!(ids, vec![1, 3]);
    assert!(out.is_complete());
    assert_eq!(out.rejected_counts.set_constraint, 1);
    for row in &out.ranked {
        assert_eq!(row.fusion.recompute(), row.fused);
        println!("{}", row.to_json(&row.candidate.id()));
    }
    Ok(())
}

Python

Install from source first. Python setters mutate the engine and return None; do not chain them.

from rust_multi_ranking_engine import Engine

engine = Engine()
engine.scorer("relevance", scale="unit")
engine.scorer("authority", scale="unit")
engine.fuse("weighted_sum", weights={"relevance": 0.8, "authority": 0.2})
engine.max_per_group("source", 1, id="one_per_source")
engine.budget_top_k(2)

out = engine.run([
    {"id": "a", "scores": {"relevance": 0.9, "authority": 0.8},
     "groups": {"source": "manual"}, "text": "Install the client."},
    {"id": "b", "scores": {"relevance": 0.8, "authority": 0.9},
     "groups": {"source": "manual"}, "text": "Configure the client."},
    {"id": "c", "scores": {"relevance": 0.7, "authority": 0.7},
     "groups": {"source": "wiki"}, "text": "Troubleshooting notes."},
])

assert [row.id for row in out.ranked] == ["a", "c"]
assert out.is_complete()
assert out.rejected_counts["set_constraint"] == 1
print(out.selection)
for row in out.ranked:
    print(row.rank, row.candidate["text"], row.to_json())

The result contains the selected set in selection order. A higher fused score can lose to a group cap or to a candidate with greater coverage gain.

3. Installation and features

Rust dependency

For development against this checkout, use a path dependency. This example assumes your application and the engine are sibling directories; adjust the relative path to your layout.

[dependencies]
rust_multi_ranking_engine = { path = "../rust_multi_ranking_engine" }

Enable optional features in the same declaration when needed:

[dependencies]
rust_multi_ranking_engine = { path = "../rust_multi_ranking_engine", features = ["parallel", "serde"] }

Audit JavaScript Object Notation (JSON) output is available without serde. The standard Python build enables python only. Keep parallel out of Python callback builds: worker callbacks must acquire Python's interpreter lock, and that combination is not the supported binding configuration.

Python source installation

From the repository root, with Rust and a native linker installed:

python -m venv .venv

Activate it on Windows:

.venv\Scripts\Activate.ps1

Or on Linux and macOS:

source .venv/bin/activate

Build and install through the backend declared in pyproject.toml:

python -m pip install .
python -c "import rust_multi_ranking_engine as r; print(r.__version__, r.__status__)"

For binding development or wheel creation:

python -m pip install "maturin>=1.5,<2.0"
maturin develop --release
maturin build --release

Build dependencies may need network access on first use. The abi3 setting permits a compatible wheel to serve multiple supported CPython versions on the same platform and architecture; wheels remain platform-specific. Registry installation depends on a compatible release being available there. Source installation is the route for the current behavior documented here.

4. Execution model

Let N be the input count, M the pool capacity, and K the requested or derived count.

Pool sizing and admission

The default pool multiplier is 32. Capacity uses saturating arithmetic and is at least one.

For RRF, admission uses the explicitly named cheap scorer or the first registered cheap scorer. At least one cheap scorer is required because ranks cannot be computed over a stream before the pool exists.

For weighted and maximum fusion, admission uses the explicitly named cheap scorer, or fusion over the cheap axes. With no cheap axes, admission keys are all negative infinity and identifiers decide pool membership. Register a useful cheap scorer even when an expensive scorer supplies the final signal.

Pool pruning precedes expensive scoring and coverage optimization. A discarded candidate cannot later satisfy a requirement or improve the selected set. Increase the multiplier when admission is a weak proxy for the final objective, and measure quality against a larger pool.

Determinism

Ties use CandidateId: numeric identifiers sort before text identifiers, then each variant sorts ascending. Supply unique, stable identifiers and callbacks that return the same values for the same inputs.

Floating-point fusion follows scorer registration order. Keep that order fixed. Parallel equivalence additionally requires scores to be independent of batch size and partitioning. Timing, arrival order of rejection details, and a first-N rejection sample are not deterministic ranking guarantees. Identifier uniqueness is a caller contract; the engine does not deduplicate or reject duplicates.

5. Core types and callback contracts

Engine<C> requires C: Candidate + Sync. Registered scorers, constraints, and objectives are stored through trait objects and must satisfy their Sync and registration-time 'static bounds. run borrows the engine and consumes an IntoIterator<Item = C>, so an engine can be reused with fresh inputs.

Scorer contract

• id, scale, and cost must be stable. The engine caches them at registration.
• score(&C) returns Option<f32>. None means unavailable, distinct from a measured zero.
• score_batch(&[&C]) must return exactly one value per input, in the same order. Its default implementation calls score for each candidate.
• Expensive scorers use score_batch. Cheap scorers use per-candidate scoring during admission.
• A length mismatch returns Error::BatchLengthMismatch. Each parallel chunk is checked independently, so an extra result in one chunk cannot cancel a missing result in another.
• The engine cannot detect reordered batch values. Preserve the positional mapping.
• Normalized<S> forwards the underlying batch call and normalizes returned values, preserving None entries and allowing malformed lengths to be detected.

The engine treats a returned NaN as missing after scoring. It does not generally reject infinities or validate that a declared Unit score lies in [0, 1]. Normalizers transform values before the engine observes them. Validate raw model outputs in the adapter when strict numerical validity matters.

ScoreSet::get(&id) distinguishes an absent axis (None) from a registered axis with no value (Some(None)). iter() returns axes in registration order. Result scores include any explicit normalization; they need not be the original model logits.

6. Rust API reference

The application programming interface (API) uses builder methods that consume and return Self. validate and run borrow &self.

Errors

Match variants instead of parsing display strings. Current core display messages are in Korean.

Validation checks declared configuration, not arbitrary callback semantics. It does not prove mathematical declarations, validate all floating-point parameters, or catch Rust callback panics. A failed run returns an error rather than a partial Outcome; an iterator may already have been consumed when a runtime error occurs.

7. Fusion, scales, and missing scores

Scale compatibility

Every axis is ordered higher-first, including Rank. If a retriever returns rank 1 as best, convert it to a decreasing utility such as 1 / (rank + 1). Negate a distance when smaller distances should rank higher. A scale declaration does not reverse ordering.

Reciprocal Rank Fusion

For each participating axis, the engine ranks surviving candidates by score and adds 1 / (k + rank), with one-based rank. Fusion::rrf() uses k = 60; Fusion::Rrf { k } supplies another constant.

RRF uses ordering rather than magnitude. It reranks the retained pool, so upstream rank gaps and ranks of discarded candidates are not preserved. Use a finite nonnegative k; arbitrary values are not fully guarded by validation.

Weighted and maximum fusion

Despite its name, WeightedSum computes a weighted mean over participating axes:

fused = sum(weight_i * value_i) / sum(weight_i).

An empty weight list assigns each axis weight one. With an explicit nonempty list, omitted axes have weight zero. Under Skip, missing axes do not contribute to the denominator. Avoid duplicate weight entries; the current lookup uses the first match. Supply finite nonnegative weights and a positive total for participating axes. These numerical conditions are caller responsibilities.

Fusion::Max takes the largest participating value. With no participating values, fusion yields zero. A Unit declaration makes axes structurally compatible; it does not establish probability calibration or comparable business meaning.

Explicit normalization

Import ScorerExt and wrap a Rust scorer with .normalized(normalizer).

Min-max bounds are supplied externally. Estimating them from an incoming stream would make earlier and later candidates incomparable. Sigmoid maps a logit into a unit interval but does not itself calibrate a model.

Missing scores

A missing cheap score under Reject removes a candidate before admission. A missing expensive score removes it during refinement, without refilling the pool from candidates already discarded in stage one.

8. Constraints, objectives, and guarantees

Built-in constraints

constraint::group_counts(items, key) helps inspect a selected set. Upper bounds compose by intersection. A generic cost_budget enforces an additional ceiling but does not activate the dedicated knapsack algorithm used by Budget::Tokens.

Coverage and custom objectives

Without a set objective, the objective is the sum of fused scores. With one, each selection step uses:

gain(S, candidate) = fused(candidate) + objective.marginal_gain(S, candidate).

Coverage::new(|candidate| candidate_topics) rewards newly covered keys. Duplicate topics within a candidate or across selected candidates count once. .weighted(|key| weight) assigns each unique key a value. Use finite nonnegative weights when relying on monotone submodular guarantees. Choose the weight scale deliberately: one coverage unit can dominate a small RRF score.

Lower-bound requirements

Requirements run after greedy selection. Repair searches for feasible replacements, preserves requirements satisfied earlier, and checks every requirement before returning success. For deterministic predicates and valid constraint implementations, a successful result satisfies all registered lower bounds and the enforced upper bounds.

Repair is a single-replacement heuristic. Requirement order can affect success. InfeasibleRequirement means the procedure failed in the eligible pool; a feasible set may still exist and require multiple coordinated swaps. Its available field counts candidates matching the predicate before accounting for other constraints. It is not the number of feasible replacements.

If repair changes the selection, the result reports exact = false and guarantee = None. Requirements already satisfied do not by themselves downgrade the metadata.

Approximation metadata

A matroid is a family of feasible sets with hereditary and exchange properties. Submodularity means diminishing marginal gains. Custom implementations declare these properties through is_matroid() and is_submodular(); the engine trusts those declarations.

The following table describes metadata dispatch for the eligible pool, subject to mathematical assumptions. Bounds require a normalized, nonnegative, monotone objective, valid constraint declarations, and appropriate nonnegative costs. The engine does not prove these conditions. Submodularity alone does not establish monotonicity, and negative scores or marginal gains can invalidate a bound.

Here p counts registered matroid set constraints; the cardinality budget is handled separately.

None means no factor is reported for that configuration; it does not measure quality. exact = true is conditional metadata, not proof that admission preserved the globally optimal set from the original input.

9. Selection budgets

Fixed count

Budget::TopK(k) selects up to k candidates; k must be positive. Filters, constraints, or a small pool can leave fewer than k. Inspect the selected count and rejection evidence.

Tail-mass count

Budget::tail_mass(epsilon, fallback_k) fits a finite Zipf distribution to descending fused scores after refinement and thresholding, then derives a count intended to leave at most epsilon of fitted mass outside the prefix.

The validator accepts 0 <= epsilon < 1. Use positive fallback_k for a useful fallback. The implementation fits an exponent in [0.01, 6] through bounded numerical search. Fit quality is 1 - D, where D is the Kolmogorov-Smirnov distance; the default acceptance threshold is 0.9.

This quality score is not a statistical p-value, and the procedure is not the full bootstrapped power-law test described in the cited literature. It operates on the pool, not the entire input. Constraints and coverage can also change the selected items, so epsilon does not guarantee whole-corpus relevance recall or the actual selected set's omitted mass.

BudgetTrace records s, fit_quality, fallback, reason, and derived_k. Inspect it when adaptive selection is enabled. tail_mass(s, k, v) separately computes finite Zipf mass beyond the first k ranks among v ranks.

Integer cost budget

Budget::Tokens { max } requires .cost(|candidate| candidate_cost) in Rust. Costs are u32 and accumulated with a wider integer. Tokens are a common use case, but any consistently measured nonnegative integer cost can be used.

The selector compares gain-per-cost greedy selection, raw-gain greedy selection, and the best feasible singleton, then keeps the highest objective value. This is the dedicated path associated with the knapsack factors above.

Zero-cost candidates are allowed, so a token budget does not necessarily bound item count. It also sizes the pool from the numeric budget: a large token limit can create a large pool. A generic floating-point CostBudget remains an additional feasibility check with no claimed knapsack factor.

10. Results and audit evidence

Outcome contract

is_complete() verifies accounting. It does not certify that K was filled, IDs were unique, callbacks were correct, or selection was globally optimal.

Ranked<C> contains candidate, rank, fused, scores, fusion, and passed set-constraint identifiers. Rank is selection order, including positions affected by repair, and need not follow descending fused score. fused excludes additional set-objective gain.

FusionTrace contains the method, missing policy, optional RRF constant, and per-axis terms. Each term records the scorer, input kind (Value, Rank, Imputed, or Skipped), effective weight, and contribution. recompute() reconstructs the fused score from contributions; used_axes() counts participating terms. This reconstructs fusion, not the history of objective gains and replacement decisions.

Rejections and retention

A rejection row contains the candidate, reason, and optional fused score. Stage-one rejections have no fused score. If multiple generic constraints block a remaining candidate, the first matching constraint supplies the reason. The dedicated token budget has no separate variant, so budget-limited candidates can appear as Outranked.

For large streams, use Count or a bounded Sample. Default Keep retains rejected payloads and can use memory proportional to the entire input.

Diagnostics

ScorerTrace.calls counts candidate evaluations, not batch callback invocations. Timing varies between runs.

Treat cut_margin as a local diagnostic. It can be absent when no finite comparison exists or the singleton branch wins. For tokens, it remains based on gain per cost even when the raw-gain branch wins. After repair it is not an optimality certificate. The token path's pool_exhausted follows internal greedy bookkeeping; do not use it as proof of feasibility, recall, or remaining budget.

JSON output

Rust selected and rejected rows expose to_json(&candidate_id). Python selected rows expose to_json(); Python rejected rows expose structured attributes instead. This selected-row example combines equally weighted values 1.0 and 0.5 into 0.75:

{
  "candidate": "doc-a",
  "rank": 1,
  "fused": 0.75,
  "scores": {"relevance": 1.0, "authority": 0.5},
  "missing_policy": "skip",
  "fusion": {
    "method": "weighted_sum",
    "terms": [
      {"scorer": "relevance", "input": {"kind": "value", "value": 1.0}, "weight": 0.5, "contribution": 0.5},
      {"scorer": "authority", "input": {"kind": "value", "value": 0.5}, "weight": 0.5, "contribution": 0.25}
    ]
  },
  "constraints": {}
}

Nonfinite numbers become JSON null. IDs render as strings, so numeric 7 and text "7" can produce the same audit ID. Use one identifier convention when exporting. Rows do not serialize the candidate payload or provide a complete run-level schema. Store configuration, row evidence, and run metadata in an application-owned envelope when durable replay is required.

11. Python binding reference

The module exports Engine, result classes, EngineError, tail_mass, __version__, and __status__. Setters mutate the engine. Validation occurs in run; the binding does not expose Rust's validate().

Candidate dictionaries

Use None for a missing score entry, not scores=None. For a positive group cap, candidates with no value for that group are exempt; a cap of zero rejects all candidates through that constraint. Validate group fields upstream if missing groups must not bypass a limit.

Configuration methods

Normalizer names are sigmoid, clamp01, and minmax; the last requires normalize_range=(min, max). An expensive scorer without fn still reads precomputed scores. Declaring cost does not invoke a model.

A callback supplied through fn must belong to an expensive scorer. It receives a list of original candidate objects and returns an equal-length sequence of numbers or None in the same order. In the standard serial Python build, each expensive scorer receives the pool as a batch. Support empty batches too. Input conversion still processes every candidate; batching does not eliminate all interpreter work.

Configuration errors generally surface as ValueError; execution failures such as malformed batch length or failed repair use EngineError. Callback exceptions can propagate from the adapter. Match exception types rather than parsing localized strings.

Result objects

selection, trace, and rejected_counts are dictionaries. Candidate objects remain references to originals, while selected-row JSON is a snapshot from result construction. Avoid mutating returned dictionaries or candidates used as audit evidence. Scores use Rust f32; compare with a tolerance such as math.isclose rather than exact decimal equality.

12. Pipeline integration

Retrieval-augmented generation

In retrieval-augmented generation (RAG), retrieve broadly, attach cheap retrieval scores, rerank the admitted pool, select under source and context limits, and pass row.candidate to the context builder. Token counts must come from the tokenizer used by the consuming model.

This runnable example demonstrates the callback boundary with fixed illustrative logits. It performs no model inference.

from rust_multi_ranking_engine import Engine

seen_batches = []

def rerank_batch(candidates):
    seen_batches.append(len(candidates))
    # Replace this lookup with a model's batch inference adapter.
    return [candidate["rerank_logit"] for candidate in candidates]

engine = Engine()
engine.scorer("retrieval", scale="unit")
engine.scorer("rerank", scale="unbounded", cost="expensive",
              normalize="sigmoid", fn=rerank_batch)
engine.fuse("weighted_sum", weights={"retrieval": 0.3, "rerank": 0.7})
engine.admission("retrieval")
engine.max_per_group("source", 1)
engine.coverage_objective()
engine.budget_tokens(300)
engine.rejections("sample", n=20)

out = engine.run([
    {"id": "setup", "scores": {"retrieval": 0.9}, "rerank_logit": 2.0,
     "groups": {"source": "manual"}, "cover": ["setup"], "cost": 120,
     "text": "Installation procedure."},
    {"id": "config", "scores": {"retrieval": 0.8}, "rerank_logit": 1.0,
     "groups": {"source": "manual"}, "cover": ["setup"], "cost": 100,
     "text": "Configuration procedure."},
    {"id": "repair", "scores": {"retrieval": 0.7}, "rerank_logit": 1.5,
     "groups": {"source": "wiki"}, "cover": ["repair"], "cost": 140,
     "text": "Recovery procedure."},
])

assert seen_batches == [3]
assert out.is_complete()
assert sum(row.candidate["cost"] for row in out.ranked) <= 300
assert {row.id for row in out.ranked} == {"setup", "repair"}
# Tokens combined with a group cap have no reported approximation factor.
assert out.selection["guarantee"] is None
context = "\n\n".join(row.candidate["text"] for row in out.ranked)
print(context)

The Rust counterpart in examples/rag_selection.rs combines normalized logits, source caps, coverage, and a token budget. Its logits are also supplied data, not a bundled cross-encoder.

Multiple retrieval sources

Merge retrieval outputs by an application-owned canonical ID before running the engine. Preserve one score axis per source, mark absent scores as missing, and use RRF when magnitudes are incomparable. Convert lower-is-better ranks or distances first. Set admission deliberately: the first cheap axis otherwise controls the RRF pool.

The engine does not merge duplicate IDs. If admission depends on several retrievers, construct a suitable cheap admission score upstream and register it explicitly.

Cached or unavailable model scores

A scorer adapter can read cached values and return None when unavailable. Choose Skip, Impute, or Reject according to application semantics. Include content version, query, model version, and preprocessing settings in cache keys; the core has no knowledge of them.

Audit storage

For full per-candidate records, use Keep and export after the run. For large inputs, use Count or Sample and store aggregate counts with selected evidence. The core has no streaming audit sink callback. If full audit retention and bounded process memory are both required, design external storage or input partitioning with its effect on global selection made explicit.

13. Extension points

Implement existing traits in an adapter crate or application module. The core need not depend on your model runtime, service client, or domain types.

This complete Rust example wraps a batch scorer without losing its batch implementation, then adds a lower-bound requirement:

use rust_multi_ranking_engine::{
    Budget, Candidate, CandidateId, Engine, Fusion, Normalizer, Requirement,
    ScoreScale, Scorer, ScorerCost, ScorerExt, ScorerId,
};

struct Item { id: u64, cheap: f32, logit: f32, required: bool }
impl Candidate for Item {
    fn id(&self) -> CandidateId { CandidateId::Num(self.id) }
}

struct Cheap;
impl Scorer<Item> for Cheap {
    fn id(&self) -> ScorerId { "cheap".into() }
    fn scale(&self) -> ScoreScale { ScoreScale::Unit }
    fn cost(&self) -> ScorerCost { ScorerCost::Cheap }
    fn score(&self, c: &Item) -> Option<f32> { Some(c.cheap) }
}

struct BatchLogits;
impl Scorer<Item> for BatchLogits {
    fn id(&self) -> ScorerId { "logit".into() }
    fn scale(&self) -> ScoreScale { ScoreScale::Unbounded }
    fn cost(&self) -> ScorerCost { ScorerCost::Expensive }
    fn score(&self, c: &Item) -> Option<f32> { Some(c.logit) }
    fn score_batch(&self, candidates: &[&Item]) -> Vec<Option<f32>> {
        // Replace with batch inference, preserving length and order.
        candidates.iter().map(|c| Some(c.logit)).collect()
    }
}

fn main() -> rust_multi_ranking_engine::Result<()> {
    let out = Engine::new()
        .scorer(Cheap)
        .scorer(BatchLogits.normalized(Normalizer::Sigmoid))
        .fuse(Fusion::weighted_sum())
        .require(Requirement::at_least("required_kind", 1, |c: &Item| c.required))
        .budget(Budget::TopK(1))
        .run([
            Item { id: 1, cheap: 0.9, logit: 3.0, required: false },
            Item { id: 2, cheap: 0.5, logit: 0.0, required: true },
        ])?;
    assert_eq!(out.ranked[0].candidate.id, 2);
    assert!(!out.selection.exact);
    assert_eq!(out.selection.guarantee, None);
    assert!(out.is_complete());
    Ok(())
}

Return false for a mathematical declaration unless the property is established. The engine can still run and will withhold the corresponding claim. admits must describe feasibility of adding the candidate to the current set; hidden mutable state can invalidate selection and repair checks.

14. Build and test

Run from the repository root:

cargo fmt --all -- --check
cargo test
cargo test --features parallel,serde
cargo doc --no-deps
cargo run --example rag_selection
cargo run --release --example throughput

Rust tests use no separate testing dependency. They include deterministic generated cases, exhaustive comparisons on small instances, configuration checks, audit invariants, and result-contract regressions.

For Python, build the supported configuration in an activated virtual environment, then run the binding suite:

python -m pip install pytest "maturin>=1.5,<2.0"
maturin develop --release
python -m pytest tests/test_python_binding.py

Test Rust parallel behavior separately from the standard Python build. --all-features combines Python and Rayon and is not a substitute for those configurations. Unit tests do not establish model accuracy, production throughput, or minimum-toolchain compatibility.

15. Performance, limits, and troubleshooting

Cost model

Stage-one heap admission takes approximately O(N log M) comparisons, plus unary predicates and cheap scoring. This is not the complexity of the entire run.

Expensive scoring processes at most the pool per axis. Cardinality greedy selection scans the pool repeatedly, roughly O(KM) before callback costs. Token selection can perform roughly O(M²) scanning. Set constraints may scan the selected set, and built-in coverage rebuilds covered-key sets during gain evaluation. Requirement repair adds its own search cost.

Pool score storage grows with M times the number of axes, plus payloads, selection state, and rejection details. Keep can add O(N) retained payloads. Count and bounded Sample bound rejection retention, but cannot remove memory already allocated by a caller passing a materialized list. Python conversion adds overhead too.

examples/throughput.rs is a reproducible synthetic workload. Its expensive scorer simulates work; it does not measure neural inference. Record the command, processor, compiler, profile, features, input size, pool capacity, scorer workload, and retention policy when reporting timings. Historical figures without those conditions are not portable performance promises.

Known limits

• Admission can discard candidates needed for the best constrained set; there is no automatic full-input retry.
• Lower-bound repair can fail even when a feasible set exists.
• Numerical inputs and mathematical declarations are not fully validated.
• Duplicate IDs are not detected; audit strings can collapse numeric and text IDs.
• Fusion evidence does not record the full objective or repair trajectory.
• Token diagnostics have the limitations described in Results and audit evidence.
• Python exposes built-in constraints and coverage, not arbitrary Python implementations of Rust constraint and objective traits.
• The library is alpha. Durable output schemas and cross-version compatibility remain application integration responsibilities.

Troubleshooting

16. Repository layout

17. License

Licensed under Apache-2.0. See Cargo.toml for package metadata and the repository for source.