Skip to content

docs: add sparq development notice to the top of the README - #1959

Draft
jeswr wants to merge 2 commits into
mainfrom
docs/sparq-notice
Draft

docs: add sparq development notice to the top of the README#1959
jeswr wants to merge 2 commits into
mainfrom
docs/sparq-notice

Conversation

@jeswr

@jeswr jeswr commented Jul 4, 2026

Copy link
Copy Markdown
Member

🚧 Draft — agent-generated, for @jeswr's wording/figures review before landing

Adds a > [!NOTE] banner at the very top of the README (directly under the H1) announcing that @jeswr is now actively developing sparq, for eye-js users to find the successor project. Nothing else in the README is touched.

Direct eye-js-vs-sparq DeepTaxonomy comparison (+ the caveat)

The speed line no longer reuses sparq's sparq-vs-native-EYE figure ("orders of magnitude faster than the native EYE reasoner… ≈62×"). That 62× compared sparq against the standalone native EYE binary running a full forward --pass closure — a different task from what eye-js's own bench actually runs, so quoting it against eye-js would have been misleading.

Instead the notice now states a direct eye-js-vs-sparq DeepTaxonomy-1k comparison with measured numbers:

  • sparq (native Rust): ≈7 ms engine time / ≈70 ms end-to-end incl. process startup, from sparq's published benchmarks (idle-machine wall-clock dt1k 0.068 s; engine-internal min-of-5 ≈0.005–0.007 s).
  • eye-js (WASM build of EYE): ≈390 ms end-to-end, measured on-box (eyereasoner v21.1.10, node 22, 2-core CI box, gated) on the canonical linear DeepTaxonomy-1k shape from perf/bench.ts — of which ≈270 ms is one-time WASM module instantiation and ≈120 ms is reasoning.

⚠️ Caveat, stated explicitly in the notice: this is a native-vs-WASM comparison. sparq publishes no WASM DeepTaxonomy timing anywhere, so the honest framing is sparq-native vs eye-js-WASM, and the notice says so — the gap reflects both the engine and the native-vs-WASM runtime cost (WASM boot alone is ≈270 ms of eye-js's ≈390 ms). Framed as "roughly an order of magnitude on reasoning time and several-fold end-to-end," not "orders of magnitude." When sparq publishes a WASM DT number this should become a true wasm-vs-wasm line (tracked in #1965).

Every other figure is verified

Claim Source
Rust-native RDF triplestore, SPARQL 1.1/1.2 sparq README lead
N3 reasoning (RDFS / OWL 2 RL / Notation3), native + WASM sparq README features; skills/inference/SKILL.md; crates/sparq-reason-wasm, deployed at sparq.jeswr.org/wasm/reason/
sparq reasoning bundle ≈2.6 MB wasm / ≈0.9 MB gzip re-measured from the deployed artifact 2026-07-04: sparq_reason_wasm_bg.wasm = 2,572,368 B raw, 909,549 B gzip -9
eye-js ≈3.8 MB wasm + data / ≈4.1 MB browser bundle measured from this repo @ fa76971: swipl-web.wasm 2,190,887 B + swipl-web.data 1,642,703 B = 3,833,590 B; webpack bundle/index.js 4,051,911 B
DeepTaxonomy-1k: sparq ≈7 ms/≈70 ms vs eye-js ≈390 ms sparq: bench/inference/eye-comparison.md; eye-js: on-box measurement (eyereasoner v21.1.10, canonical perf/bench.ts linear DT-1000 shape)
experimental / pre-1.0 / evolving quickly sparq README status banner
migration npm package "tracked in sparq-org/sparq#1499" sparq-org/sparq#1499 — does not exist on npm yet, hence tracked, not available

Deliberately not claimed: any identical-closure guarantee between eye-js and sparq (verified only sparq-vs-native-EYE in the linked file; eye-js's bench uses a goal-directed --query, so its derivation may differ), and any published sparq npm package.

Trackers

Adjacency note

⚠️ #1954 (browser dist e2e test + RDF 1.2 support level) also edits README.md. This change is at the very top (under the H1); #1954's edit is in the RDF-1.2 section — different region, so a conflict is unlikely, but rebase after #1954 lands if the merge queue complains.

🤖 Generated with Claude Code

Adds a banner at the top of the README pointing eye-js users at
https://github.com/sparq-org/sparq (Rust-native triplestore with N3
reasoning), with verified bundle-size and benchmark figures, and links
the eye-js-compatible migration package request (sparq-org/sparq#1499).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…rq notice

Replace the "orders of magnitude faster than the native EYE reasoner"
phrasing (a sparq-vs-native-EYE figure) with a direct, honest eye-js-vs-sparq
DeepTaxonomy-1k comparison using measured numbers: sparq (native Rust) ~7 ms
engine / ~70 ms end-to-end vs eye-js (WASM build of EYE) ~390 ms end-to-end
(~270 ms WASM boot + ~120 ms reasoning). Flag it explicitly as native-vs-WASM
since sparq publishes no WASM DeepTaxonomy timing. Keep the (verified) bundle-size
comparison and reflect sparq's current experimental/pre-1.0 state.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'EYE JS Benchmark'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.25.

Benchmark suite Current: a82637b Previous: d129aee Ratio
Run socrates query 15.33 ops/sec (±6.69%) 22.2 ops/sec (±2.39%) 1.45
Executing the socrates query 115 ops/sec (±20.74%) 3890 ops/sec (±1.67%) 33.83
Run deep taxonomy benchmark [10] 6.51 ops/sec (±2.61%) 18.83 ops/sec (±6.56%) 2.89
Run deep taxonomy benchmark [50] 0.24 ops/sec (±1.60%) 19.63 ops/sec (±7.26%) 81.79
Run deep taxonomy benchmark [100] 0.04 ops/sec (±1.32%) 18.67 ops/sec (±6.95%) 466.75
Run deep taxonomy benchmark [10] [reasoning only] 7.07 ops/sec (±16.51%) 4107 ops/sec (±1.65%) 580.91
Run deep taxonomy benchmark [50] [reasoning only] 0.56 ops/sec (±21.44%) 4147 ops/sec (±1.85%) 7405.36
Run deep taxonomy benchmark [100] [reasoning only] 0.15 ops/sec (±23.05%) 4136 ops/sec (±1.60%) 27573.33
Run timbl + foaf + rdfs rules 1.95 ops/sec (±2.47%) 17.23 ops/sec (±6.18%) 8.84
Run timbl + foaf + owl2rl rules 1.12 ops/sec (±1.60%) 17.03 ops/sec (±3.91%) 15.21
Run timbl + rdfs rules 4.43 ops/sec (±2.59%) 18.28 ops/sec (±6.60%) 4.13
Run timbl + owl2rl rules 5.66 ops/sec (±0.72%) 17.1 ops/sec (±6.85%) 3.02
Run timbl + foaf + rdfs rules [string] 2 ops/sec (±0.46%) 18.45 ops/sec (±7.08%) 9.22
Run timbl + foaf + owl2rl rules [string] 1.15 ops/sec (±0.46%) 18.54 ops/sec (±6.64%) 16.12
Run timbl + rdfs rules [string] 4.52 ops/sec (±0.30%) 18.77 ops/sec (±6.77%) 4.15
Run timbl + owl2rl rules [string] 5.82 ops/sec (±0.29%) 18.98 ops/sec (±6.47%) 3.26

This comment was automatically generated by workflow using github-action-benchmark.

CC: @jeswr

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant