kele 0.0.1a1__cp313-cp313-win32.whl

kele/syntax/connectives.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+
+class Connective(StrEnum):
+    """Logical connectives supported by the inference engine syntax layer."""
+    AND = "AND"
+    OR = "OR"
+    NOT = "NOT"
+    IMPLIES = "IMPLIES"
+    EQUAL = "EQUAL"
+
+
+AND: Final[Connective] = Connective.AND
+OR: Final[Connective] = Connective.OR
+NOT: Final[Connective] = Connective.NOT
+IMPLIES: Final[Connective] = Connective.IMPLIES
+EQUAL: Final[Connective] = Connective.EQUAL

kele/syntax/dnf_converter.py

@@ -0,0 +1,145 @@
+from functools import reduce
+import warnings
+from uuid import uuid1
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+from sympy import Symbol
+from sympy.logic.boolalg import (
+    And as SymAnd,
+    Equivalent,
+    Implies,
+    Not as SymNot,
+    Or as SymOr,
+    simplify_logic,
+)
+from bidict import bidict
+
+from .base_classes import (
+    Assertion,
+    Formula,
+    Intro,
+    Rule,
+)
+
+from .connectives import (
+    AND,
+    EQUAL,
+    IMPLIES,
+    NOT,
+    OR,
+)
+
+
+class _AssertionSymbol:
+    assertion_to_id: ClassVar[bidict[Assertion, Symbol]] = bidict()
+
+    @classmethod
+    def get_symbol(cls, assertion: Assertion) -> Symbol:
+        if assertion not in cls.assertion_to_id:
+            cls.assertion_to_id[assertion] = Symbol(str(uuid1()))
+        return cls.assertion_to_id[assertion]
+
+    @classmethod
+    def get_assertion(cls, assertion_id: Symbol) -> Assertion:
+        return cls.assertion_to_id.inverse[assertion_id]
+
+
+def convert_to_dnf(formula: Formula | Assertion) -> Formula | Assertion:
+    """
+    将一个公式转化为dnf格式
+
+    :param formula: _description_
+    :type formula: Formula | Assertion
+    :return: _description_
+    :rtype: Formula | Assertion
+    """
+    sympy_expr = _convert_to_sympy_expr(formula)
+    dnf_sympy_expr = simplify_logic(sympy_expr, form='dnf')
+    return _rebuild_formula(dnf_sympy_expr)
+
+
+def _rebuild_formula(sympy_expr: Any) -> Formula | Assertion:  # noqa: ANN401
+    if isinstance(sympy_expr, Symbol):
+        return _AssertionSymbol.get_assertion(sympy_expr)
+    if isinstance(sympy_expr, SymNot):
+        return Formula(connective=NOT, formula_left=_rebuild_formula(sympy_expr.args[0]))
+    if isinstance(sympy_expr, SymAnd):
+        return reduce(lambda x, y: Formula(connective=AND, formula_left=x, formula_right=y),
+                        map(_rebuild_formula, sympy_expr.args))
+    if isinstance(sympy_expr, SymOr):
+        return reduce(lambda x, y: Formula(connective=OR, formula_left=x, formula_right=y),
+                        map(_rebuild_formula, sympy_expr.args))
+
+    raise ValueError(f"Unknown sympy expression type {type(sympy_expr)}")
+
+
+def _convert_to_sympy_expr(cur_formula: Formula | Assertion) -> Any:  # noqa: ANN401
+    if isinstance(cur_formula, Assertion):
+        return _AssertionSymbol.get_symbol(cur_formula)
+    if cur_formula.connective == NOT:
+        return SymNot(_convert_to_sympy_expr(cur_formula.formula_left))
+    if TYPE_CHECKING:
+        cur_formula.formula_right = cast("Formula | Assertion", cur_formula.formula_right)
+    if cur_formula.connective == AND:
+        return SymAnd(_convert_to_sympy_expr(cur_formula.formula_left), _convert_to_sympy_expr(cur_formula.formula_right))
+    if cur_formula.connective == OR:
+        return SymOr(_convert_to_sympy_expr(cur_formula.formula_left), _convert_to_sympy_expr(cur_formula.formula_right))
+    if cur_formula.connective == IMPLIES:
+        return Implies(_convert_to_sympy_expr(cur_formula.formula_left), _convert_to_sympy_expr(cur_formula.formula_right))
+    if cur_formula.connective == EQUAL:
+        return Equivalent(_convert_to_sympy_expr(cur_formula.formula_left), _convert_to_sympy_expr(cur_formula.formula_right))
+    raise ValueError(f"Unknown connective {cur_formula.connective}")
+
+
+class RuleSafetyProcesser:
+    """
+    将规则拆分成一系列规则，且body部分是DNF
+    """
+    def _split_into_dnf_formulas(self, formula: Formula | Assertion) -> list[Assertion | Formula]:
+        """
+        将公式拆分成DNF规则
+
+        :param formula: 待拆分的公式
+        :type formula: Formula | Assertion
+        :return: 拆分后的DNF规则
+        :rtype: list[Assertion | Formula]
+        """
+        if isinstance(formula, Assertion) or formula.connective != OR:
+            return [formula]
+        if TYPE_CHECKING:
+            formula.formula_right = cast("Formula | Assertion", formula.formula_right)
+        return self._split_into_dnf_formulas(formula.formula_left) + self._split_into_dnf_formulas(formula.formula_right)
+
+    def split_rule_and_process_safety[T1: Rule](self, rule: T1) -> list[T1]:
+        """
+        将公式拆分成DNF规则，并且将unsafe_variables以intro的形式加入规则
+
+        :param formula: 待拆分的公式
+        :type formula: Formula | Assertion
+        :return: 拆分后的DNF规则
+        :rtype: list[Assertion | Formula]
+        """
+        # 1、转化规则并拆分
+        new_rules: list[T1] = []
+        dnf_body = convert_to_dnf(rule.body)
+        body_formulas = self._split_into_dnf_formulas(dnf_body)
+        new_rules.extend(rule.replace(body=single_body_formula) for single_body_formula in body_formulas)
+
+        # 2、将unsafe_variables以intro的形式加入新规则
+        processed_new_rules: list[T1] = []
+
+        for r in new_rules:
+            unsafe_variables = r.unsafe_variables
+            new_rule_body = r.body
+            if unsafe_variables:
+                warnings.warn(f"""Rule {r!s} contains unsafe variables {[str(u) for u in unsafe_variables]}; auto-handled.\n
+                          A rule is safe if variables in action terms and negative literals are all included in non-action, positive assertions.\n
+                          For details, see the engine tutorial: #TODO
+                          """, stacklevel=4)  # TODO: add URL
+            for single_variable in unsafe_variables:
+                new_rule_body = Formula(new_rule_body, AND, Intro(single_variable))
+
+            new_rule = r.replace(body=new_rule_body)
+            processed_new_rules.append(new_rule)
+
+        return processed_new_rules

kele/syntax/external.py

@@ -0,0 +1,17 @@
+from collections.abc import Callable
+from pydantic import BaseModel, ConfigDict
+
+from .base_classes import FACT_TYPE, Question, Assertion
+
+
+class SankuManagementSystem(BaseModel):
+    """三库系统的抽象，主要用于类型检查和说明数据结构"""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    knowledge: list[FACT_TYPE] = []
+    initial_by_question: Callable[[Question, int | None], list[FACT_TYPE]] = lambda x, y: []
+    # TODO(lbq): 需与泳融沟通，使用一个question和一个取出的上限值，由三库系统决定返回哪些有用的信息协助初始化。
+    # 另外 HACK: 实则应该用memcached语言传入，而且这是一个http链接，不是函数
+    query_assertion: Callable[[Assertion | list[Assertion]], list[Assertion]] = lambda x: []
+    update_facts: Callable[[FACT_TYPE | list[FACT_TYPE]], None] = lambda x: None

kele/syntax/sub_concept.py

@@ -0,0 +1,87 @@
+# ruff: noqa: PLC0415
+
+from __future__ import annotations
+import warnings
+from contextlib import contextmanager
+import re
+from collections.abc import Generator
+from collections.abc import Sequence, Mapping
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from kele.syntax import Concept
+
+
+# Concept从属关系录入
+def register_concept_relations(relations: str | Mapping[Concept | str, Sequence[Concept | str]] | Sequence[tuple[Concept | str, Concept | str]]) \
+        -> None:
+    """
+    批量注册从属关系列表 [(child, parent), ...]，每条对应一个概念从属关系 child ⊆ parent。
+    支持三种录入形式：字符串DSL / 映射(子->[父...]) / 列表[(子,父),...]
+    """
+    if isinstance(relations, str):
+        register_concept_from_string(relations)
+    elif isinstance(relations, Mapping):
+        register_concept_from_mapping(relations)
+    else:
+        register_concept_subsumptions(relations)
+
+
+def register_concept_subsumptions(pairs: Sequence[tuple[Concept | str, Concept | str]]) -> None:
+    """批量注册从属关系列表 [(child, parent), ...]"""
+    from kele.syntax import Concept
+    for ch, pa in pairs:
+        Concept.add_subsumption(ch, pa)
+
+
+def register_concept_from_mapping(mapping: Mapping[Concept | str, Sequence[Concept | str]]) -> None:
+    """从映射(子->[父...])注册"""
+    from kele.syntax import Concept
+    for ch, parents in mapping.items():
+        for pa in parents:
+            Concept.add_subsumption(ch, pa)
+
+
+def register_concept_from_string(spec: str) -> None:
+    """
+    从字符串录入多条从属关系。支持分隔符：逗号/分号/换行；关系符：'⊆'、'<='。
+    :raise ValueError: 分隔符需要用'⊆'、'<='
+    """  # noqa: DOC501
+    from kele.syntax import Concept
+    items = re.split(r"[;,]+", spec)
+    for item in items:
+        s = item.strip()
+        if not s:
+            continue
+        m = re.match(r"^(.+?)(?:⊆|<=)(.+)$", s)
+        if not m:
+            raise ValueError(f"Unable to parse inclusion statement: {s!r}. Expected 'A ⊆ B' or 'A <= B'.")
+        left, right = m.group(1).strip(), m.group(2).strip()
+        Concept.add_subsumption(left, right)
+
+
+def with_concept_relations(relations: str | Mapping[Concept | str, Sequence[Concept | str]] | Sequence[tuple[Concept | str, Concept | str]]) \
+        -> object:
+    """装饰器：在被装饰对象定义时注册关系。
+
+    用法：
+        @with_concept_relations("int ⊆ real; positive_int <= int")
+        def build_ops(): ...
+    """
+    def _decorator(obj: object) -> object:
+        register_concept_relations(relations)
+        return obj
+    return _decorator
+
+
+@contextmanager
+def concept_relation_scope(relations: str | Mapping[Concept | str, Sequence[Concept | str]] | Sequence[tuple[Concept | str, Concept | str]]) \
+        -> Generator:  # type: ignore[type-arg]
+    """上下文管理器：进入时注册给定关系，注意退出时不做回滚，因为我们暂时认为子集关系是不变的。"""
+    register_concept_relations(relations)
+    try:
+        yield
+    finally:
+        warnings.warn(
+            "Registers the given relation on entry; no rollback on exit because subset relations are assumed immutable.",
+            stacklevel=2,
+        )

kele/syntax/syntacticsugar.py

@@ -0,0 +1,201 @@
+# ruff: noqa: PLR6301
+
+"""
+这个模块提供四则运算的语法糖，使用 Lark 语法解析器。
+请注意每个CompoundTerm都必须用括号括起来，包括但不限于嵌套、原子的CompoundTerm等
+支持的符号包括：
+- 数字（整数或浮点数）
+- 变量名（[A-Za-z_]\\w*）
+- 括号（支持嵌套）
+- 二元操作符：+、-、*、/
+- 一元操作符：+、-
+- 方程式：e_term "=" e_term
+解析后会将语法树转换为推理引擎的syntax：CompoundTerm、Constant、Variable等
+支持的op和concept置于builtin_base文件夹，例如 arithmetic_plus_op、arithmetic_minus_op 等。
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from lark import Lark, Transformer, Token
+
+from kele.knowledge_bases.builtin_base.builtin_concepts import (
+    COMPLEX_NUMBER_CONCEPT,
+)
+from kele.knowledge_bases.builtin_base.builtin_operators import (
+    arithmetic_divide_op,
+    get_arithmetic_equation_op,
+    arithmetic_minus_op,
+    arithmetic_negate_op,
+    arithmetic_plus_op,
+    arithmetic_times_op,
+)
+from kele.syntax import CompoundTerm, Constant, Variable, TERM_TYPE, Assertion, Formula
+
+
+GRAMMAR: Final[str] = r"""
+// 顶层：（方程中的）等式 | 带括号表达式 | 裸数字
+start: equation
+     | pexpr                 -> top_paren_expr
+     | number
+
+// （方程中的）等式：两侧允许 带括号表达式 或 裸数字
+equation: e_term "=" e_term   -> equation
+e_term: pexpr | number
+
+// 带括号表达式：目前是四则运算 + 一元正负，允许嵌套
+pexpr: "(" expr ")"          -> paren
+     | "(" pexpr ")"         -> nested_paren
+
+// 四则运算
+?expr: expr "+" term         -> add
+     | expr "-" term         -> sub
+     | expr "*" term         -> mul
+     | expr "/" term         -> div
+     | "-" expr              -> neg
+     | "+" expr              -> pos
+     | term
+
+?term: number
+       | symbol
+       | pexpr               // 支持嵌套括号
+
+number: NUMBER
+symbol: NAME
+
+NAME: /[A-Za-z_]\w*/
+%import common.NUMBER
+%ignore /[ \t]+/
+"""
+
+
+class ToSyntax(Transformer):  # type: ignore[type-arg]
+    """Transform Lark parse trees into AL inference engine terms."""
+
+    # --- Entrypoints & helpers -------------------------------------------------
+
+    def start(self, items: list[TERM_TYPE | Assertion | Formula]) -> TERM_TYPE | Assertion | Formula:
+        """Return the single top-level term."""
+        return items[0]
+
+    def e_term(self, items: list[TERM_TYPE]) -> TERM_TYPE:
+        """Return an equation-side term unchanged."""
+        return items[0]
+
+    # --- Parentheses handling --------------------------------------------------
+
+    def top_paren_expr(self, items: list[TERM_TYPE]) -> TERM_TYPE:
+        """Alias for a top-level parenthesized expression."""
+        return items[0]
+
+    def paren(self, items: list[TERM_TYPE]) -> TERM_TYPE:
+        """Elide a single layer of parentheses."""
+        return items[0]
+
+    def nested_paren(self, items: list[TERM_TYPE]) -> TERM_TYPE:
+        """Elide nested parentheses."""
+        return items[0]
+
+    # --- Atoms -----------------------------------------------------------------
+
+    def number(self, items: list[Token]) -> Constant:
+        """Convert a numeric token into a :class:`Constant`."""
+        s = str(items[0])
+        v = float(s) if ("." in s or "e" in s or "E" in s) else int(s)
+        return Constant(v, COMPLEX_NUMBER_CONCEPT)
+
+    def name(self, items: list[Token]) -> Variable:
+        """Convert an identifier token into a :class:`Variable`."""
+        return Variable(str(items[0]))
+
+    # --- Unary ops -------------------------------------------------------------
+
+    def neg(self, items: list[CompoundTerm]) -> CompoundTerm:
+        """Build a unary negation term."""
+        return CompoundTerm.from_parts(arithmetic_negate_op, [items[0]])
+
+    def pos(self, items: list[CompoundTerm]) -> TERM_TYPE:
+        """Return the inner term for unary plus (no-op)."""
+        return items[0]
+
+    # --- Binary ops ------------------------------------------------------------
+
+    def add(self, items: list[CompoundTerm]) -> CompoundTerm:
+        """Build an addition term."""
+        left, right = items
+        return CompoundTerm.from_parts(arithmetic_plus_op, [left, right])
+
+    def sub(self, items: list[CompoundTerm]) -> CompoundTerm:
+        """Build a subtraction term."""
+        left, right = items
+        return CompoundTerm.from_parts(arithmetic_minus_op, [left, right])
+
+    def mul(self, items: list[CompoundTerm]) -> CompoundTerm:
+        """Build a multiplication term."""
+        left, right = items
+        return CompoundTerm.from_parts(arithmetic_times_op, [left, right])
+
+    def div(self, items: list[CompoundTerm]) -> CompoundTerm:
+        """Build a division term."""
+        left, right = items
+        return CompoundTerm.from_parts(arithmetic_divide_op, [left, right])
+
+    # --- Equation --------------------------------------------------------------
+
+    def equation(self, items: list[CompoundTerm]) -> CompoundTerm:
+        """Build an equality term for the left/right sides."""
+        left, right = items
+        return CompoundTerm.from_parts(get_arithmetic_equation_op, [left, right])
+
+
+_parser: Lark = Lark(GRAMMAR, parser="lalr", maybe_placeholders=False)
+_to_syntax: ToSyntax = ToSyntax()
+
+
+class SyntacticSugar:
+    """Callable facade that delegates to :func:`parse_term`."""
+
+    def __call__(self, input_str: str) -> TERM_TYPE | Assertion | Formula:
+        """Parse ``input_str`` and return a transformed term.
+
+        Parameters
+        ----------
+        input_str
+            The input string to parse.
+
+        Returns
+        -------
+        Term
+            The transformed term produced by :func:`parse_term`.
+
+        Raises
+        ------
+        SyntaxError
+            If parsing fails for any reason.
+        """
+        try:
+            return _to_syntax.transform(_parser.parse(s))  # type: ignore[no-any-return]
+        except Exception as e:
+            raise SyntaxError(f"Parsing failed: {e}\n") from e
+
+
+syntactic_sugar: Final[SyntacticSugar] = SyntacticSugar()
+
+
+if __name__ == "__main__":
+    cases: list[str] = [
+        "(1+2)=3",
+        "(x*2+3)",
+        "1",
+        "((1)+(2))=((3))",  # 多余括号仍可
+        "((1)+(2))=3",
+        "((1+2))=3",
+        "(1+(2*3))=7",
+        "(-(1+2))",  # 顶层表达式需括号
+        "(1+x)",  # 所有的term都要求有括号
+        "(1+(-x))",
+        "(((1+x)))",
+    ]
+    for s in cases:
+        print(s, "=>", syntactic_sugar(s))  # noqa: T201

kele-0.0.1a1.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: kele
+Version: 0.0.1a1
+Summary: 推理引擎
+Author: Bingqian Li, BoYang Zhang, Weiming Hong, Hao Zhang, Yi Zhou
+Maintainer-email: Bingqian Li <libq2022@alumni.shanghaitech.edu.cn>, Yi Zhou <yi_zhou@ustc.edu.cn>
+License: BSD-3-Clause
+License-File: LICENSE
+License-File: licensecheck.json
+Requires-Python: <4.0,>=3.13
+Requires-Dist: bidict<1.0,>=0.23
+Requires-Dist: dacite<2.0,>=1.9
+Requires-Dist: graphviz==0.20.3
+Requires-Dist: lark<2.0,>=1.0
+Requires-Dist: networkx<4.0,>=3.5
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: polars>=1.32
+Requires-Dist: prometheus-client>=0.22
+Requires-Dist: psutil>=7.0
+Requires-Dist: pydantic<3.0,>=2.0.0
+Requires-Dist: python-sat<2.0,>=1.7.dev0
+Requires-Dist: pyvis<0.4,>=0.3
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: sympy<2.0,>=1.13
+Requires-Dist: tyro<2.0,>=0.9
+Description-Content-Type: text/markdown
+
+# KELE Inference Engine
+
+[English](README.md) | [中文](README.zh.md)
+
+<!-- Badges: If services are not configured, badges may show unknown/404; enable as needed. -->
+[![License](https://img.shields.io/github/license/USTC-KnowledgeComputingLab/KELE.svg)](LICENSE)
+[![Build](https://github.com/USTC-KnowledgeComputingLab/KELE/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/USTC-KnowledgeComputingLab/KELE/actions/workflows/release.yml)
+![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://msg-bq.github.io/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![Commit Message](https://img.shields.io/badge/commit%20message-style%20guide-yellow)](CONTRIBUTING.md)
+
+---
+
+KELE is a forward-chaining inference engine based on [Assertion Logic](https://link.springer.com/chapter/10.1007/978-3-319-63703-7_9), implementing a subset of the logic.
+
+It supports **term-level facts**, **nested terms**, **equivalence axioms**, and **operators with functions**, and integrates well with modern Python (3.13+). You can embed your tools through operator implementations (and embed KELE into your tools), while we leave the burden of wrapping/binding other languages to developers rather than users.
+
+> ⚠️ **Project status**  \
+> We released the first alpha version on **12/31** and will move it to a beta release as soon as possible after the holiday. The engine will maintain backward compatibility for commonly used public classes and modules, while internal components are still evolving and under active development.
+
+### ✨ Features
+
+- **Term-level facts and reasoning**: term-centric organization and inference, suited for equality knowledge
+- **Equivalence axioms**: convenient equivalence expressions with internal maintenance
+- **Nested compound terms**: operators can nest to build complex structures
+- **Implement functions for operators**: implement functions for operators (e.g., arithmetic, equation solving)
+
+> Implement functions for operators ≈ Prolog meta-predicates / ASP HEX external predicates (not identical semantics, similar usage).
+
+### 🔍 Matching semantics
+
+- **Loose matching**: treat subsumption as "intersection" matching, without input/constraint distinction
+- **Concept overlap check**: returns whether there is a non-empty common concept set aligned
+- **Mismatch handling**: incompatible
+
+### 🔧 Installation
+
+#### Option A: PyPI (after release)
+
+You can grab the latest built wheel from GitHub Actions or install a published release directly.
+
+```bash
+pip install kele
+```
+
+#### Option B: Build from source
+
+> **Requirements**: Python 3.13+; Rust toolchain (`rustup`); on Windows, MSVC (Visual Studio Build Tools).
+
+```bash
+git clone https://github.com/USTC-KnowledgeComputingLab/KELE
+cd KELE
+uv sync
+uv run maturin develop --skip-install  # install rust and MSVC (Windows) beforehand
+```
+
+### 🚀 Quick start
+
+> Full example: `examples/relationship_quick_start.py`
+
+```bash
+uv run python examples/relationship_quick_start.py
+# Output: grandparent relation inference result (forward-chaining demo)
+```
+
+### 🧩 Core syntax at a glance
+
+| Type              | Meaning                                     | Example/Hint                                         |
+| ----------------- |---------------------------------------------| ---------------------------------------------------- |
+| `Concept`         | Group of objects sharing something in common | `Person = Concept("Person")`                        |
+| `Constant`        | Object (belongs to concepts)                | `alice = Constant("Alice", Person)`                 |
+| `Variable`        | Placeholder in rules/queries                | `X = Variable("X")`                                 |
+| `Operator`        | Map a tuple of objects into a single one    | `parent(Person, Person) -> Bool`                     |
+| `CompoundTerm`    | Operator + arguments                        | `CompoundTerm(parent, [alice, bob])`                 |
+| `Assertion`       | “term = term” assertion                     | `Assertion(..., ...)`           |
+| `Formula`         | Combine assertions with AND/OR/…            | `Formula(A, "AND", B)`                              |
+| `Rule`            | body → head                                 | `Rule(head=..., body=...)`                  |
+| `QueryStructure`  | Query input (premises + question)           | `QueryStructure(premises=[...], question=[...])`     |
+| `InferenceEngine` | Engine core                                 | `InferenceEngine(facts=[...], rules=[...])`          |
+
+`examples/relationship_quick_start.py` shows a family-relation inference example, illustrating how the pieces fit together:
+
+1. Define concepts (`Concept`) and operators (`Operator`), such as `Person`, `parent`, `grandparent`.
+2. Add initial facts (`Assertion`), e.g. “Bob is Alice’s parent”.
+3. Write rules (`Rule` + `Formula`), e.g. “if parent(X, Y) and parent(Y, Z), then grandparent(X, Z)”.
+4. Build a query (`QueryStructure`) and run `InferenceEngine`.
+
+Example snippet (imports/details omitted; see `examples/relationship_quick_start.py` for a runnable version):
+
+```python
+# 1. Define concepts and operators
+Person = Concept("Person")
+...
+
+# 2. Add facts
+alice = Constant("Alice", Person)
+...
+
+facts = [
+    # parent(Alice, Bob) = True
+    Assertion(CompoundTerm(parent, [alice, bob]), true_const),
+    ...
+]
+
+# 3. Define rules + query
+rules = [Rule(
+    head=...,
+    body=...,
+)]
+
+engine = InferenceEngine(facts=facts, rules=rules)
+query = QueryStructure(premises=facts, question=[...])  # e.g., ask for grandparent(Alice, X)
+
+print(engine.infer_query(query))
+```
+
+### 🧭 Documentation
+
+* **Sphinx docs**:
+
+  * Read the Docs: WIP
+  * Build locally: `uv run sphinx-build -b html docs\source docs\build\html`
+
+* **Tutorial**: https://msg-bq.github.io/
+
+### 🗺️ Roadmap
+
+WIP
+
+### 🤝 Contributing
+
+Issues/PRs welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md), and consider enabling `ruff` and `mypy`.
+
+If you have any questions about using the engine—including usage, syntax/semantics, or theoretical foundations—please open an issue or contact us.
+
+### 🪪 License
+
+This project uses the BSD 3-Clause license. See [LICENSE](LICENSE).