Merge pull request #141 from lab-v2/peng-task1

Add Task 1 tutorials: loading from file and LLM-generated rules

Author: ColtonPayne

docs/source/tutorials/index.rst

@@ -18,5 +18,6 @@ Contents
    ./annotation_function.rst
    ./temporal_classifier_tutorial.rst   
    ./cybersecurity_inconsistency.rst
-
+   ./load_rules_facts_from_file.rst
+   ./llm_generated_rules.rst
 

docs/source/tutorials/llm_generated_rules.rst

@@ -0,0 +1,144 @@
+LLM Generated PyReason Rules
+============================
+
+Introduction
+------------
+In this tutorial, we use a Large Language Model (Claude) to 
+generate a valid PyReason rule for a simple knowledge graph. We then
+validate the generated rule with PyReason's rule parser and run inference
+to show it fires on the graph.
+
+.. note:: 
+   Find the full, executable code `here <https://github.com/lab-v2/pyreason/blob/main/examples/llm_generated_rules_ex.py>`_
+
+Knowledge Graph
+---------------
+We build a small academic knowledge graph with three types of nodes - students, majors, and departments.
+They are connected by two predicates: ``major_in`` and ``in_department``.
+
+.. code:: python
+
+    import networkx as nx
+    g = nx.DiGraph()
+
+    g.add_edge('alice', 'math', major_in=1)
+    g.add_edge('bob',   'math', major_in=1)
+    g.add_edge('mary',  'cs',   major_in=1)
+
+    # Major -> Department
+    g.add_edge('math', 'math_dept', in_department=1)
+    g.add_edge('cs',   'cs_dept',   in_department=1)
+
+The Prompt
+----------
+The prompt describes a specific reasoning goal: deriving which department a student belongs to.
+The head predicate name is fixed to ensure consistent, comparable output across LLMs.
+
+.. code:: python
+
+    PROMPT = """\
+    You are generating a rule for a PyReason knowledge graph.
+
+    ### Task
+    Write a single PyReason rule that derives which department a student belongs to,
+    given that a student is enrolled in a major and that major belongs to a department.
+
+    ### Available predicates
+    - major_in(Student, Major) - student in enrolled in a major
+    - in_department(Major, Department) - major belongs to a department
+
+    ### PyReason rule syntax
+    head_predicate(X,Y) <-N body_predicate_1(X,Z),body_predicates_2(Z,Y)
+
+    - N is the delta: use 0 for immediate firing
+    - Variables are single uppercase letters (X,Y,Z)
+    - Head predicate name must be: student_in_dept
+
+    ### Output format
+    Output the rule on a single line. No explanation, no markdown, no punctuation.
+
+    ### Example (Different predicates, shows syntax only)
+    grandparent(X,Y)<-0 parent(X,Z),parent(Z,Y)
+    """
+
+Generating the Rule
+-------------------
+We call the Anthropic API to send the prompt to Claude and split the response into individual rule string.
+
+.. code:: python
+
+    import anthropic
+
+    client = anthropic.Anthropic()
+    response = client.messages.create(
+        model="claude-sonnet-4-20250514",
+        max_tokens=256,
+        messages=[{"role": "user", "content": PROMPT}],
+    )
+
+    rule_str = response.content[0].text.strip()
+
+
+A typical response looks like:
+
+.. code:: text
+
+    student_in_dept(X,Y)<-0 major_in(X,Z),in_department(Z,Y)
+
+Validating the Rule
+-------------------
+The rule is passed through ``pr.Rule()`` to confirm it is syntactically valid 
+before loading it into the reasoner. If invalid, the script exits immediately.
+
+.. code:: python
+
+    import pyreason as pr
+
+    try:
+        pr.Rule(rule_str)
+        print(f"[VALID] {rule_str}")
+    except Exception as e:
+        sys.exit(f"[INVALID] {rule_str}\nError: {e}")
+
+Running inference
+-----------------
+Load the valid rule into PyReason with ``infer_edges=True`` so that new edges 
+are created when the rule fires between currently unconnected nodes.
+
+.. code:: python
+
+    pr.settings.verbose = False
+    pr.load_graph(g)
+    pr.add_rule(pr.Rule(rule_str, name="student_in_dept_rule", infer_edges=True))
+
+    interpretation = pr.reason(timesteps=2)
+
+    print("\nInferred student-department relationships:")
+    for df in pr.filter_and_sort_edges(interpretation, ["student_in_dept"]):
+        if not df.empty:
+            print(df.to_string(index=False))
+
+Expected output:
+
+.. code:: text
+
+    Inferred student-department relationships:
+                component   student_in_dept
+    0   (alice, math_dept)      [1.0, 1.0]
+    1   (bob,   math_dept)      [1.0, 1.0]
+    2     (mary,  cs_dept)      [1.0, 1.0]
+
+
+Cross-LLM Consistency
+---------------------
+The same prompt was tested against Claude, GPT-4, and Gemini through their 
+web interfaces. All three produced the same valid rule:
+
+.. code:: text
+
+    Claude:  student_in_dept(X,Y)<-0 major_in(X,Z),in_department(Z,Y)
+    GPT-4:   student_in_dept(X,Y)<-0 major_in(X,Z),in_department(Z,Y)
+    Gemini:  student_in_dept(X,Y)<-0 major_in(X,Z),in_department(Z,Y)
+
+This demonstrates that a well-constrained prompt consistently produces identical, 
+valid PyReason rules across different LLMs.

docs/source/tutorials/load_rules_facts_from_file.rst

@@ -0,0 +1,192 @@
+Load Rules and Facts From File
+==================================
+
+Introduction
+------------
+Loading facts and rules from files is crucial for practical PyReason usage. 
+It provides scalability for large rule sets, reusability across projects, 
+and allows non-programmers to edit domain knowledge without touching Python code.
+
+In this tutorial, we will focus on four functions that load facts and rules 
+from CSV or JSON files: ``add_fact_from_csv``, ``add_fact_from_json``, 
+``add_rule_from_csv``, and ``add_rule_from_json``.
+
+.. note:: 
+   Find the full, executable code `here <https://github.com/lab-v2/pyreason/blob/main/examples/load_rules_facts_from_file/load_rules_facts_from_file_ex.py>`_
+
+Graph
+----------------------
+Let's build a simple student-major-department knowledge graph. Alice, Bob, 
+and Mary are students — Alice and Bob enroll in the math major, while Mary 
+enrolls in CS. Each major belongs to a department: math belongs to the math 
+department, and CS belongs to the CS department.
+
+The enrollment relationships are defined as graph edges. The ``in_department``
+and ``scholarship`` relationships are loaded from external files as facts instead.
+
+.. code:: python
+
+    import networkx as nx
+
+    g = nx.DiGraph()
+    g.add_nodes_from(['alice', 'bob', 'mary'])  # students
+    g.add_nodes_from(['math', 'cs'])            # majors
+    g.add_nodes_from(['math_dept', 'cs_dept'])  # departments
+
+    g.add_edge('alice', 'math', enroll=1)
+    g.add_edge('bob', 'math', enroll=1)
+    g.add_edge('mary', 'cs', enroll=1)
+
+
+Load Rules from CSV 
+----------------------
+Rules can be loaded from a CSV file. Each row has four columns:
+``rule_text``, ``name``, ``infer_edges``, ``set_static``.
+
+.. code:: text
+
+    rule_text,name,infer_edges,set_static
+    "under_department(X,Y) <-0 enroll(X,Z), in_department(Z,Y)",under_department_rule,true,false
+    "eligible(X) <-1 under_department(X,Y), scholarship(Y)",eligible_scholarship_rule,false,false
+
+Note: when the rule text contains a comma, wrap the whole field in quotes.
+
+Then load the file using:
+
+.. code:: python
+
+    import pyreason as pr
+    pr.add_rule_from_csv('examples/rules.csv')
+
+Load Rules from JSON
+-----------------------
+Rules can also be loaded from a JSON file. The JSON should be array of objects.
+Example: 
+
+.. code:: text
+
+    [
+        {
+            "rule_text": "under_department(X,Y) <-0 enroll(X,Z), in_department(Z,Y)",
+            "name": "under_department_rule",
+            "infer_edges": true,
+            "set_static": false
+        },    
+        {
+            "rule_text": "eligible(X) <-1 under_department(X,Y), scholarship(Y)",
+            "name": "eligible_scholarship_rule",
+            "infer_edges": false,
+            "set_static": false
+        }
+    ]
+
+Then load the file using:
+
+.. code:: python
+
+    pr.add_rule_from_json('examples/rules.json')
+
+Loading Facts from CSV
+----------------------
+Facts can be loaded from a CSV file. Each row should have up to 5 comma-separated values in this order: ``fact_text, name, start_time, end_time, static``.
+
+.. code:: text
+
+    fact_text,name,start_time,end_time,static
+    scholarship(math_dept),scholarship_math_dept,0,2,False
+    "in_department(math,math_dept)",math_in_math_department,0,2,False
+    "in_department(cs,cs_dept)",cs_in_cs_department,0,2,False
+    
+Note: when the fact text contains a comma, wrap the whole field in quotes.
+
+Then load the file using:
+
+.. code:: python
+
+    pr.add_fact_from_csv('examples/facts.csv')
+
+Loading Facts from JSON
+-----------------------
+Facts can also be loaded from a JSON file. The JSON should be an array of objects. 
+Example:
+
+.. code:: text
+
+    [
+        {
+            "fact_text": "scholarship(math_dept)",
+            "name": "scholarship_math_dept",
+            "start_time": 0,
+            "end_time": 2,
+            "static": false
+        },
+
+        {
+            "fact_text": "in_department(math,math_dept)",
+            "name": "math_in_math_department",
+            "start_time": 0,
+            "end_time": 2,
+            "static": false
+        },
+
+        {
+            "fact_text": "in_department(cs,cs_dept)",
+            "name": "cs_in_cs_department",
+            "start_time": 0,
+            "end_time": 2,
+            "static": false
+        }
+    ]
+
+Then load the file using:
+
+.. code:: python
+
+    pr.add_fact_from_json('examples/facts.json')
+
+
+Running PyReason
+----------------
+
+After loading the graph, rules, and facts using any combination of the 
+four loading functions above, run the reasoning:
+
+.. code:: python
+
+    interpretation = pr.reason(timesteps=2)
+    dataframes = pr.filter_and_sort_nodes(interpretation, ['eligible'])
+    for t, df in enumerate(dataframes):
+        print(f'TIMESTEP - {t}')
+        print(df)
+        print()
+
+Expected Output
+---------------
+.. code::
+
+
+    TIMESTEP - 0
+    Empty DataFrame
+    Columns: [component, eligible]
+    Index: []
+
+    TIMESTEP - 1
+      component    eligible
+    0     alice  [1.0, 1.0]
+    1       bob  [1.0, 1.0]
+
+    TIMESTEP - 2
+      component    eligible
+    0     alice  [1.0, 1.0]
+    1       bob  [1.0, 1.0]
+
+At timestep 1, ``alice`` and ``bob`` become eligible because they are in 
+``math_dept`` and ``math_dept`` has a scholarship. ``mary`` is not eligible 
+because ``cs_dept`` has no scholarship fact.
+
+
+Further Details
+---------------
+
+For a complete description of parameters and advanced features, see the full API reference in `pyreason.py 
+<https://github.com/lab-v2/pyreason/blob/main/pyreason/pyreason.py#L868>`_.