Metadata-Version: 2.4
Name: rdflib-reasoning-engine
Version: 0.1.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; extra == 'dev'
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.

## 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 | In progress | Shared alpha nodes now perform literal filtering and retain persistent alpha memory across incremental updates |
| Beta memory / join node support | In progress | Shared beta nodes now perform left-deep joins and retain persistent partial-match memory across incremental updates |
| Triple pattern matching | In progress | Public Rule IR, compiler normalization, and `NetworkMatcher` now execute RDFLib-variable triple patterns end-to-end |
| Rule firing and agenda management | In progress | `Agenda` now orders activations by salience and breadth-first depth; richer conflict resolution policy remains future work |
| Inference materialization | In progress | Compiled logical productions now 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 | In progress | Predicate conditions compile and execute through the RETE matcher using injected read-only predicate hooks |
| Rule action callbacks | In progress | Callback consequents now execute through the agenda with read-only invocation context; richer signature validation and retraction-time policy remain future work |
| Derivation / trace logging | In progress | Engine-native `DerivationRecord` values are now emitted for new logical conclusions produced by fired rules |
| JTMS-compatible support bookkeeping | In progress | `WorkingMemory`, `DependencyGraph`, and `Justification` records now track stated facts and multi-parent support for derived facts; recursive retraction remains future work |
| Explanation reconstruction | In progress | Proof models and reconstruction protocol exist, but derivation records are not yet rebuilt into concrete `DirectProof` paths |
| 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.
