eyeling 1.12.6 → 1.12.8

package/HANDBOOK.md

@@ -893,6 +893,12 @@ These are “function-like” relations where the subject is usually a list and
 - Computes the numeric sum.
 - Chooses an output datatype based on the “widest” numeric datatype seen among inputs and (optionally) the object position; integers stay integers unless the result is non-integer.
 
+Eyeling also supports a small, EYE-style convenience for timestamp arithmetic:
+
+- **DateTime plus duration/seconds**: `(dateTime durationOrSeconds) math:sum dateTime`
+  - `xsd:duration` is interpreted as seconds (same model as `math:difference`).
+  - Output is a normalized `xsd:dateTime` in UTC lexical form (`...Z`).
+
 #### `math:product`
 
 **Shape:** `( $x1 $x2 ... ) math:product $total`
@@ -911,9 +917,10 @@ Eyeling supports:
 
 1. **Numeric subtraction**: `c = a - b`.
 2. **DateTime difference**: `(dateTime1 dateTime2) math:difference duration`
-   - Produces an `xsd:duration` in whole days (internally computed via seconds then formatted).
+   - Produces an **`xsd:duration`** in a seconds-only lexical form such as `"PT900S"^^xsd:duration`.
+   - This avoids ambiguity around month/year day-length and still plays well with `math:lessThan`, `math:greaterThan`, etc. because Eyeling's numeric comparison builtins treat `xsd:duration` as seconds.
 
-3. **DateTime minus duration**: `(dateTime duration) math:difference dateTime`
+3. **DateTime minus duration**: `(dateTime durationOrSeconds) math:difference dateTime`
    - Subtracts a duration from a dateTime and yields a new dateTime.
 
 If the types don’t fit any supported case, the builtin fails.
@@ -1963,21 +1970,19 @@ In that sense, N3 is less a bid to make the web “smarter” than a bid to make
 
 <a id="app-c"></a>
 
-## Appendix C — N3 beyond Prolog: logic that survives the open web
-
-At first glance, an N3 rule set can feel familiar if you’ve used Prolog: variables, unification, and rules that read like “if this pattern holds, then that pattern follows.” But N3 is not just “logic programming with a different syntax.” It is logic shaped for a different environment: not a single program with a single database, but a world of distributed graphs that can be published, merged, and cited across boundaries.
+## Appendix C — N3 beyond Prolog: logic for RDF-style graphs
 
-That change of environment forces a change in what “beyond Prolog” even means. It is less about being more powerful in the abstract, and more about being _more portable as meaning_ — logic that stays connected when it moves between documents, vocabularies, and authors.
+Notation3 (N3) rule sets often look similar to Prolog at the surface: they use variables, unification, and implication-style rules (“if these patterns match, then these patterns follow”). N3 is typically used in a different setting: instead of a single program operating over a single local database, N3 rules and data are commonly written as documents that can be published, shared, merged, and referenced across systems.
 
-Several design moves push N3 into that web-native space:
+In practice, that setting is reflected in several common features of N3-style rule writing:
 
-- **Global identity is the default.** Names are IRIs. A rule does not merely compute with local symbols; it operates over identifiers meant to be shared across datasets.
-- **Graphs are the unit of exchange.** The input is a graph; the output is a graph. Inference produces new triples rather than hidden internal state, so results can travel the same way the facts do.
-- **Statements can be treated as data.** Quoted graphs let you talk _about_ assertions: claims, policies, provenance, “this source says …,” “this formula implies …,” and other meta-level structure that is awkward in a plain predicate database.
-- **Rules can be publishable artifacts.** Rules can live alongside data as text, be versioned, reviewed, and reused — the “meaning” is not forced back into an external codebase.
-- **Web-like computation can be pulled into rule bodies.** Built-ins make room for the small computations that real integration needs (strings, lists, comparisons), and some N3 workflows even treat IRIs as pointers to more knowledge.
+- **Identifiers are IRIs.** Terms are usually global identifiers rather than local symbols, which supports linking across datasets.
+- **Input and output are graphs.** Rules consume graph patterns and produce additional triples, so the result of inference can be represented in the same form as the input data.
+- **Quoted graphs allow statements-as-data.** N3 can treat a graph (a set of triples) as a term, which makes it possible to represent and reason about assertions (e.g., “this source says …” or “this formula implies …”) as data.
+- **Rules can be distributed as text artifacts.** Rules can live alongside data, be versioned, and be reused without requiring an external host language to “carry” the meaning.
+- **Built-ins cover common computations.** Many N3 workflows rely on built-ins for operations such as string handling, list processing, comparisons, and related utilities; some workflows also use IRIs as pointers to retrievable content.
 
-In that sense, Prolog is a superb engine for proving things _inside_ a chosen world. N3 is a way to write rules so they keep working _across_ worlds: across documents, across graph boundaries, and across the open-ended growth of linked data. When an engine like Eyeling solves rule bodies with a Prolog-like prover but still saturates forward consequences, it’s exactly this bridge: Prolog-style execution serving a web-scale, graph-first notion of meaning.
+Engines can combine execution styles in different ways. One common pattern is to use a Prolog-like backward-chaining prover to satisfy rule bodies, while still using forward chaining to add the instantiated conclusions to the fact set until no new facts are produced.
 
 ---
 

package/examples/bayes-therapy.n3

@@ -0,0 +1,264 @@
+# ============================================================================
+# Bayes Therapy Decision Support
+#
+# This example extends a tiny Bayesian diagnostic model (Disease -> Symptoms)
+# with a decision layer that scores therapies by expected utility.
+#
+# NOTE: All probabilities and weights are illustrative and not medical advice.
+# ============================================================================
+
+@prefix :     <https://example.org/diag#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
+@prefix list: <http://www.w3.org/2000/10/swap/list#> .
+
+# -------------------------------------------
+# 1) MODEL: Disease -> Symptoms (Naive Bayes)
+# -------------------------------------------
+
+:COVID19            a :Disease; :prior 0.05 .
+:Influenza          a :Disease; :prior 0.03 .
+:AllergicRhinitis   a :Disease; :prior 0.10 .
+:BacterialPneumonia a :Disease; :prior 0.01 .
+
+# Conditional probabilities P(symptom | disease)
+:COVID19 :pGiven [ :symptom :Fever;        :p 0.70 ] .
+:COVID19 :pGiven [ :symptom :DryCough;     :p 0.65 ] .
+:COVID19 :pGiven [ :symptom :LossOfSmell;  :p 0.40 ] .
+:COVID19 :pGiven [ :symptom :Sneezing;     :p 0.15 ] .
+:COVID19 :pGiven [ :symptom :ShortBreath;  :p 0.20 ] .
+
+:Influenza :pGiven [ :symptom :Fever;        :p 0.80 ] .
+:Influenza :pGiven [ :symptom :DryCough;     :p 0.50 ] .
+:Influenza :pGiven [ :symptom :LossOfSmell;  :p 0.05 ] .
+:Influenza :pGiven [ :symptom :Sneezing;     :p 0.20 ] .
+:Influenza :pGiven [ :symptom :ShortBreath;  :p 0.10 ] .
+
+:AllergicRhinitis :pGiven [ :symptom :Fever;        :p 0.05 ] .
+:AllergicRhinitis :pGiven [ :symptom :DryCough;     :p 0.15 ] .
+:AllergicRhinitis :pGiven [ :symptom :LossOfSmell;  :p 0.10 ] .
+:AllergicRhinitis :pGiven [ :symptom :Sneezing;     :p 0.80 ] .
+:AllergicRhinitis :pGiven [ :symptom :ShortBreath;  :p 0.05 ] .
+
+:BacterialPneumonia :pGiven [ :symptom :Fever;        :p 0.70 ] .
+:BacterialPneumonia :pGiven [ :symptom :DryCough;     :p 0.60 ] .
+:BacterialPneumonia :pGiven [ :symptom :LossOfSmell;  :p 0.02 ] .
+:BacterialPneumonia :pGiven [ :symptom :Sneezing;     :p 0.05 ] .
+:BacterialPneumonia :pGiven [ :symptom :ShortBreath;  :p 0.60 ] .
+
+# ----------------------------------------------------------------------
+# 2) THERAPY MODEL: P(improve | disease, therapy) + P(adverse | therapy)
+# ----------------------------------------------------------------------
+
+:Paxlovid a :Therapy;
+  # aligned with :Case :diseases order
+  :successByDisease ( 0.75 0.05 0.02 0.05 );
+  :adverse 0.10 .
+
+:Oseltamivir a :Therapy;
+  :successByDisease ( 0.05 0.60 0.02 0.05 );
+  :adverse 0.08 .
+
+:Antihistamine a :Therapy;
+  :successByDisease ( 0.10 0.10 0.75 0.05 );
+  :adverse 0.03 .
+
+:Antibiotic a :Therapy;
+  :successByDisease ( 0.05 0.05 0.02 0.80 );
+  :adverse 0.07 .
+
+:SupportiveCare a :Therapy;
+  :successByDisease ( 0.30 0.30 0.25 0.20 );
+  :adverse 0.01 .
+
+:Model :benefitWeight 10; :harmWeight 3 .
+
+# -------------------------------------------
+# 3) CASE: evidence (symptoms present/absent)
+# -------------------------------------------
+
+:Case a :PatientCase;
+  :diseases ( :COVID19 :Influenza :AllergicRhinitis :BacterialPneumonia );
+  :therapies ( :Paxlovid :Oseltamivir :SupportiveCare :Antibiotic :Antihistamine );
+  :evidence (
+    [ :symptom :Fever;       :present true  ]
+    [ :symptom :DryCough;    :present true  ]
+    [ :symptom :LossOfSmell; :present false ]
+    [ :symptom :Sneezing;    :present false ]
+    [ :symptom :ShortBreath; :present false ]
+  ).
+
+# -----------------------------------------------------------
+# 4) GUARDS (inference fuses): probabilities must be in [0,1]
+# -----------------------------------------------------------
+
+{ ?d :prior ?p. ?p math:lessThan 0. }     => false.
+{ ?d :prior ?p. ?p math:greaterThan 1. }  => false.
+
+{ ?d :pGiven [ :p ?p ]. ?p math:lessThan 0. }     => false.
+{ ?d :pGiven [ :p ?p ]. ?p math:greaterThan 1. }  => false.
+
+{ ?t a :Therapy. ?t :adverse ?p. ?p math:lessThan 0. }     => false.
+{ ?t a :Therapy. ?t :adverse ?p. ?p math:greaterThan 1. }  => false.
+
+{ ?t a :Therapy. ?t :successByDisease ?ps.
+  ?ps list:iterate ( ?i ?p ).
+  ?p math:lessThan 0.
+} => false.
+
+{ ?t a :Therapy. ?t :successByDisease ?ps.
+  ?ps list:iterate ( ?i ?p ).
+  ?p math:greaterThan 1.
+} => false.
+
+# ------------------------------------------
+# 5) HELPERS (all written as backward rules)
+# ------------------------------------------
+
+# pairList(d, (x1 x2 ...)) -> ((d x1) (d x2) ...)
+{ ( ?d () ) :pairList () } <= true.
+
+{ ( ?d ?xs ) :pairList ?pairs } <= {
+  ?xs list:firstRest ( ?x ?rest ).
+  ( ?d ?rest ) :pairList ?tailPairs.
+  ?pairs list:firstRest ( ( ?d ?x ) ?tailPairs ).
+}.
+
+# factor(d, evidenceItem) -> probability factor for that symptom
+{ ( ?d ?ev ) :factor ?p } <= {
+  ?ev :symptom ?s.
+  ?ev :present true.
+  ?d :pGiven [ :symptom ?s; :p ?p ].
+}.
+
+{ ( ?d ?ev ) :factor ?q } <= {
+  ?ev :symptom ?s.
+  ?ev :present false.
+  ?d :pGiven [ :symptom ?s; :p ?p ].
+  ( 1 ?p ) math:difference ?q.
+}.
+
+# pairWithConst((x1 x2 ...), c) -> ((x1 c) (x2 c) ...)
+{ ( () ?c ) :pairWithConst () } <= true.
+
+{ ( ?xs ?c ) :pairWithConst ?pairs } <= {
+  ?xs list:firstRest ( ?x ?rest ).
+  ( ?rest ?c ) :pairWithConst ?tailPairs.
+  ?pairs list:firstRest ( ( ?x ?c ) ?tailPairs ).
+}.
+
+# zip((a1 a2 ...), (b1 b2 ...)) -> ((a1 b1) (a2 b2) ...)
+{ ( () () ) :zip () } <= true.
+
+{ ( ?as ?bs ) :zip ?pairs } <= {
+  ?as list:firstRest ( ?a ?arest ).
+  ?bs list:firstRest ( ?b ?brest ).
+  ( ?arest ?brest ) :zip ?tailPairs.
+  ?pairs list:firstRest ( ( ?a ?b ) ?tailPairs ).
+}.
+
+# Helpers for list:map
+{ ?pair :mul ?p }  <= { ?pair math:product ?p }.
+{ ?pair :quot2 ?q } <= { ?pair math:quotient ?q }.
+
+# ---------------------------------------------------------
+# 6) DIAGNOSIS: unnormalized scores + normalized posteriors
+# ---------------------------------------------------------
+
+# score(d) = prior(d) * Π_e factor(d,e)
+{ ?d :scoreFor ?score } <= {
+  ?d :prior ?prior.
+  :Case :evidence ?evs.
+  ( ?d ?evs ) :pairList ?pairs.
+  ( ?pairs :factor ) list:map ?factors.
+  ?factors math:product ?likelihood.
+  ( ?prior ?likelihood ) math:product ?score.
+}.
+
+# Compute the score list, total evidence, and posterior list once.
+{
+  :Case :diseases ?ds.
+  ( ?ds :scoreFor ) list:map ?scores.
+  ?scores math:sum ?total.
+
+  ( ?scores ?total ) :pairWithConst ?scorePairs.
+  ( ?scorePairs :quot2 ) list:map ?posteriors.
+} => {
+  :Case :scores ?scores;
+        :evidenceTotal ?total;
+        :posteriors ?posteriors.
+}.
+
+# Attach each disease posterior to the disease term (no blank nodes in output)
+{
+  :Case :diseases ?ds.
+  :Case :posteriors ?posts.
+
+  ?ds list:iterate ( ?i ?d ).
+  ( ?posts ?i ) list:memberAt ?p.
+} => {
+  ?d :posterior ?p.
+}.
+
+# -------------------------------------------------------
+# 7) THERAPY SCORING: expected success + expected utility
+# -------------------------------------------------------
+
+# expectedSuccess(t) = Σ_i post[i] * successByDisease[i]
+{
+  :Case :posteriors ?posts.
+  ?t a :Therapy.
+  ?t :successByDisease ?succ.
+
+  ( ?posts ?succ ) :zip ?pairs.
+  ( ?pairs :mul ) list:map ?terms.
+  ?terms math:sum ?expectedSuccess.
+
+  ?t :adverse ?adverse.
+  :Model :benefitWeight ?bw.
+  :Model :harmWeight ?hw.
+
+  ( ?bw ?expectedSuccess ) math:product ?benefit.
+  ( ?hw ?adverse ) math:product ?harmCost.
+  ( ?benefit ?harmCost ) math:difference ?utility.
+} => {
+  ?t :expectedSuccess ?expectedSuccess;
+     :expectedAdverse ?adverse;
+     :utility ?utility.
+}.
+
+# --------------------------------------------------------------
+# 8) RECOMMENDATION: pick max-utility therapy from the case list
+# --------------------------------------------------------------
+
+# betterOf(t1,t2) chooses t1 if utility(t1) >= utility(t2), else t2.
+{ ( ?t1 ?t2 ) :betterOf ?t1 } <= {
+  ?t1 :utility ?u1.
+  ?t2 :utility ?u2.
+  ?u1 math:notLessThan ?u2.
+}.
+{ ( ?t1 ?t2 ) :betterOf ?t2 } <= {
+  ?t1 :utility ?u1.
+  ?t2 :utility ?u2.
+  ?u1 math:lessThan ?u2.
+}.
+
+# bestTherapy((t)) = t
+{ ( ?ts ) :bestTherapy ?t } <= {
+  ?ts list:firstRest ( ?t () ).
+}.
+
+# bestTherapy((head rest...)) = betterOf(head, bestTherapy(rest))
+{ ( ?ts ) :bestTherapy ?best } <= {
+  ?ts list:firstRest ( ?head ?rest ).
+  ?rest list:firstRest ( ?_ ?__ ).  # ensure rest is non-empty
+  ( ?rest ) :bestTherapy ?bestRest.
+  ( ?head ?bestRest ) :betterOf ?best.
+}.
+
+# Emit a single recommendation for this case.
+{
+  :Case :therapies ?ts.
+  ( ?ts ) :bestTherapy ?best.
+} => {
+  :Case :recommendedTherapy ?best.
+}.

package/examples/collatz.n3

@@ -0,0 +1,117 @@
+# ==================
+# Collatz conjecture
+# ==================
+#
+# Collatz iteration:
+#   - if n is even: n ↦ n/2
+#   - if n is odd : n ↦ 3n + 1
+#
+# The conjecture states that starting from any positive integer n,
+# repeated application of the rule eventually reaches 1.
+#
+# This N3 program:
+#   1) enumerates test inputs N = 1000, 999, ..., 1 via a backward :repeat relation
+#   2) computes the full Collatz trajectory for each N as an RDF list
+#   3) materializes only the final results as  :collatzTrajectory  triples
+#
+# See https://en.wikipedia.org/wiki/Collatz_conjecture
+
+@prefix :     <http://example.org/collatz#> .
+@prefix math: <http://www.w3.org/2000/10/swap/math#> .
+@prefix list: <http://www.w3.org/2000/10/swap/list#> .
+
+# -----------------------------------------
+# Query / materialization of the test suite
+# -----------------------------------------
+#
+# Generate N in {1000..1} and ask the backward-defined :collatz predicate
+# for the full trajectory list ?M.
+#
+# Note: we derive N as (1000 - N0) so that N0 ranges over 0..999.
+# This keeps :repeat as a generic “0..N-1” generator.
+#
+# Output predicate is renamed to :collatzTrajectory to keep results separate
+# from the intensional (backward) definition of :collatz.
+{
+  1000 :repeat ?N0 .
+  (1000 ?N0) math:difference ?N .
+  ?N :collatz ?M .
+}
+=>
+{
+  ?N :collatzTrajectory ?M .
+} .
+
+# ------------------------
+# Backward range generator
+# ------------------------
+#
+# ?N :repeat ?I  enumerates all integers I in the half-open interval:
+#   I ∈ [0 .. N-1]
+
+# Base case: repeat(1) = {0}
+{ ?N :repeat 0 }
+<=
+{ ?N math:equalTo 1. } .
+
+# For N>1, also include the last value (N-1)
+{ ?N :repeat ?I }
+<=
+{
+  ?N math:greaterThan 1.
+  (?N 1) math:difference ?I.     # I = N - 1
+} .
+
+# And for N>1, inherit everything from repeat(N-1)
+# (this is the recursive “rest of the range”)
+{ ?N :repeat ?I }
+<=
+{
+  ?N math:greaterThan 1.
+  (?N 1) math:difference ?N1.    # N1 = N - 1
+  ?N1 :repeat ?I.
+} .
+
+# -------------------------
+# Backward Collatz relation
+# -------------------------
+#
+# ?N0 :collatz ?M  relates a start value ?N0 to its full Collatz trajectory ?M.
+# The trajectory is represented as an RDF list:
+#   - for N0=1: (1)
+#   - for N0>1: (N0 ... 1)
+#
+# The recursion is guarded with “N0 > 1” so the base case terminates cleanly.
+
+# Base case: 1 terminates immediately
+{ ?N0 :collatz (1) }
+<=
+{ ?N0 math:equalTo 1. } .
+
+# Even step: N0 > 1 and N0 mod 2 = 0  =>  N1 = N0/2
+# The resulting list is constructed as: (N0) :: collatz(N1)
+{ ?N0 :collatz ?M }
+<=
+{
+  ?N0 math:greaterThan 1.
+  (?N0 2) math:remainder 0.
+  (?N0 2) math:integerQuotient ?N1.   # N1 = floor(N0/2) (safe because even)
+
+  ?N1 :collatz ?J.
+  ?M list:firstRest (?N0 ?J).         # M = [N0 | J]
+} .
+
+# Odd step: N0 > 1 and N0 mod 2 = 1  =>  N1 = 3*N0 + 1
+# Again: (N0) :: collatz(N1)
+{ ?N0 :collatz ?M }
+<=
+{
+  ?N0 math:greaterThan 1.
+  (?N0 2) math:remainder 1.
+  (3 ?N0) math:product ?T.
+  (?T 1) math:sum ?N1.                # N1 = 3*N0 + 1
+
+  ?N1 :collatz ?J.
+  ?M list:firstRest (?N0 ?J).         # M = [N0 | J]
+} .
+