PurRAssist

PurRAssist

Assistance for AIs that get the details almost right.

PurRAssist recovers intent from imperfect JSON, names, paths, and text. Give a decoder a schema and an effort level: it searches composed corrections, validates the complete result, and returns evidence of what changed. A schema-valid guess is still a guess. Ambiguous alternatives remain visible. Use it as a Rust crate, an MCP server, or a CLI.

Version 0.1.0. Published as rust-v0.1.0: the six crates are on crates.io, with documentation on docs.rs. Read the changelog, the implementation contract for the accepted scope, and the qualification record for executable evidence. Its known limitations are not release blockers. The release procedure records the package and registry gates.

One engine, three interfaces

One recovery engine, three equal ways to use it: as a Rust crate, as an MCP server, and as a command-line tool. They share the same engines and the same evidence receipts.

Rust crate

cargo add purrassist

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), }

Ok::<(), purrassist::schema::SchemaError>(())

<!-- three-interfaces-rust:end -->

The purrassist crate is the Rust interface: it re-exports the pure engines, the syntax integration and the derives.

MCP server

cargo install purrassist-cli

purrassist mcp --root /path/to/workspace

Add the server to any MCP client that launches stdio servers:

{

"mcpServers": { "purrassist": { "command": "purrassist", "args": ["mcp", "--root", "/path/to/workspace"] } } }

The server speaks newline-delimited JSON-RPC over stdio. Every tool is listed in the tool reference. Starting the server creates a .purrassist/ directory in the root, where the file tools keep their transaction journals; the call command below does the same.

CLI

purrassist decode --schema schema.json --input response.txt

purrassist call match_strings --root DIR < args.json

purrassist call TOOL --root DIR reads a JSON argument object from stdin and invokes the same operation used by MCP: for every registered tool the CLI and MCP results are identical, which the test every_registry_entry_has_a_fixture_validated_through_cli_and_mcp checks tool by tool. The convenience commands decode and match are shortcuts with their own output, not the tools' output. purrassist validate prints exactly the validate_json tool's output.

Crate map

Six crates make up the release set, published in this order:

Three workspace crates are internal and not published: wasm-harness (native, WASI and browser-WASM acceptance transcripts), purrassist-helper-census (the duplicate-functionality census), and purrassist-toolgraph (validated caller-owned vocabulary, loss profiles, context masks and exact output byte bounds, with a direct consumer of the supported upstream plain FnO schema profile; plain-number support, graph loading and execution remain planned).

Capabilities

The pure core owns its JSON parser, exact decimal arithmetic, schema validator, Unicode normalization, edit distances, phonetic matching, semantic rules, recovery search, and receipts. It has zero third-party runtime dependencies. The isolated syntax crate uses the pinned Tree-sitter grammar family; see the dependency inventory. Each tool is described in the tool reference.

Prepared grammars also support grammar::print::canonical_governed for complete canonical call, result and declaration output with borrowed bindings. The canonical_print example prepares its grammar separately and exercises semantic and resource refusals. Cold grammar compilation, higher-level emitter preparation and full seeded/witness generation remain outside this operation; tool-graph integration remains under #36.

Current surfaces include:

• JSON recovery with nested unwrapping, syntax repair, approximate keys/enums, stringified values, whole-schema validation, and invented values (required properties, patternProperties/additionalProperties/dependentSchemas fills, propertyNames-conformant key repairs) produced by a first-party witness-generation algebra rather than a schema-blind heuristic.
• Unicode, lexical, Levenshtein, unrestricted Damerau-Levenshtein, English Soundex, aliases, and contextual path matching.
• Explicit semantic domain rules and caller-supplied embedding similarity.
• Source-bound text edits, bounded fuzzy replacement, relocatable unified diffs, overlap checks, exact-byte undo, and a Markdown editing index and structural section/list/table/reference operations. All 1,324 pinned CommonMark/GFM examples have exact rendering checks, alongside generated preservation properties and independent differential campaigns.
• Python, Rust, JavaScript/JSX, TypeScript/TSX grammar inspection and validated punctuation repairs. Grammar acceptance does not prove program correctness.
• Journaled single-file replacement and conditional undo for coordinated writers.
• Tool-call recovery from raw model output: weighted, invertible dialect grammars with best-first markup repair, resolution against typed tools or lossless OpenAI/MCP/Anthropic declarations (Draft 2020-12 or Draft-07 schemas), per-call outcomes with itemized repairs, conservative guards for mutating tools, and re-emission as any dialect or the OpenAI tool_calls array. Call markup of a dialect that is not built in yet, or not in the request's allow-list, is reported as a rejected attempt (unsupported_dialect), never silent content. Twenty-three dialects are built in: 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, gemma3-tool-code.v1, glm-4.5.v1, bare-json.v1, pythonic.v1, deepseek-v3-stripped.v1, deepseek-v3.1-stripped.v1, harmony-stripped.v1, hermes-stripped.v1, kimi-k2-stripped.v1, llama3-json-stripped.v1, mistral-v11-stripped.v1, and mistral-v3-stripped.v1. The marker-suppressed variants use derived grammar recipes; callers add their own with the grammar DSL. Typed tool definitions derive from Rust structs and enums with #[derive(ToolDefinition)] and #[derive(ToolEnum)] (the zero-dependency purrassist-derive crate, re-exported by the facade; see the example below). Streaming recognition (#16) and provider streaming events (#17) remain tracked. See tool-call recovery.
• CLI, stdio MCP, and resumable helper request/response adapters (prepare_helper and complete_helper; see helpers). No model is required, loaded, or contacted by default.

A tool's schema and its typed arguments can come from one Rust struct:

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 , }

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) }), );

Ok::<(), Box >(())

<!-- derive-example:end -->

Schema::generate_witness/generate_witness_governed separately implement a witness-generation algebra (canonicalize, eliminate not by De Morgan duality, merge allOf constraints, and generate a type-directed value, recursing over $ref/$dynamicRef): its result is a validated Witness, a closed-form Unsatisfiable proof (never inferred from search exhaustion), or an honest Exhausted, and recovery invents every guessed value through this same algebra. Schema::compile_governed and with_resources_governed return typed CompilationError values separating invalid schemas from resource failures. Pass the same governor to recover_governed to share the total preparation and recovery budget. The decode_json tool does this automatically. The convenience compilation methods use the default finite budget.

purrassist_core::patch::Patch (an ordered, non-overlapping, source-digest- bound set of byte-range replacements) is the crate's single edit representation; edits::EditPlan/TextEdit are aliases for it. Beyond apply, it exposes a governed invert, compose, commute, rebase, and diff algebra; apply_edit/apply_file use rebase/diff to reconcile a stale plan against an intervening change through an explicit rebase_from input. See plan application. The Rust markdown::Document API's structural operations — insert_section, remove_section, move_section (with optional re-leveling of the moved section's own heading), rename_heading, ListItemEdit::Move, renumber_list, TableRowEdit::Move, TableColumnEdit::Move, and add_reference/relabel_reference/remove_reference/unlink_reference (which rewrite every shortcut/collapsed/full-reference use resolving to the affected definition) — are exposed through the host tool plan_markdown_structure, selected by a typed op (section_insert, section_remove, section_move, section_rename, list_move, list_renumber, table_row_move, table_column_move, reference_add, reference_relabel, reference_remove, reference_unlink). Each is governed, digest-bound, reparse-checked, and provides an exact inverse.

The Rust markdown::InlineFragment layer retains exact byte spans and renders code spans, emp