unicode-logic-kit 0.31.0__py3-none-any.whl

unicode_logic_kit/dl/__init__.py

@@ -0,0 +1,384 @@
+"""The ``dl`` subpackage — the description logic **ALC**.
+
+Concept constructors (``import unicode_logic_kit.dl as dl``)::
+
+    dl.Top(), dl.Bottom(), dl.Atomic("Person"), dl.Not(C),
+    dl.And(C, D), dl.Or(C, D), dl.Exists("hasChild", C), dl.ForAll("hasChild", C),
+    dl.AtLeast(2, "hasChild", C), dl.AtMost(1, "hasChild", C)   # qualified number
+                                                                 # restrictions (ALCQ)
+
+Reasoning over a (general) TBox / ABox::
+
+    dl.concept_satisfiable(C, tbox)   # is C satisfiable w.r.t. the TBox?
+    dl.subsumes(C, D, tbox)           # does the TBox entail C ⊑ D?
+    dl.equivalent(C, D, tbox)         # C ≡ D?
+    dl.abox_consistent(abox, tbox)    # is the knowledge base consistent?
+
+Instance/realization queries over an ABox, all pure reductions to ``abox_consistent``
+(see :mod:`unicode_logic_kit.dl.tableau`)::
+
+    dl.instance_check(abox, "alice", C, tbox)       # does the KB entail alice : C?
+    dl.instance_retrieval(abox, C, tbox)             # every individual entailed to be C
+    dl.realize(abox, "alice", vocabulary, tbox)      # alice's most-specific concepts
+    dl.realize_all(abox, vocabulary, tbox)           # realize() for every individual
+
+TBox classification — the whole named-concept subsumption hierarchy as a pure
+reduction to ``subsumes`` (see :mod:`unicode_logic_kit.dl.classification`)::
+
+    dl.classify(tbox)                 # -> Classification(equivalents, parents,
+                                       #    children, ancestors)
+
+ALC is exactly multi-modal K; the reasoner is a tableau with TBox internalisation
+and subset blocking (see :mod:`unicode_logic_kit.dl.tableau`).
+
+Parsing the glyph concept syntax back into a :class:`Concept`
+(:mod:`unicode_logic_kit.dl.parser`)::
+
+    dl.parse_concept("∃hasChild.(Doctor ⊓ ¬Rich)")   # -> Concept
+    dl.parse_gci("Doctor ⊑ ∃hasChild.⊤")              # -> (Concept, Concept)
+
+Parsing/rendering the W3C OWL 2 Manchester Syntax (ALC fragment only,
+:mod:`unicode_logic_kit.dl.owl_manchester`)::
+
+    dl.parse_manchester("hasChild some (Doctor and not Rich)")   # -> Concept
+    dl.to_manchester(C)                                          # -> str
+    dl.parse_manchester_axiom("Doctor SubClassOf hasChild some owl:Thing")
+    #  -> ("subclass", Concept, Concept)
+    dl.parse_manchester_role_axiom("hasChild SubPropertyOf hasDescendant")
+    #  -> ("subproperty", "hasChild", "hasDescendant")
+    dl.parse_manchester_role_axiom("hasDescendant Characteristics: Transitive")
+    #  -> ("transitive", "hasDescendant")
+    dl.parse_manchester_role_axiom("partOf InverseOf hasPart")
+    #  -> ("inverse", "partOf", "hasPart")
+    dl.parse_manchester_role_axiom("hasSink DisjointWith hasSource")
+    #  -> ("disjoint", "hasSink", "hasSource")
+
+Parsing/rendering the W3C OWL 2 Functional-Style Syntax (ALCHQ fragment, a whole
+ontology document rather than a single axiom, :mod:`unicode_logic_kit.dl.owl_functional`)::
+
+    dl.parse_owl_functional("Ontology(SubClassOf(Doctor Person))")   # -> (TBox, ABox)
+    dl.to_owl_functional(tbox, abox)                                 # -> str
+    dl.parse_owl_functional_class_expression("ObjectSomeValuesFrom(hasChild Doctor)")
+    #  -> Exists("hasChild", Atomic("Doctor"))
+    dl.to_owl_functional_class_expression(C)                        # -> str
+
+The standard translation to FOL, so ALC reuses the kit's FOL provers/exports
+(:mod:`unicode_logic_kit.dl.translate`)::
+
+    dl.concept_to_fol(C)                # -> FOL formula π(C, x), one free var x
+    dl.subsumption_to_fol(C, D)         # -> ∀x (π(C, x) → π(D, x))
+    dl.tbox_to_fol(tbox)                # -> conjunction of subsumption_to_fol per GCI
+    dl.rbox_to_fol(tbox)                # -> conjunction of role-inclusion/transitivity closures
+    dl.abox_to_fol(abox)                # -> conjunction of the ABox's assertions
+    dl.kb_to_fol(tbox, abox)            # -> KnowledgeBaseFOL: the KB + the role box as SEPARATE axioms
+    dl.check_kb_names(tbox, abox)       # -> None: kb_to_fol's check on names, over boxes rendered apart
+    dl.concept_to_modal(C)              # -> propositional modal-K formula (single role only)
+
+A :class:`TBox` holds the concept inclusions AND the role box, but ``tbox_to_fol``
+renders the concept inclusions only — so it RAISES ``dl.RoleBoxOmittedError`` for a TBox
+that has role inclusions or transitive roles (``concept_inclusions_only=True`` is the
+explicit opt-out). Ask any question *relative to* a knowledge base through
+``kb_to_fol``, passing the role box as premises, never folded into the formula::
+
+    kb = dl.kb_to_fol(tbox, abox)
+    api.prove(kb.subsumption_goal(C, D), kb.tbox_premises)         # = dl.subsumes(C, D, tbox)
+    api.prove(kb.unsatisfiability_goal(C), kb.tbox_premises)       # proved <=> C is unsatisfiable
+    api.prove(kb.instance_goal("a", C), kb.premises)               # = dl.instance_check(...)
+    api.prove(fol.Not(kb.formula), kb.axioms)       # proved <=> the knowledge base is inconsistent
+
+Role hierarchies and transitive roles (RBox), on top of the concept-level TBox
+(:mod:`unicode_logic_kit.dl.tableau`)::
+
+    t = dl.TBox().add_role_inclusion("hasChild", "hasDescendant").add_transitive_role("hasDescendant")
+    dl.subsumes(dl.Exists("hasChild", dl.Exists("hasChild", C)), dl.Exists("hasDescendant", C), t)
+    #  -> True: ∃hasChild.∃hasChild.C ⊑ ∃hasDescendant.C, entailed by the RBox alone
+
+Qualified number restrictions (ALCQ), on SIMPLE roles only (a role that is
+transitive, or has a transitive sub-role, raises ``NonSimpleRoleError`` by name —
+see :mod:`unicode_logic_kit.dl.tableau`'s "Qualified number restrictions" section)::
+
+    dl.concept_satisfiable(dl.And(dl.AtLeast(2, "r", C), dl.AtMost(1, "r", dl.Top())))
+    #  -> False: at least 2 pairwise-distinct r-successors but at most 1 r-successor at all
+
+``ABox.assert_distinct(a, b)`` records ``a ≠ b`` — this reasoner has no unique name
+assumption (see the same tableau section), so two ABox individuals otherwise remain
+mergeable, which matters as soon as a number restriction is in play.
+
+``instance_check``/``classify``/the rest of the reasoning API above respect a TBox's
+RBox automatically, since they all reduce to ``concept_satisfiable``/``abox_consistent``
+— no separate RBox-aware entry point is needed anywhere else.
+
+The rest of the OWL 2 object property box
+------------------------------------------
+A :class:`TBox` carries every OWL 2 object-property axiom kind, and
+``dl.rbox_to_fol`` renders every one of them (so ``kb_to_fol`` + ``api.prove``
+and ``dl.external_*`` answer them all). What the IN-HOUSE tableau does with
+each is the second column of ``dl.tableau._AXIOM_KINDS``::
+
+    t = (dl.TBox()
+         .add_disjoint_roles("hasSink", "hasSource")   # decided: a clash rule
+         .add_asymmetric_role("hasPhysicalInput")      # decided: a clash rule
+         .add_irreflexive_role("hasPhysicalInput")     # decided: a clash rule
+         .add_functional_role("hasState"))             # decided: ⊤ ⊑ ≤1 P.⊤
+    dl.abox_consistent(dl.ABox().assert_role("a", "a", "hasPhysicalInput"), t)
+    #  -> False: Irr(hasPhysicalInput) is ∀x ¬hasPhysicalInput(x, x)
+
+    dl.concept_satisfiable(dl.Top(), dl.TBox().add_symmetric_role("r"))
+    #  -> raises dl.UnsupportedAxiomError, naming SymmetricObjectProperty and
+    #     saying why (a symmetric role IS the inverse-role inclusion r ⊑ r⁻,
+    #     and a back-edge breaks subset blocking) and what to use instead
+
+Refused by name, each with its own remedy in the message:
+``InverseObjectProperties`` (:meth:`~unicode_logic_kit.dl.TBox.add_inverse_roles`),
+``SymmetricObjectProperty``, ``ReflexiveObjectProperty``,
+``InverseFunctionalObjectProperty`` and a property chain
+(:meth:`~unicode_logic_kit.dl.TBox.add_role_chain`) — plus an
+:class:`~unicode_logic_kit.dl.concepts.InverseRole` on either side of a role
+inclusion, which is accepted and rendered correctly but not decided in house.
+``EquivalentObjectProperties``
+(:meth:`~unicode_logic_kit.dl.TBox.add_equivalent_roles`) needs no rule at all:
+it is stored as the role inclusions it abbreviates.
+
+OWL 2 (Structural Specification §11) restricts asymmetry, irreflexivity, role
+disjointness, functionality and inverse-functionality — and every qualified
+number restriction — to SIMPLE roles, and the kit enforces exactly that
+condition, by name (:class:`NonSimpleRoleError`), on the in-house AND the
+external route. A role-box builder handed something that is not a usable role
+in that position raises :class:`RoleExpressionError` on the call that is wrong::
+
+    dl.TBox().add_role_inclusion(("r", "s"), "t")
+    #  -> raises dl.RoleExpressionError: a sequence of roles is a PROPERTY
+    #     CHAIN -- use dl.TBox.add_role_chain(chain, super_role)
+    dl.TBox().add_role_inclusion("P", "owl:topObjectProperty")
+    #  -> raises dl.RoleExpressionError: an OWL 2 BUILT-IN property name, not
+    #     an ordinary role. ``dl.parse_owl_functional`` consumes the
+    #     TAUTOLOGICAL inclusion into it as a documented no-op; every other use
+    #     of a built-in name is refused by name there too.
+
+Class expressions and the ABox: value restrictions, domain/range, identity
+---------------------------------------------------------------------------
+``dl.HasValue(role, individual)`` is OWL's ``ObjectHasValue(r a)``, written
+``exists r.{a}``: a NOMINAL in disguise, so the in-house tableau REFUSES it, as
+it refuses a bare ``Nominal`` (see :class:`~unicode_logic_kit.dl.concepts.HasValue`
+for why it is a constructor of its own and not ``dl.Exists(role,
+dl.Nominal(a))``, and "Value restrictions (ObjectHasValue)" in
+:mod:`unicode_logic_kit.dl.tableau` for why no in-house rule for it is sound: a
+value restriction gives a generated node an edge back to a named one, which the
+subset blocking the tableau terminates by does not cover). Its FOL image is the
+GROUND ATOM, the one-point reduction of ``exists y (r(x, y) and y = a)``, and
+that image, with ``api.prove`` — or ``dl.external_*`` (HermiT) — is what decides
+it::
+
+    dl.concept_to_fol(dl.HasValue("HasStateOfMatter", "Liquid"))
+    #  -> HasStateOfMatter(x, Liquid)
+    dl.concept_satisfiable(dl.And(dl.HasValue("r", "a"), dl.ForAll("r", dl.Bottom())))
+    #  -> raises dl.UnsupportedConceptError, naming the value restriction and
+    #     the routes that do decide it. The FOL image proves the hand-derived
+    #     verdict (unsatisfiable: a would have to be in bottom).
+
+``TBox.add_role_domain`` / ``add_role_range`` store
+``ObjectPropertyDomain``/``ObjectPropertyRange`` NATIVELY rather than as the
+GCIs they are equivalent to, so the image is the direct two-variable sentence
+and ``to_owl_functional`` round-trips the axiom to itself; the tableau decides
+them by internalising those GCIs, with no new rule::
+
+    dl.rbox_to_fol(dl.TBox().add_role_domain("Covers", dl.Atomic("Study")))
+    #  -> forall x forall y (Covers(x, y) -> Study(x))
+
+``ABox.assert_same`` (``SameIndividual``) is decided by node MERGING, closed
+under the equivalence the assertions generate, before any completion rule runs;
+``ABox.assert_negative_role`` (``NegativeObjectPropertyAssertion``, arguments in
+``assert_role``'s order) by a clash condition over FORBIDDEN edges. The second
+refuses a NON-SIMPLE role by name, since seeing a forbidden edge is what its
+verdict depends on and the tableau never materialises a transitive role's
+derived edges::
+
+    dl.abox_consistent(dl.ABox().assert_same("a", "b").assert_distinct("a", "b"))
+    #  -> False: a = b and a != b have no common model
+
+``dl.parse_owl_functional_axioms(text)`` is the per-axiom reader for a whole
+ontology: it returns an :class:`OwlFunctionalResult` with the TBox/ABox it could
+build plus one :class:`RefusedAxiom` per axiom outside the fragment, each naming
+the construct, its offset and its own source text. ``dl.parse_owl_functional``
+stays strict, raising on the first such construct. The lenient reader recovers
+from :class:`OwlFunctionalUnsupportedError` and nothing else: MALFORMED input
+still raises::
+
+    doc = dl.parse_owl_functional_axioms(text)
+    doc.ok, doc.accepted, doc.refused_keywords
+    kb = doc.to_kb()        # == dl.kb_to_fol(doc.tbox, doc.abox)
+
+One limit to know before printing an image that mentions an individual: the kit
+decides predicate-versus-term by the first character's case, so an UPPER-case
+individual name -- the norm for an OWL IRI -- prints as itself and does not read
+back as the same formula (``Alice = Bob`` does not parse;
+``HasStateOfMatter(x, Liquid)`` parses only as third-order, with ``Liquid`` a
+``PredicateTerm``). The AST is sound either way, and the routes that never go
+through text are unaffected. See ``tests/test_printed_text_reads_back.py``.
+
+Inverse roles and nominals (I, O) — outside ALCHQ, refused by the in-house tableau
+(a value restriction, ``dl.HasValue``, is a nominal and is refused with them)::
+
+    dl.concept_satisfiable(dl.Exists(dl.InverseRole("hasChild"), dl.Top()))
+    #  -> raises dl.UnsupportedConceptError: no in-house tableau rule decides I/O
+
+``dl.translate`` translates both constructs faithfully to FOL regardless (a role
+expression has a standard FOL image, argument order swapped; a nominal ``{a}``
+becomes the equality ``x = a`` — see :mod:`unicode_logic_kit.dl.translate`'s module
+docstring). To actually DECIDE a concept that needs either, use
+:mod:`unicode_logic_kit.dl.owl_reasoner`'s external, HermiT-backed reasoner (an
+optional dependency — install with ``pip install unicode-logic-kit[owl]``)::
+
+    dl.owl_reasoner_available()                       # owlready2 importable?
+    dl.external_concept_satisfiable(dl.And(dl.Nominal("a"), dl.Nominal("b")))
+    #  -> True: {a} ⊓ {b} is satisfiable absent an explicit DifferentIndividuals
+    #     assertion (OWL 2 has no unique name assumption)
+    dl.external_instance_check(
+        dl.ABox().assert_role("alice", "bob", "hasChild"), "bob",
+        dl.Exists(dl.InverseRole("hasChild"), dl.Top()))
+    #  -> True: bob has an incoming hasChild edge, i.e. an hasChild-inverse successor
+
+Which route decides what — the axiom-kind table
+------------------------------------------------
+Every axiom kind a :class:`TBox`/:class:`ABox` can hold has ONE row in
+``dl.tableau._AXIOM_KINDS``, and the row says what the in-house tableau does
+with it and what the FOL image does with it (see "The axiom-kind table" in
+:mod:`unicode_logic_kit.dl.tableau`'s module docstring). Two rules follow, and
+they are the kit's answer to "could these two routes disagree?":
+
+* **Builders never refuse.** ``TBox.add_*``/``ABox.assert_*`` accept every
+  kind, because a TBox is what a parser fills from a file.
+* **A kind the tableau has no rule for is refused BY NAME at query time**, by
+  :class:`UnsupportedAxiomError`, from ``concept_satisfiable``/
+  ``abox_consistent`` — and so from everything that reduces to them. Never
+  approximated, never silently ignored. ``dl.kb_to_fol`` + ``api.prove``, or
+  ``dl.external_*``, is where such a kind is answered instead.
+
+The FOL image keeps the two apart as well: ``kb_to_fol(tbox, abox).formula``
+is the knowledge base and ``.side_axioms`` the premises that are NOT part of
+it (each a :class:`SideAxiom` carrying the OWL ``kind`` it came from, so
+``kb.axioms_of_kind("TransitiveObjectProperty")`` is a question with an
+answer), while ``tbox_to_fol`` refuses outright to hand back a concept-
+inclusion image that silently drops them.
+
+The data layer: two sorts
+--------------------------
+OWL 2's second sort -- data values, datatypes, data properties -- is STORED
+(:class:`DataExists`, :class:`DataForAll`, :class:`DataHasValue`,
+:class:`DataAtLeast`, :class:`DataAtMost`; ``TBox.add_data_property_*`` and
+``add_datatype_definition``; ``ABox.assert_data``/``assert_negative_data``;
+:class:`Literal` and the data ranges :class:`Datatype`,
+:class:`DatatypeRestriction`, :class:`DataOneOf`, :class:`DataComplementOf`,
+:class:`DataIntersectionOf`, :class:`DataUnionOf`), READ and WRITTEN by the
+Manchester and Functional-Style syntaxes, and TRANSLATED by the FOL image --
+and REFUSED by the in-house tableau, by name, kind by kind (it has no data
+domain), and by ``dl.owl_reasoner``. What answers is ``dl.kb_to_fol`` +
+``api.prove``; facets are decided by ``atp.z3_arith``.
+
+The image is a guarded ONE-sorted theory over two reserved predicates,
+:data:`OWL_THING` and :data:`OWL_DATA`. The separation of the two domains, the
+typing of every data property and individual, the datatype lattice and literal
+distinctness are SIDE axioms (``group`` ``"sort"``/``"datatype"``), so the
+two-sorted question is the one the prover answers only if they are PREMISES:
+pass ``kb.premises`` / ``kb.tbox_premises``, not ``kb.formula`` alone, and let the
+bundle build the GOAL, ``kb.subsumption_goal(C, D)``, ``kb.unsatisfiability_goal(C)``
+or ``kb.instance_goal(a, C)``, which relativise it the way ``kb.separation``
+says (a hand-built goal needs ``subsumption_to_fol(..., object_sort=True)``).
+Every GCI of such an image is restricted to ``OwlThing`` (an unrestricted
+``⊤ ⊑ {a}`` would range over data values and make an OWL-consistent knowledge
+base inconsistent). The sort, typing and datatype axioms are derived from the
+vocabulary the knowledge base uses, so name the concepts you are going to ask
+about when you build it, ``dl.kb_to_fol(tbox, abox, query=[C, D])`` -- a goal over
+a name the bundle does not cover is refused by name, not answered wrongly. The
+image is sound -- every OWL model expands to a model of it, so ``proved``
+transfers to OWL 2 -- and deliberately not complete: facets are uninterpreted
+for ``api.prove``, a literal is typed only by the datatype it was written with,
+and the size of a value space is not stated, so ``refuted`` does not transfer
+(``kb.refutation_is_decisive`` is ``False`` exactly when there is a data layer).
+See "The data layer: two sorts" in the description-logic guide.
+
+Every ``dl.external_*`` function mirrors its ``dl.<name>`` in-house-tableau
+namesake's signature and reduction exactly (``external_subsumes`` reduces to
+``external_concept_satisfiable`` the way ``subsumes`` reduces to
+``concept_satisfiable``, and so on), just decided over the bigger ALCHQ + I + O
+fragment instead — see :mod:`unicode_logic_kit.dl.owl_reasoner`'s module docstring.
+"""
+
+from .concepts import (
+    Concept, Top, Bottom, Atomic, Not, And, Or, Exists, ForAll, AtLeast, AtMost,
+    InverseRole, Nominal, HasValue, DataExists, DataForAll, DataHasValue,
+    DataAtLeast, DataAtMost, nnf,
+)
+from .datatypes import (
+    Literal, DataRange, Datatype, DatatypeRestriction, DataOneOf,
+    DataComplementOf, DataIntersectionOf, DataUnionOf, UnsupportedDatatypeError,
+    OWL_THING, OWL_DATA, datarange_to_fol,
+)
+from .tableau import (
+    TBox, ABox,
+    concept_satisfiable, concept_unsatisfiable, subsumes, equivalent, abox_consistent,
+    instance_check, instance_retrieval, realize, realize_all,
+    NonSimpleRoleError, UnsupportedConceptError, UnsupportedAxiomError,
+    RoleExpressionError,
+)
+from .classification import classify, Classification
+from .parser import parse_concept, parse_gci, ConceptSyntaxError
+from .translate import (
+    concept_to_fol, subsumption_to_fol, tbox_to_fol, rbox_to_fol, abox_to_fol,
+    databox_to_fol, data_sort_axioms, check_kb_names,
+    kb_to_fol, KnowledgeBaseFOL, SideAxiom, RoleBoxOmittedError,
+    concept_to_modal,
+)
+from .owl_manchester import (
+    parse_manchester, to_manchester, parse_manchester_axiom,
+    parse_manchester_role_axiom, role_axiom_to_manchester, ManchesterSyntaxError,
+    parse_manchester_data_range, to_manchester_data_range, parse_manchester_literal,
+)
+from .owl_functional import (
+    parse_owl_functional, parse_owl_functional_axioms, to_owl_functional,
+    parse_owl_functional_class_expression, to_owl_functional_class_expression,
+    OwlFunctionalResult, RefusedAxiom, ConsumedAxiom,
+    OwlFunctionalSyntaxError, OwlFunctionalUnsupportedError,
+)
+from .owl_reasoner import (
+    available as owl_reasoner_available,
+    external_concept_satisfiable, external_concept_unsatisfiable,
+    external_subsumes, external_equivalent,
+    external_abox_consistent, external_instance_check, external_instance_retrieval,
+    external_realize, external_realize_all,
+    OwlReasonerError,
+)
+
+__all__ = [
+    "Concept", "Top", "Bottom", "Atomic", "Not", "And", "Or", "Exists", "ForAll",
+    "AtLeast", "AtMost", "InverseRole", "Nominal", "HasValue", "nnf",
+    "DataExists", "DataForAll", "DataHasValue", "DataAtLeast", "DataAtMost",
+    "Literal", "DataRange", "Datatype", "DatatypeRestriction", "DataOneOf",
+    "DataComplementOf", "DataIntersectionOf", "DataUnionOf",
+    "UnsupportedDatatypeError", "OWL_THING", "OWL_DATA", "datarange_to_fol",
+    "TBox", "ABox",
+    "concept_satisfiable", "concept_unsatisfiable", "subsumes", "equivalent",
+    "abox_consistent",
+    "instance_check", "instance_retrieval", "realize", "realize_all",
+    "NonSimpleRoleError", "UnsupportedConceptError", "UnsupportedAxiomError",
+    "RoleExpressionError",
+    "classify", "Classification",
+    "parse_concept", "parse_gci", "ConceptSyntaxError",
+    "concept_to_fol", "subsumption_to_fol", "tbox_to_fol", "rbox_to_fol", "abox_to_fol",
+    "databox_to_fol", "data_sort_axioms", "check_kb_names",
+    "kb_to_fol", "KnowledgeBaseFOL", "SideAxiom", "RoleBoxOmittedError",
+    "concept_to_modal",
+    "parse_manchester", "to_manchester", "parse_manchester_axiom",
+    "parse_manchester_role_axiom", "role_axiom_to_manchester", "ManchesterSyntaxError",
+    "parse_manchester_data_range", "to_manchester_data_range", "parse_manchester_literal",
+    "parse_owl_functional", "parse_owl_functional_axioms", "to_owl_functional",
+    "parse_owl_functional_class_expression", "to_owl_functional_class_expression",
+    "OwlFunctionalResult", "RefusedAxiom", "ConsumedAxiom",
+    "OwlFunctionalSyntaxError", "OwlFunctionalUnsupportedError",
+    "owl_reasoner_available",
+    "external_concept_satisfiable", "external_concept_unsatisfiable",
+    "external_subsumes", "external_equivalent",
+    "external_abox_consistent", "external_instance_check", "external_instance_retrieval",
+    "external_realize", "external_realize_all",
+    "OwlReasonerError",
+]

unicode_logic_kit/dl/classification.py

@@ -0,0 +1,227 @@
+"""TBox classification: the named-concept subsumption hierarchy, as a pure reduction
+to :func:`unicode_logic_kit.dl.tableau.subsumes`.
+
+Given a TBox, :func:`classify` collects every named (:class:`~unicode_logic_kit.dl.concepts.Atomic`)
+concept mentioned in it, decides the full pairwise subsumption matrix over those names
+with the already-tested ``subsumes``, and turns that matrix into the structure an OWL
+reasoner's classifier reports: equivalence classes (for concepts a TBox happens to make
+synonyms), a transitively-reduced Hasse diagram of direct parents/children, and the
+free transitive closure (``ancestors``). No new tableau completion rules are added —
+correctness rides entirely on ``subsumes``'s existing soundness and completeness for ALC.
+
+Public API: :class:`Classification`, :func:`classify`.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, FrozenSet, Iterable, List, Optional, Set
+
+from .concepts import (
+    Concept, Top, Bottom, Atomic, Not, And, Or, Exists, ForAll, AtLeast, AtMost,
+    InverseRole, Nominal, HasValue, DATA_CONCEPTS,
+)
+from .tableau import TBox, subsumes, _reject_beyond_alc, _reject_inputs, _reject_role_box
+
+
+@dataclass(frozen=True)
+class Classification:
+    """The named-concept subsumption hierarchy of a TBox (see :func:`classify`).
+
+    Every key and every member of every value is a *canonical name*: the
+    lexicographically smallest name in its mutual-subsumption equivalence class, so
+    that a TBox with synonyms (``Bachelor ≡ Man ⊓ ¬Married``) still reports one node
+    per distinct concept rather than one per name.
+    """
+
+    equivalents: Dict[str, FrozenSet[str]]
+    """Canonical name -> its full synonym set (itself included)."""
+
+    parents: Dict[str, FrozenSet[str]]
+    """Canonical name -> its *direct* super-concept names (the Hasse diagram)."""
+
+    children: Dict[str, FrozenSet[str]]
+    """Canonical name -> its *direct* sub-concept names (the Hasse diagram)."""
+
+    ancestors: Dict[str, FrozenSet[str]]
+    """Canonical name -> ALL (transitively closed) super-concept names."""
+
+
+def _atomic_names(concept: Concept, names: Set[str]) -> None:
+    """Recursively collect every :class:`Atomic` name occurring in ``concept`` into ``names``.
+
+    Refuses — through the tableau's own concept guard, with
+    :class:`~unicode_logic_kit.dl.tableau.UnsupportedConceptError`, the refusal every
+    other entry point gives — a :class:`~unicode_logic_kit.dl.concepts.Nominal`
+    (caught directly: it is not "atomic-shaped" enough to fall through the
+    isinstance chain below, so it hits the final ``else`` on its own) or an
+    :class:`~unicode_logic_kit.dl.concepts.InverseRole`-valued ``role`` field
+    (checked EXPLICITLY in the ``Exists``/``ForAll``/``AtLeast``/``AtMost``
+    branch below, unlike :func:`unicode_logic_kit.dl.concepts.nnf`'s matching
+    branches, which leave ``role`` untyped on purpose — see that function's
+    docstring): without this explicit check, an ``InverseRole``-only axiom
+    would silently contribute NO names to :func:`classify`'s vocabulary
+    (``Exists``/``ForAll`` only ever recurse into ``.concept``, never inspect
+    ``.role``), so a TBox whose ONLY axiom uses one would classify as an empty,
+    vacuously "fine" hierarchy instead of raising — the one shape in this
+    module where :func:`unicode_logic_kit.dl.tableau.subsumes`'s own
+    ``_reject_beyond_alc`` guard would never even get called to catch it (see
+    :func:`classify`'s docstring: it never calls ``subsumes`` at all when its
+    collected vocabulary is empty).
+
+    A :class:`~unicode_logic_kit.dl.concepts.HasValue` and a data restriction are
+    refused through the tableau's own concept guard, with
+    :class:`~unicode_logic_kit.dl.tableau.UnsupportedConceptError`.
+    """
+    if isinstance(concept, Atomic):
+        names.add(concept.name)
+    elif isinstance(concept, (Top, Bottom)):
+        pass
+    elif isinstance(concept, DATA_CONCEPTS):
+        # A data restriction names a DATA property and a data range, never a
+        # class, so it contributes no name -- but it is outside the fragment the
+        # reduction to ``subsumes`` decides, and with a one-name vocabulary
+        # ``subsumes`` is never called to say so. The tableau's own concept
+        # guard raises the SAME refusal every other entry point gives.
+        _reject_beyond_alc(concept)
+    elif isinstance(concept, HasValue):
+        # Contributes NO class name -- a value restriction names a ROLE and an
+        # INDIVIDUAL, neither of which belongs in a subsumption hierarchy over
+        # named CONCEPTS -- but it is a nominal in disguise, which the reduction
+        # to ``subsumes`` does not decide, and with a one-name vocabulary
+        # ``subsumes`` is never called to say so. The tableau's own concept
+        # guard raises the SAME refusal every other entry point gives.
+        _reject_beyond_alc(concept)
+    elif isinstance(concept, Not):
+        _atomic_names(concept.concept, names)
+    elif isinstance(concept, (And, Or)):
+        _atomic_names(concept.left, names)
+        _atomic_names(concept.right, names)
+    elif isinstance(concept, (Exists, ForAll, AtLeast, AtMost)):
+        if isinstance(concept.role, InverseRole):
+            # An inverse role contributes no class name either, and with a
+            # one-name vocabulary ``subsumes`` is never called to refuse it. The
+            # tableau's own concept guard raises the SAME refusal every other
+            # entry point gives (UnsupportedConceptError, which the MCP tools
+            # return as a structured error; a bare TypeError escaped them).
+            _reject_beyond_alc(concept)
+        _atomic_names(concept.concept, names)
+    else:
+        # A bare Nominal lands here: refused by the same guard, by name.
+        _reject_beyond_alc(concept)
+        raise TypeError(f"classify: unsupported concept {type(concept).__name__}")
+
+
+def _equivalence_classes(names: List[str], holds) -> List[Set[str]]:
+    """Connected components of the mutual-subsumption graph over ``names``."""
+    adjacency: Dict[str, Set[str]] = {n: set() for n in names}
+    for a in names:
+        for b in names:
+            if a != b and holds[(a, b)] and holds[(b, a)]:
+                adjacency[a].add(b)
+                adjacency[b].add(a)
+    seen: Set[str] = set()
+    classes: List[Set[str]] = []
+    for n in names:
+        if n in seen:
+            continue
+        stack, component = [n], set()
+        while stack:
+            x = stack.pop()
+            if x in component:
+                continue
+            component.add(x)
+            stack.extend(adjacency[x] - component)
+        seen |= component
+        classes.append(component)
+    return classes
+
+
+def classify(tbox: TBox, concepts: Optional[Iterable[Concept]] = None) -> Classification:
+    """Classify every named concept of ``tbox`` into a subsumption hierarchy.
+
+    The vocabulary is every :class:`Atomic` name reachable from ``tbox.inclusions``
+    (walked through ``And``/``Or``/``Not``/``Exists``/``ForAll``), extended with the
+    names occurring in ``concepts`` when given — useful for a name of interest that
+    never appears in an axiom (and so would otherwise be invisible, an isolated node
+    with no parents/children/ancestors and a singleton equivalence class).
+
+    Raises:
+        ~unicode_logic_kit.dl.tableau.UnsupportedAxiomError:
+            ``tbox`` carries an axiom KIND no in-house rule
+            decides, exactly as ``subsumes`` would raise -- including for a
+            TBox with ONE named concept, where the pair loop below never calls
+            ``subsumes`` at all (its only ordered pair is ``(A, A)``, answered
+            ``True`` without a tableau), so without the up-front guard that one
+            shape returned a hierarchy for a knowledge base every other entry
+            point refuses.
+        ~unicode_logic_kit.dl.tableau.UnsupportedConceptError:
+            a stored class expression (or one of
+            ``concepts``) contains a value restriction (``HasValue``, a
+            nominal in disguise) or a data restriction -- raised by the
+            tableau's concept guard whatever the vocabulary's size.
+    """
+    # The axiom-level guard, once, before anything is decided -- the same call
+    # concept_satisfiable/abox_consistent open with. A TBox with zero or one
+    # named concept never reaches `subsumes`, so inheriting it was not enough.
+    _reject_role_box(tbox, None)
+    names: Set[str] = set()
+    for sub, sup in tbox.inclusions:
+        _atomic_names(sub, names)
+        _atomic_names(sup, names)
+    extra = list(concepts) if concepts is not None else []
+    for c in extra:
+        _atomic_names(c, names)
+    # The concept-level half of the same guard, over EVERY class expression the
+    # TBox stores (a domain or range filler included -- `_atomic_names` above
+    # reads inclusions only) and over the extra concepts. `subsumes` runs it per
+    # pair, but a vocabulary of fewer than two names makes no such call, and a
+    # knowledge base that every other entry point refuses (an OWL 2 built-in
+    # property name as a restriction's role, a nominal in a domain filler) got a
+    # hierarchy here.
+    _reject_inputs(tbox, None, extra)
+    ordered = sorted(names)
+
+    # The O(n^2) reduction: decide sub/sup for every ordered pair with `subsumes`.
+    holds = {}
+    for a in ordered:
+        for b in ordered:
+            holds[(a, b)] = True if a == b else subsumes(Atomic(a), Atomic(b), tbox)
+
+    classes = _equivalence_classes(ordered, holds)
+    canon_of: Dict[str, str] = {}
+    equivalents: Dict[str, FrozenSet[str]] = {}
+    for component in classes:
+        canon = min(component)
+        equivalents[canon] = frozenset(component)
+        for member in component:
+            canon_of[member] = canon
+    canon_names = sorted(equivalents)
+
+    # Free byproduct: the un-reduced transitive closure, at the canonical-name level
+    # (equivalence-class members all agree on what they subsume/are subsumed by, so one
+    # representative pairwise lookup per class is enough).
+    ancestors: Dict[str, Set[str]] = {c: set() for c in canon_names}
+    for a in canon_names:
+        for b in canon_names:
+            if a != b and holds[(a, b)]:
+                ancestors[a].add(b)
+
+    # Transitive reduction (Hasse diagram): drop a -> b when some c also ancestor of a
+    # already reaches b, i.e. a -> c -> b makes a -> b redundant.
+    parents: Dict[str, FrozenSet[str]] = {}
+    for a in canon_names:
+        direct = set(ancestors[a])
+        for c in ancestors[a]:
+            direct -= ancestors[c]
+        parents[a] = frozenset(direct)
+
+    children: Dict[str, Set[str]] = {c: set() for c in canon_names}
+    for a, ps in parents.items():
+        for p in ps:
+            children[p].add(a)
+
+    return Classification(
+        equivalents=equivalents,
+        parents=parents,
+        children={c: frozenset(s) for c, s in children.items()},
+        ancestors={c: frozenset(s) for c, s in ancestors.items()},
+    )