Metadata-Version: 2.4
Name: rdflib-reasoning-engine
Version: 0.3.0
Summary: RETE-based RDFS and OWL 2 RL entailment for RDFLib
License: MIT License
        
        Copyright (c) 2026 rdflib-reasoning contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Requires-Python: >=3.14
Requires-Dist: pydantic
Requires-Dist: rdflib
Requires-Dist: rdflib-reasoning-axioms
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Provides-Extra: notebook
Requires-Dist: ipython; extra == 'notebook'
Description-Content-Type: text/markdown

# RDFLib Reasoning Engine

Agentic AI should be able to take advantage of basic reasoning in an efficient manner.

[RDFS](https://www.w3.org/TR/rdf11-mt/#entailment-rules-informative) and [OWL 2 RL reasoning](https://www.w3.org/TR/owl2-profiles/#Reasoning_in_OWL_2_RL_and_RDF_Graphs_using_Rules) define the semantics for two entailment regimes.
These regimes can be computed using forward-chaining rules, though practical approaches may also benefit from [special handling for transitive closures](https://jena.apache.org/documentation/inference/index.html#transitive).
The `rdflib-reasoning-engine` package provides an efficient general purpose forward chaining rule engine (i.e., RETE) that works with RDFLib.

## Tutorials and demos

If you want to see the current RDFS inference surface in action, start with:

- [../notebooks/demo-rdfs-inference.ipynb](../notebooks/demo-rdfs-inference.ipynb): compact end-to-end tutorial for RDFLib-backed RDFS materialization plus a proof view of the rule applications behind one inferred triple
- [../notebooks/demo-proof-reconstructor.ipynb](../notebooks/demo-proof-reconstructor.ipynb): proof-focused companion notebook covering proof reconstruction, Mermaid rendering, markdown rendering, and raw proof inspection

## Feature Matrix

Status values:

- `Implemented`: available in the package today
- `In progress`: scaffolding or partial implementation exists, but the feature is not yet wired end-to-end
- `Not started`: identified feature target with no concrete implementation yet

### RDFS entailment rules

This matrix tracks the intermediate RDFS rule target using the cached RDF 1.1 Semantics specification at [`docs/specs/rdf11-semantics/optimized.html`](../docs/specs/rdf11-semantics/optimized.html). The informative RDFS entailment rules are identified there as `rdfs1` through `rdfs13`.

| Feature | Spec reference | Status |
| --- | --- | --- |
| Property typing | `rdfs1` | Implemented |
| Domain inference | `rdfs2` | Implemented |
| Range inference | `rdfs3` | Implemented |
| Resource typing axioms | `rdfs4a`, `rdfs4b` | Implemented |
| Subproperty transitivity | `rdfs5` | Implemented |
| Every property is a subproperty of itself | `rdfs6` | Implemented |
| Subproperty inheritance | `rdfs7` | Implemented |
| Class typing for `rdfs:Class` | `rdfs8` | Implemented |
| Subclass typing propagation | `rdfs9` | Implemented |
| Every class is a subclass of itself | `rdfs10` | Implemented |
| Subclass transitivity | `rdfs11` | Implemented |
| Container membership property inheritance | `rdfs12` | Implemented |
| Datatype subclass typing | `rdfs13` | Implemented |

### OWL 2 RL rules

The authoritative local reference for this matrix is [`docs/specs/owl2-reasoning-profiles/INDEX.md`](../docs/specs/owl2-reasoning-profiles/INDEX.md), which indexes Section 4.3 of the cached OWL 2 Profiles specification.

| Feature | Spec reference | Status |
| --- | --- | --- |
| Equality rules | `eq-ref`, `eq-sym`, `eq-trans`, `eq-rep-s`, `eq-rep-p`, `eq-rep-o`, `eq-diff1`, `eq-diff2`, `eq-diff3` | Not started |
| Property assertion and typing rules | `prp-ap`, `prp-dom`, `prp-rng` | Not started |
| Functional and inverse-functional property rules | `prp-fp`, `prp-ifp` | Not started |
| Irreflexive, symmetric, asymmetric, and transitive property rules | `prp-irp`, `prp-symp`, `prp-asyp`, `prp-trp` | Not started |
| Subproperty, equivalent property, and property disjointness rules | `prp-spo1`, `prp-spo2`, `prp-eqp1`, `prp-eqp2`, `prp-pdw`, `prp-adp` | Not started |
| Inverse property rules | `prp-inv1`, `prp-inv2` | Not started |
| Key and negative property assertion rules | `prp-key`, `prp-npa1`, `prp-npa2` | Not started |
| Core class rules | `cls-thing`, `cls-nothing1`, `cls-nothing2`, `cls-int1`, `cls-int2`, `cls-uni`, `cls-com`, `cls-oo` | Not started |
| Some/all values from and has-value rules | `cls-svf1`, `cls-svf2`, `cls-avf`, `cls-hv1`, `cls-hv2` | Not started |
| Max cardinality rules | `cls-maxc1`, `cls-maxc2`, `cls-maxqc1`, `cls-maxqc2`, `cls-maxqc3`, `cls-maxqc4` | Not started |
| Class axiom rules | `cax-sco`, `cax-eqc1`, `cax-eqc2`, `cax-dw`, `cax-adc` | Not started |
| Datatype rules | `dt-type1`, `dt-type2`, `dt-eq`, `dt-diff`, `dt-not-type` | Not started |
| Schema vocabulary rules | `scm-cls`, `scm-sco`, `scm-eqc1`, `scm-eqc2`, `scm-op`, `scm-dp`, `scm-spo`, `scm-eqp1`, `scm-eqp2`, `scm-dom1`, `scm-dom2`, `scm-rng1`, `scm-rng2`, `scm-hv`, `scm-svf1`, `scm-svf2`, `scm-avf1`, `scm-avf2`, `scm-int`, `scm-uni` | Not started |

### Engine capabilities

This matrix tracks functional engine features independent of standards coverage.

| Feature | Status | Notes |
| --- | --- | --- |
| Alpha memory / node support | Implemented | Shared alpha nodes perform literal filtering and retain persistent alpha memory across incremental updates |
| Beta memory / join node support | Implemented | Shared beta nodes perform left-deep joins and retain persistent partial-match memory across incremental updates |
| Triple pattern matching | Implemented | Public Rule IR, compiler normalization, and `NetworkMatcher` execute RDFLib-variable triple patterns end-to-end |
| Rule firing and agenda management | Implemented | `Agenda` orders activations by salience and breadth-first depth; richer conflict resolution policy remains future work |
| Inference materialization | Implemented | Compiled logical productions execute to fixed point in `RETEEngine`, and `RETEStore` materializes inferred triples into RDFLib contexts |
| RDF triple well-formedness enforcement | Implemented | The engine rejects or warns-and-skips triples with literal subjects or non-IRI predicates, preventing malformed triples from entering working memory or derived outputs |
| Builtin predicate / function support | Implemented | Predicate conditions compile and execute through the RETE matcher using injected read-only predicate hooks |
| Rule action callbacks | Implemented | Callback consequents execute through the agenda with read-only invocation context; richer signature validation and retraction-time policy remain future work |
| Derivation / trace logging | Implemented | Engine-native `DerivationRecord` values are emitted for new logical conclusions produced by fired rules |
| JTMS-compatible support bookkeeping | Implemented | `WorkingMemory`, `DependencyGraph`, and `Justification` records track stated facts and multi-parent support for derived facts; recursive retraction remains future work |
| Explanation reconstruction | Implemented | `DerivationProofReconstructor` rebuilds `DirectProof` trees from non-silent derivation records for triple-goal explanations |
| Proof rendering (markdown and Mermaid) | Implemented | Presentation-focused rendering over canonical `DirectProof` data includes namespace-aware shortening and notebook display adapters via optional extras |
| Contradiction / inconsistency handling | Not started | Detecting, surfacing, or managing incompatible conclusions |
| Specialized transitive relation index | Not started | Intended optimization path for `rdfs:subClassOf` and `rdfs:subPropertyOf` first; broader general transitive-property support remains a later design question |

## Current integration baseline

The supported RDFLib integration path is `Store` events -> `BatchDispatcher` ->
`RETEStore` -> `RETEEngine`.

The `rdflib-reasoning-engine` package is part of the `rdflib-reasoning` metapackage.
