Crate purrassist 

Intent-aware assistance for imperfect AI output.

PurRAssist

Assistance for AIs that get the details almost right. This facade exposes the pure recovery engines and isolated syntax integration.

Status: 0.1.0. This crate is the Rust interface of PurRAssist, one engine with three equal interfaces: the Rust crates (this one), the MCP server and the CLI (purrassist-cli).

use purrassist::{Outcome, RecoveryRequest, Schema};

let schema = Schema::compile(r#"{
  "type": "object",
  "required": ["temperature"],
  "properties": {"temperature": {"type": "number"}},
  "additionalProperties": false
}"#)?;

let answer = schema.recover("[[{temperatur: '42',}]]", RecoveryRequest::default());
match answer.outcome {
    Outcome::Resolved(value) => assert_eq!(value.to_json(), r#"{"temperature":42}"#),
    Outcome::BestGuess(value) => println!("inferred: {}", value.to_json()),
    Outcome::Ambiguous(values) => println!("{} interpretations", values.len()),
    Outcome::Unresolved => println!("{}", answer.receipt.stopped),
}

Tool-call recovery

tool_call recovers the tool calls of one raw model turn against the OpenAI, MCP, or Anthropic declarations the model was shown (read byte for byte), with per-call outcomes, itemized repairs, the turn’s finish, and a receipt; it never executes a call. Twelve dialects ship: qwen3-coder-xml.v1, hermes.v1, openai-tool-calls.v1, llama3-json.v1, mistral-v3.v1, mistral-v11.v1, deepseek-v3.1.v1, deepseek-v3.v1, kimi-k2.v1, anthropic-tool-use.v1, harmony.v1, and bare-json.v1.

use purrassist::Outcome;
use purrassist::tool_call::{ToolRecoveryRequest, ToolSet};
let declarations = r#"[{"type":"function","function":{"name":"get_weather","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}]"#;
let tools = ToolSet::from_openai(declarations, purrassist::Budget::default()).unwrap();
let turn = br#"[TOOL_CALLS] [{"name": "get_weather", "arguments": {"city": "Oslo"}}]"#;
let result = tools.recover(turn, &ToolRecoveryRequest::default());
let Outcome::Resolved(calls) = result.outcome else { panic!("unexpected outcome") };
assert_eq!(calls.calls[0].tool.as_deref(), Some("get_weather"));
assert_eq!(calls.calls[0].dialect.id(), "mistral-v3.v1");

A tool’s schema and its typed arguments can come from one Rust struct, through the purrassist::ToolDefinition and purrassist::ToolEnum derives (purrassist-derive):

use purrassist::json;
use purrassist::tool_call::{FromNode, ToolArguments};

#[derive(purrassist::ToolEnum, Debug, PartialEq)]
enum Order {
    Asc,
    Desc,
}

/// Search the index.
#[derive(purrassist::ToolDefinition, Debug, PartialEq)]
#[tool(effects = read_only)]
struct Search {
    /// What to look for.
    query: String,
    #[param(default = 10)]
    limit: u32,
    order: Option<Order>,
}

assert_eq!(Search::tool_definition().name(), "search");
let arguments = json::parse(r#"{"query": "cats", "order": "Desc"}"#)?;
assert_eq!(
    Search::from_node(&arguments),
    Ok(Search { query: "cats".into(), limit: 10, order: Some(Order::Desc) }),
);

Inspect every result’s status and receipt. Validation does not turn an invented value into a fact. Ambiguity and resource exhaustion are explicit outcomes.

Version 0.1.0, with executable conformance, recovery, resource, and portability qualification. Capabilities, known limitations, verification, and provenance are recorded in the qualification record. First-party code is licensed under MIT OR Apache-2.0 OR MulanPSL-2.0.

Re-exports

pub use purrassist_syntax as syntax;

Modules

contract

Pure first-party assistance engines and contracts. Shared assistance, resource-accounting, and evidence contracts.

digest

Pure first-party assistance engines and contracts. Dependency-free SHA-256 content identities, following FIPS 180-4 section 6.2. These identify bytes; they do not authenticate their author.

edits

Pure first-party assistance engines and contracts. Source-bound text edits with overlap checks, conditional inverse plans, and receipts.

embeddings

Pure first-party assistance engines and contracts. Caller-owned embedding index; no model, transport, or ambient state.

grammar

Pure first-party assistance engines and contracts. Weighted, invertible grammars for model output markup.

intent

Pure first-party assistance engines and contracts. Caller-owned semantic rules: explicit concepts, modifiers, and auditable resolution.

json

Pure first-party assistance engines and contracts. Ordered, source-addressed JSON with exact decimal values.

markdown

Pure first-party assistance engines and contracts. Source-preserving Markdown block indexing and section edits.

matching

Pure first-party assistance engines and contracts. Deterministic evidence-bearing matching. Scores are ranking units, not probabilities.

patch

Pure first-party assistance engines and contracts. The crate’s single edit representation.

paths

Pure first-party assistance engines and contracts. Pure candidate-path resolution. Matching never opens or authorizes a file.

pattern

Pure first-party assistance engines and contracts. Budgeted regular-expression evaluation for schema patterns.

provenance

Pure first-party assistance engines and contracts. A deduplicated derivation forest for ambiguous receipts.

schema

Pure first-party assistance engines and contracts. Compiled JSON Schema constraints and source-addressed validation.

text

Pure first-party assistance engines and contracts. First-party Unicode normalization and text comparison foundations.

tool_call

Pure first-party assistance engines and contracts. Typed tool definitions compiled into validated, indexed tool sets.

wire

Pure first-party assistance engines and contracts. Versioned JSON representations shared by command-line and protocol surfaces.

Structs

AssistResult

Pure first-party assistance engines and contracts. The answer together with its evidence; receipts also accompany failures.

Budget

Pure first-party assistance engines and contracts. Explicit limits. Helper access is disabled until the caller budgets it.

CancellationToken

Pure first-party assistance engines and contracts. Caller-owned, monotonic cancellation signal shared by related operations.

Governor

Pure first-party assistance engines and contracts. A sticky governor: after exhaustion or cancellation, every charge fails.

Receipt

Pure first-party assistance engines and contracts. An ordered, versioned audit receipt. Ledgers contain no hidden model reasoning.

RecoveryRequest

Effort, resource, and invention policy for JSON recovery. Recovery policy; effort changes search bounds, never the schema’s constraints.

Schema

Compiled schema validation and recovery entry point. A compiled schema plus caller-supplied external resources. Compilation does no I/O.

ScratchLease

Pure first-party assistance engines and contracts. An opaque byte reservation, charged eagerly and released exactly once, automatically, when dropped.

ScratchMap

Pure first-party assistance engines and contracts. An ordered association list keyed by K, whose growth is charged.

ScratchMeter

Pure first-party assistance engines and contracts. The shared, atomic scratch-byte counter behind a Governor and every ScratchLease/ScratchVec/ScratchString/ScratchMap it issues.

ScratchString

Pure first-party assistance engines and contracts. A String whose growth is charged before it is allocated.

ScratchVec

Pure first-party assistance engines and contracts. A Vec<T> whose growth is charged against a ScratchMeter before it is requested from the allocator, and whose charge is released exactly once, on drop.

Enums

Effort

Pure first-party assistance engines and contracts. Increasing recovery effort; all presets remain finite.

Outcome

Pure first-party assistance engines and contracts. An answer’s epistemic status, independently of schema or syntax validation.

StopReason

Pure first-party assistance engines and contracts. Why an operation stopped; exhaustion never asserts unsatisfiability.

Constants

RECEIPT_VERSION

Pure first-party assistance engines and contracts. Version of the machine-readable receipt contract.

Traits

ScratchCharge

Pure first-party assistance engines and contracts. A type’s portable, target-independent scratch charge.

Derive Macros

ToolDefinition

Derives ToolArguments, ToolParameter, ToolItem and FromNode for a struct of named fields, so the struct is its own tool definition and its own typed arguments. Unlike purrassist_derive::ToolDefinition, the generated code reaches the engine through ::purrassist, so a crate needs only the purrassist dependency (no crate = attribute, no direct core dependency).

ToolEnum

Derives ToolParameter, ToolItem and FromNode for an enum of unit variants (a string enumeration), generating paths through ::purrassist. See ToolDefinition for the facade rationale and purrassist_derive::ToolEnum for the attributes and errors.