eyeron

Eyeron

Eyeron combines Eye with the sound of iron, reflecting explainable reasoning and its place in the Eyereasoner family.

Eyeron is a Rust-based Notation3 (N3) reasoner that turns facts and rules into conclusions with verifiable proofs. It can be used as a command-line program, embedded as a Rust library, or run in a browser through WebAssembly.

[!TIP] Start here: Learn how Eyeron’s source code works, or try Eyeron now in the browser.

Highlights

• forward rules with log:implies / =>;
• goal-directed backward rules with log:impliedBy / <=;
• generated rules and quoted-formula conclusions;
• N3 proof output with -p / --proof;
• RDF 1.1 and RDF 1.2 input profiles for Turtle, N-Triples, N-Quads, and TriG;
• finite RDF Message Log replay and message-at-a-time streaming;
• indexed fact lookup and an agenda path for long single-premise rule chains;
• native Rust and WebAssembly APIs.

Eyeron supports prefixes and bases, variables, blank nodes, literals, RDF lists, quoted formulas, log:query, log:outputString, owl:sameAs through =, virtual rdf:first / rdf:rest list matching, and deterministic blank nodes generated by repeated rule firings.

Implemented built-ins

The following built-ins are implemented in the reasoner:

• log: equalTo, notEqualTo, collectAllIn, forAllIn, conclusion, conjunction, includes, notIncludes, uri, rawType, dtlit, langlit, content, semantics, semanticsOrError, parsedAsN3, and skolem;
• math: sum, difference, product, quotient, integerQuotient, remainder, exponentiation, negation, absoluteValue, rounded, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, degrees, greaterThan, lessThan, notGreaterThan, notLessThan, equalTo, and notEqualTo;
• list: first, rest, firstRest, last, length, member, memberAt, in, notMember, remove, append, reverse, sort, iterate, and map;
• string: lessThan, greaterThan, notLessThan, notGreaterThan, concatenation, contains, containsIgnoringCase, startsWith, endsWith, equalIgnoringCase, notEqualIgnoringCase, format, matches, notMatches, replace, and scrape;
• time: year, month, day, hour, minute, second, timeZone, and localTime;
• crypto: sha.

String regular expressions use Rust’s Unicode-aware regex engine, with compatibility handling for the look-around forms exercised by the bundled conformance tests.

Build

cargo build --release

The executable is written to target/release/eyeron.

Command-line use

Run an N3 file:

cargo run --release -- examples/socrates.n3

Generate a proof:

cargo run --release -- --proof examples/socrates.n3

Read N3 from standard input by passing -:

printf '@prefix : <http://example.org/> . :Socrates a :Man . { ?x a :Man . } => { ?x a :Mortal . } .' \
  | cargo run --release -- -

Multiple files are merged into one document. HTTP and HTTPS URLs can be mixed with local paths:

cargo run --release -- rules.n3 data.n3
cargo run --release -- rules.n3 https://example.org/data.ttl

Eyeron selects RDF input by extension for .ttl, .nt, .nq, and .trig. Use --rdf when reading Turtle from standard input or when RDF-compatible output is required:

cargo run --release -- data.trig
cargo run --release -- --rdf - < data.ttl

Run eyeron, eyeron -h, or eyeron --help to display help. Running without arguments is equivalent to -h.

RDF Messages

Eyeron recognizes RDF Message Logs containing a VERSION "*-messages" directive and MESSAGE or @message . boundaries.

In normal mode, the complete log is exposed as a replay graph using the eymsg: vocabulary. Every message receives an envelope and, for a non-empty payload, a named quoted formula that rules can inspect atomically with log:includes.

cargo run --release -- --rdf \
  examples/rdf-messages.n3 \
  examples/input/rdf-messages.trig

For message-at-a-time processing, use --stream-messages. Eyeron reads local-file or HTTP(S) input incrementally, reasons over each message with the supplied N3 program, writes that message’s RDF result, and flushes the output before reading the next message:

cargo run --release -- --rdf --stream-messages \
  examples/alma-rdf-messages.n3 \
  tests/input/alma-rdf-messages-small.nt

Each streamed message is evaluated independently. The current streaming path does not retain derived facts between messages and does not accept the message log through standard input.

Rust library

The high-level API parses N3, runs the reasoner, and returns newly derived output:

fn main() -> eyeron::Result<()> {
    let output = eyeron::reason(r#"
        @prefix : <http://example.org/> .

        :Socrates a :Man .
        { ?x a :Man . } => { ?x a :Mortal . } .
    "#)?;

    assert!(output.contains(":Socrates a :Mortal"));
    Ok(())
}

For lower-level integration, use parse_n3, parse_rdf12, or parse_rdf_message_log, followed by reason_document. The returned ReasonerResult reports completion status, reached safety limits, semantic errors, statistics, derived facts, and proof data.

Browser playground

Try the hosted playground at https://eyereasoner.github.io/eyeron/playground.

To build and serve it locally, install wasm-pack, then run:

cargo playground
python3 -m http.server

Open http://localhost:8000/playground.html. The cargo playground alias runs the eyeron-playground-build helper, which rebuilds the pkg/ WebAssembly package and removes generated files that are not needed by the playground.

For repeated browser or RDF-JS inference, construct one EyeronSession. Its N3 program is parsed and its forward-rule index is built once; each reason call uses an independent data batch:

const session = new EyeronSession(runtimeN3, false);
const output = session.reason(messageNQuads, true, "nquads");
const report = JSON.parse(session.reasonReport(nextMessageNQuads, true, "nquads"));
session.free();

The constructor’s second argument enables proof output. The two run arguments select RDF output and the input RDF syntax, matching reasonWithData. reasonReport includes iteration, matching, fact, and rule counts.

Testing

Run the complete optimized test suite with:

cargo test --release

The suite covers parser and built-in unit tests, CLI behavior, regressions, example outputs, proof goldens, the bundled Notation3 conformance suite, and the local W3C RDF 1.1/1.2 manifest mirror.

Run the focused regression, packaged-example, or playground checks independently with:

cargo test --release --test regressions
cargo test --release --test examples
cargo test --release --test playground

Refresh both vendored upstream test suites with:

./scripts/sync-test-suites

This synchronizes notation3tests from Codeberg, refreshes the W3C RDF 1.x manifests from GitHub, and runs the RDF manifest checks with --release.

Run only the W3C RDF sweep with:

cargo test --release --test w3c_rdf

The W3C runner writes reports/w3c-rdf-earl.ttl. See tests/w3c_rdf/README.md for filtering, refresh, cache, verbosity, and EARL options.

Examples

A small representative set:

# Basic forward reasoning
cargo run --release -- examples/socrates.n3

# Backward reasoning with proof output
cargo run --release -- --proof examples/backward.n3

# List and string built-ins
cargo run --release -- examples/list-builtins-tests.n3
cargo run --release -- examples/string-builtins-tests.n3

# Incremental RDF Message processing
cargo run --release -- --rdf --stream-messages \
  examples/alma-rdf-messages.n3 \
  tests/input/alma-rdf-messages-small.nt

More inputs are available under examples/, with expected results in examples/output/ and proof goldens in examples/proof/.

Current limitations

• -s / --stream is retained for command-line compatibility but ordinary N3 output is still emitted after the fixpoint;
• streamed RDF Messages are independent: no persistent cross-message fact store or window state is maintained, and stdin is not supported by --stream-messages;
• log:content, log:semantics, and log:semanticsOrError do not dereference arbitrary network resources; their external-resource behavior is deterministic and limited to the bundled conformance cases;
• persistent stores and custom external built-in modules are not implemented;
• proof output does not yet include every possible trace comment or explanation detail;
• Eyeron implements the N3 features and built-ins listed above, not every extension in every historical N3 implementation.

Project layout

src/                  Parser, reasoner, proof generation, output, CLI, and Wasm API
examples/             N3 and RDF Message examples
examples/output/      Expected derived output
examples/proof/       Expected proof output
tests/                CLI, regression, conformance, and W3C RDF tests
tools/                Playground build helper
reports/              Generated and checked-in reports

License

MIT. See LICENSE.md.

This site is open source. Improve this page.