Cookbook: deep dive reasoning module; Rete stress test; performance comparison; mixed ReteInferenceExplanation workflow

cookbook/advanced/08_Reasoning_and_Inference.ipynb

@@ -191,6 +191,139 @@
                 "- Backward Chaining Performed\n",
                 "- Explanations Generated\n"
             ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "---\n",
+                "\n",
+                "### Deep Dive: Reasoning Module\n",
+                "\n",
+                "This section provides an in-depth guide to Semantica's reasoning capabilities. Learn rule syntax, fact formats, chaining strategies, and explanation generation with robust, reproducible examples.\n",
+                "\n",
+                "**What you'll practice**\n",
+                "- Defining rules with variables and predicates\n",
+                "- Loading facts in predicate form\n",
+                "- Running forward and backward chaining\n",
+                "- Generating human-readable explanations\n"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "from semantica.kg import GraphBuilder\n",
+                "from semantica.reasoning import InferenceEngine, ExplanationGenerator\n",
+                "\n",
+                "builder = GraphBuilder()\n",
+                "engine = InferenceEngine()\n",
+                "explainer = ExplanationGenerator()\n"
+            ]
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": [
+                "### Rule Syntax\n",
+                "\n",
+                "Rules use predicate logic with variables prefixed by `?`.\n",
+                "\n",
+                "- Example: `IF parent_of(?a, ?b) AND parent_of(?b, ?c) THEN grandparent_of(?a, ?c)`\n",
+                "- Variables unify across predicates in the same rule\n",
+                "- Conclusions are added as new facts when conditions match\n"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "entities = [\n",
+                "    {\"id\": \"alice\", \"type\": \"Person\", \"name\": \"Alice\"},\n",
+                "    {\"id\": \"bob\", \"type\": \"Person\", \"name\": \"Bob\"},\n",
+                "    {\"id\": \"charlie\", \"type\": \"Person\", \"name\": \"Charlie\"},\n",
+                "    {\"id\": \"sf\", \"type\": \"Location\", \"name\": \"San Francisco\"},\n",
+                "    {\"id\": \"california\", \"type\": \"Location\", \"name\": \"California\"}\n",
+                "]\n",
+                "\n",
+                "relationships = [\n",
+                "    {\"source\": \"alice\", \"target\": \"bob\", \"type\": \"parent_of\"},\n",
+                "    {\"source\": \"bob\", \"target\": \"charlie\", \"type\": \"parent_of\"},\n",
+                "    {\"source\": \"sf\", \"target\": \"california\", \"type\": \"located_in\"},\n",
+                "    {\"source\": \"alice\", \"target\": \"sf\", \"type\": \"lives_in\"}\n",
+                "]\n",
+                "\n",
+                "knowledge_graph = builder.build([{\"entities\": entities, \"relationships\": relationships}])\n",
+                "print(len(knowledge_graph.get(\"entities\", [])))\n",
+                "print(len(knowledge_graph.get(\"relationships\", [])))\n"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "rules = [\n",
+                "    \"IF parent_of(?a, ?b) AND parent_of(?b, ?c) THEN grandparent_of(?a, ?c)\",\n",
+                "    \"IF lives_in(?x, ?y) AND located_in(?y, ?z) THEN lives_in(?x, ?z)\"\n",
+                "]\n",
+                "for r in rules:\n",
+                "    engine.add_rule(r)\n"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "for rel in relationships:\n",
+                "    fact = f\"{rel['type']}({rel['source']}, {rel['target']})\"\n",
+                "    engine.add_fact(fact)\n",
+                "\n",
+                "derived = engine.forward_chain()\n",
+                "print(len(derived))\n",
+                "for d in derived:\n",
+                "    print(d.conclusion)\n"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "goals = [\n",
+                "    \"grandparent_of(alice, charlie)\",\n",
+                "    \"lives_in(alice, california)\"\n",
+                "]\n",
+                "for g in goals:\n",
+                "    proof = engine.backward_chain(g)\n",
+                "    print(g)\n",
+                "    print(bool(proof))\n"
+            ]
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": [
+                "if derived:\n",
+                "    exp = explainer.generate_explanation(derived[0])\n",
+                "    print(exp.natural_language)\n",
+                "\n",
+                "goal = \"grandparent_of(alice, charlie)\"\n",
+                "proof = engine.backward_chain(goal)\n",
+                "if proof:\n",
+                "    pexp = explainer.generate_explanation(proof)\n",
+                "    print(pexp.natural_language)\n"
+            ]
         }
     ],
     "metadata": {
@@ -200,4 +333,4 @@
     },
     "nbformat": 4,
     "nbformat_minor": 2
-}
+}