Rust SDK — SDK — NeuronScope

Overview & Use Cases

The neuronscope Rust crate provides zero-copy, memory-mapped reading and comparison of.nsz telemetry artifacts produced by the Python SDK. It is designed for high-throughput, latency-critical environments where the overhead of a Python runtime is unacceptable.

Typical use cases include:

CI/CD Regression Gating: Check whether a new model deployment introduces quality or latency regressions inside a CI pipeline without a full Python environment.
Dashboard Services: Read and expose artifact metadata, fingerprints, and evaluation metrics to web dashboards with minimal overhead.
Benchmark Aggregators: Parse and aggregate thousands of .nsz files in parallel using Rust's async runtime and rayon.
Real-time Monitoring: Watch an artifact directory for new files and emit metrics to Prometheus or CloudWatch on arrival.
Edge Deployments: Validate that an AI model's fingerprint matches the expected checksum before allowing inference on edge hardware.

Installation

Add neuronscope to your Cargo.toml:

Cargo.toml

toml

[dependencies]
neuronscope = { version = "0.6", features = ["compare", "async"] }
 
# Available feature flags:
# compare  -- regression diffing and quality delta metrics
# async    -- tokio-based async file I/O and directory watching
# json     -- serde JSON serialization of all artifact types
# metrics  -- prometheus metrics exporter integration

Reading .nsz Artifacts

The crate uses memory-mapped I/O for zero-copy access to large .nsz artifact files. Telemetry data is accessed lazily — only the sections you query are loaded into RAM.

main.rs

rust

use neuronscope::Artifact;

fn main() -> anyhow::Result<()> {
    // Open with zero-copy memory-mapped I/O
    let artifact = Artifact::open("production_v3.nsz")?;

    // Artifact header metadata
    println!("Name:    {}", artifact.name());
    println!("Version: {}", artifact.sdk_version());
    println!("Created: {}", artifact.created_at());

    // Fingerprint information
    let fp = artifact.fingerprint();
    println!("Arch:    {}", fp.arch);
    println!("Weights: {}", fp.weights);
    println!("Prompt:  {}", fp.prompt);
    println!("Env:     {}", fp.environment);

    Ok(())
}

Fingerprint Inspection

Fingerprints can be validated against known checksums before allowing model inference — useful for integrity checks in production edge deployments.

fingerprint.rs

rust

use neuronscope::Artifact;

const EXPECTED: &str = "fp:full:a3c1f8b24d7e9012c456f789abcdef01";

fn validate_integrity(path: &str) -> anyhow::Result<bool> {
    let artifact = Artifact::open(path)?;
    let fp = artifact.fingerprint().full();

    if fp == EXPECTED {
        println!("Model integrity verified: {fp}");
        Ok(true)
    } else {
        eprintln!("Fingerprint mismatch!");
        eprintln!("  Expected: {EXPECTED}");
        eprintln!("  Actual:   {fp}");
        Ok(false)
    }
}

Artifact Comparison

With the compare feature enabled, the crate can diff two artifacts using the same Regression Comparer Engine logic as the Python SDK — exposing quality deltas, latency regressions, and structural changes.

compare.rs

rust

use neuronscope::{Artifact, compare};

fn main() -> anyhow::Result<()> {
    let baseline  = Artifact::open("baseline_v1.nsz")?;
    let candidate = Artifact::open("candidate_v2.nsz")?;

    let diff = compare(&baseline, &candidate)?;

    let q = diff.quality_delta();
    let h = diff.hallucination_delta();
    let l = diff.latency_p95_delta_ms();
    let c = diff.token_cost_delta();

    println!("Quality delta:      {q:+.4}");
    println!("Hallucination D:    {h:+.4}");
    println!("P95 Latency D ms:   {l:+.0}");
    println!("Token Cost D:       {c:+.6}");

    if diff.has_regression(0.05) {
        let reason = diff.regression_reason();
        eprintln!("REGRESSION: {reason}");
        std::process::exit(1);
    }

    println!("No regression detected.");
    Ok(())
}

CI/CD Regression Gating

A common pattern is to use the Rust crate inside a CI pipeline binary that gates deployments based on quality thresholds — without requiring a full Python environment.

ci_gate.rs

rust

use neuronscope::{Artifact, compare};
use std::process;

fn main() -> anyhow::Result<()> {
    let args: Vec<String> = std::env::args().collect();
    let baseline_path  = &args[1];
    let candidate_path = &args[2];
    let threshold: f64 = args.get(3)
        .and_then(|s| s.parse().ok())
        .unwrap_or(0.05);

    let baseline  = Artifact::open(baseline_path)?;
    let candidate = Artifact::open(candidate_path)?;
    let diff = compare(&baseline, &candidate)?;

    println!("NeuronScope Regression Gate");
    let q = diff.quality_delta();
    let h = diff.hallucination_delta();
    let l = diff.latency_p95_delta_ms();
    println!("  Quality D:        {q:+.4}");
    println!("  Hallucination D:  {h:+.4}");
    println!("  Latency P95 D ms: {l:+.0}");

    if diff.has_regression(threshold) {
        let reason = diff.regression_reason();
        eprintln!("GATE FAILED: {reason}");
        process::exit(1);
    }

    println!("GATE PASSED -- candidate deployment approved.");
    Ok(())
}

Async & Streaming Access

Enable the async feature for tokio-powered file access and directory watching:

async.rs

rust

use neuronscope::AsyncArtifact;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Watch an artifact directory for new .nsz files
    let mut watcher = neuronscope::watch_dir("./artifacts/").await?;

    while let Some(event) = watcher.next().await {
        match event {
            neuronscope::WatchEvent::Created(path) => {
                let artifact = AsyncArtifact::open(&path).await?;
                let name  = artifact.name();
                let fp    = artifact.fingerprint().full();
                let qual  = artifact.quality_score();
                let hall  = artifact.hallucination_score();

                // Emit metrics to Prometheus
                metrics::gauge!("ns_artifact_quality",      qual);
                metrics::gauge!("ns_artifact_hallucination", hall);
                println!("New artifact: {name} ({fp})");
            }
            _ => {}
        }
    }

    Ok(())
}

Design Scope & Boundaries

The Rust crate deliberately excludes the following capabilities:

Recording & Probing: The crate cannot attach probes to models or record activations. All recording is done by the Python SDK. The .nsz artifact is the only shared interface.
Model Wrapping: The Rust crate does not wrap PyTorch, JAX, or any other framework. It operates entirely on serialized artifact data.
LLM API Calls: No LLM provider clients are included. Use the Python SDK for model inference.