genai-retrieval

sparq genai-retrieval

The AI/agent surface of the sparq RDF+SPARQL engine, in two opt-in, network-free crates that compose:

• sparq-introspect — mines the effective schema a graph actually uses (classes, per-class predicate usage, observed domain/range, characteristic sets, cross-class join hints, namespaces) by sorted scans over the store indexes — and renders it as a token-budgeted text "schema card", VoID (N-Triples), SHACL node shapes (characteristic sets → sh:NodeShape), or full JSON for LLM grounding / agent retrieval context.
• sparq-nlq — a deliberately lean NL→SPARQL loop: ground (with the introspect summary) → generate (an Llm behind a trait) → validate (spargebra parse) → execute (sparq-engine under a QueryBudget) → repair (≤ N rounds). The LLM sits behind a record/replay seam so CI is fully offline; a live Anthropic client is behind an opt-in live feature.

Both crates are read-only over sparq-core's public API. Nothing in the workspace depends on them; the default engine build compiles neither and carries zero GenAI code.

Quickstart

Cargo.toml:

[dependencies]
sparq-core       = "0.1"
sparq-introspect = "0.1"
sparq-nlq        = "0.1"   # add features = ["live"] for the Anthropic backend

Add features = ["schema-diff"] to sparq-introspect when comparing two mined schemas. The feature is off by default.

Grounding context from a graph (no LLM, no network):

use sparq_core::Graph;
use sparq_introspect::Introspection;

let graph = Graph::load_str(turtle_or_ntriples, "turtle")?;   // or "ntriples"
let ix = Introspection::build(&graph);

let card = ix.to_text_summary(2500);          // prompt-ready schema card, ≤ 2500 chars
let json = ix.to_json();                       // full machine surface for an agent
let void = ix.to_void("http://ex.org/dataset");// W3C VoID, as N-Triples
let shacl = ix.to_shacl();                      // characteristic sets → SHACL node shapes (N-Triples)
# Ok::<(), String>(())