Reasoning with N3 · Chapter 9 of 10

Chapter 9

Reference

Every surface, option, vocabulary term and error in one place, followed by what the design leaves out on purpose.

Enabling it

Reasoning lives in the crate tm-n3, behind the facade feature n3. The feature is off by default, does not turn on exec, and combines with every other feature. Without it, neither tm-n3 nor eyeron is in the dependency tree. The core tier can reason: --no-default-features --features n3 builds without the query front ends.

Cargo.toml

[dependencies]
tiramemsu = { git = "https://github.com/Volland/tiramemsu", features = ["n3"] }

eyeron comes from crates.io with its HTTP client left out (default-features = false).

Rust API

tiramemsu, feature n3

use tiramemsu::{ReasonOptions, ReasonScope, Rules, TimeMode, TxN3};

// Read-only reasoning on any view.
impl View<'_> {
    pub fn reason(&self, rules: Rules, opts: &ReasonOptions) -> Result<ReasonResult>;
    pub fn rule_set_info(&self, rule_set: &Value) -> Result<RuleSetInfo>;
}

// Storing rule sets, inside a transaction (trait TxN3). Returns the eid of R.
fn store_rules(&mut self, rule_set: Value, n3: &str) -> Result<Eid>;

// Writing conclusions as derived beliefs.
impl Db {
    pub fn materialize(&self, rule_set: Value, opts: &MaterializeOptions) -> Result<MaterializeReport>;
}

pub enum Rules {
    Text(String),     // N3 text, parsed for this run
    Stored(Value),    // the live n3:source of a rule set in the view
}

ReasonOptions

ReasonResult

MaterializeOptions

MaterializeReport carries reasoned_at, the commit’s TxReport, derived, existing, widened, stale_support and status (chapter 7). RuleSetInfo carries monotonicity (Monotonic, NonMonotonic { rule, builtin } or ClockDependent { rule, builtin }), the rule count rules, the body predicates, and whether a body has a variable predicate.

Vocabulary

Prefixes: n3: is urn:tiramemsu:n3:, tm: is urn:tiramemsu:tm:, sys: is urn:tiramemsu:sys:. Anonymous nodes, blank nodes and statements appear in N3 as urn:tiramemsu:node:N, urn:tiramemsu:bnode:N and urn:tiramemsu:stmt:N. Virtual triples are generated only when a rule body uses them and are never stored. tm: cannot be written.

Errors

reason never fails for a fired fuse or a reached limit. It reports them in contradiction and status.

Python, Node.js and the browser

All three go through the JSON bridge, with a read operation reason, a transaction operation storeRules and a database operation materialize. The bridge takes the same options and returns the same result as Rust:

{"op": "reason", "rules": "{ ?x a <urn:tiramemsu:v:Human> } => { ?x a <urn:tiramemsu:v:Mortal> }."}

The bindings wrap the bridge operations:

Python

MORTALITY = "urn:tiramemsu:v:mortality"
with db.transact() as tx:
    tx.store_rules(MORTALITY, open("mortality.n3").read())

result = db.now().reason(rule_set=MORTALITY)
preview = db.materialize(MORTALITY, dry_run=True)

Node.js

const MORTALITY = "urn:tiramemsu:v:mortality";
db.transact((tx) => { tx.storeRules(MORTALITY, rulesText); });

const result = db.now().reason({ ruleSet: MORTALITY });
const preview = db.materialize(MORTALITY, { dryRun: true });

MCP

An agent that may only read can still ask what follows from memory. Writing rules or conclusions needs a server started without --read-only.

Command line

tm reason <file> (--rules <path> | --rule-set <iri>) [--as-of <tx> | --as-of-instant <t>]
          [--valid-at <instant> | --valid-during <from>..<to>] [--graph <iri>]... [--atemporal] [--max-segments <n>] [--proof] [--json]
tm rules put  <file> <iri> <path>
tm rules show <file> <iri>
tm materialize <file> <iri> [--valid-during <from>..<to>] [--graph <iri>]...
               [--require-complete] [--dry-run]

--as-of takes a transaction number. Instants are epoch milliseconds or RFC 3339 dates and date-times, and either side of a window may be empty. --json prints the bridge result.

Limits and non-goals

• No non-monotonic materialization. Negation as failure, collecting and the clock work in reason only. materialize refuses them, because the cascade could not keep their conclusions honest.
• One proof per conclusion. eyeron returns one proof per conclusion per segment. A stored conclusion rests on one of its possible supports. It is sound, and a later run restores it if that support goes while another remains.
• No SPARQL or Cypher function. Neither language can call the reasoner. Materialized conclusions are ordinary statements, and sys:derivedFrom and n3:derivedBy are ordinary predicates, so every dialect reads them.
• Nothing runs on commit. Reasoning never runs automatically after a write, and never inside the writer. Call materialize when you want conclusions updated.
• Backward rules stay in the run. They see the loaded statements only. There is no backward chaining over the store and no OWL profile.
• No I/O from rules. Rules cannot reach the network or the file system.
• Sweeps cost segments. A run costs about one reasoner pass per segment, capped by max_segments.
• Opt-in. The n3 feature is off by default, and eyeron comes from crates.io.

Credits

Reasoning is done by eyeron, a native Rust N3 reasoner by Jos De Roo, released under the MIT license, from the family of the EYE reasoner. Tiramemsu adds the mapping to statements, the two clocks and grounded materialization around it.