Add fact parser validation, tests, and bulk fact loading with tests

Makefile

@@ -85,7 +85,7 @@ test-api: ## Run only API tests (tests/api_tests)
 
 test-jit: ## Run only JIT-disabled tests (tests/unit/disable_jit)
 	@echo "$(BOLD)$(BLUE)Running JIT-disabled tests...$(RESET)"
-	$(RUN_TESTS) --suite don_disable_jit
+	$(RUN_TESTS) --suite dont_disable_jit
 
 test-no-jit: ## Run only JIT-enabled tests (tests/unit/dont_disable_jit)
 	@echo "$(BOLD)$(BLUE)Running JIT-enabled tests...$(RESET)"

pyreason/pyreason.py

@@ -1,6 +1,7 @@
 # This is the file that will be imported when "import pyreason" is called. All content will be run automatically
 # ruff: noqa: F401 (Ignore Pyreason import * for public api)
 import importlib
+import json
 import networkx as nx
 import numba
 import time
@@ -648,6 +649,159 @@ def add_fact(pyreason_fact: Fact) -> None:
         __edge_facts.append(f)
 
 
+def add_fact_in_bulk(json_path: str, raise_errors = True) -> None:
+    """Load multiple facts from a JSON file.
+
+    The JSON should be an array of objects, where each object represents a Fact with these fields:
+    - fact_text (required): The fact in text format, e.g., 'pred(x,y) : [0.2, 1]' or 'pred(x) : True'
+    - name (optional): The name of the fact
+    - start_time (optional): The timestep at which this fact becomes active (default: 0)
+    - end_time (optional): The last timestep this fact is active (default: 0)
+    - static (optional): Whether the fact is static for the entire program (default: false)
+
+    Example JSON format:
+    ```json
+    [
+        {
+            "fact_text": "Viewed(Zach)",
+            "name": "seen-fact-zach",
+            "start_time": 0,
+            "end_time": 3,
+            "static": false
+        },
+        {
+            "fact_text": "Viewed(Justin)",
+            "name": "seen-fact-justin",
+            "start_time": 0,
+            "end_time": 3,
+            "static": false
+        },
+        {
+            "fact_text": "Viewed(Michelle)",
+            "start_time": 1,
+            "end_time": 3
+        }
+    ]
+    ```
+
+    :param json_path: Path to the JSON file containing facts
+    :type json_path: str
+    :return: None
+    :raises FileNotFoundError: If the JSON file doesn't exist
+    :raises ValueError: If fact parsing fails or JSON format is invalid
+    """
+    try:
+        with open(json_path, 'r') as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        raise FileNotFoundError(f"JSON file not found: {json_path}")
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON format in file {json_path}: {e}")
+    except Exception as e:
+        raise ValueError(f"Error reading JSON file {json_path}: {e}")
+
+    if not isinstance(data, list):
+        raise ValueError(f"JSON file must contain an array of fact objects, got {type(data).__name__}")
+
+    if len(data) == 0:
+        warnings.warn(f"JSON file {json_path} contains an empty array, no facts loaded")
+        return
+
+    # Track loaded facts for reporting
+    loaded_count = 0
+    error_count = 0
+
+    # Process each fact object
+    for idx, fact_obj in enumerate(data):
+        try:
+            if not isinstance(fact_obj, dict):
+                if raise_errors:
+                    raise ValueError(f"Item {idx}: Expected object, got {type(fact_obj).__name__}")
+                warnings.warn(f"Item {idx}: Expected object, got {type(fact_obj).__name__}, skipping item")
+                error_count += 1
+                continue
+
+            # Extract fact_text (required)
+            fact_text = fact_obj.get('fact_text')
+            if not fact_text or not str(fact_text).strip():
+                if raise_errors:
+                    raise ValueError(f"Item {idx}: Missing required 'fact_text'")
+                warnings.warn(f"Item {idx}: Missing required 'fact_text', skipping item")
+                error_count += 1
+                continue
+
+            fact_text = str(fact_text).strip()
+
+            # Extract optional parameters with defaults
+            name = fact_obj.get('name')
+            if name is not None:
+                name = str(name).strip() if str(name).strip() else None
+
+            # Parse start_time
+            try:
+                start_time = fact_obj.get('start_time', 0)
+                start_time = int(start_time) if start_time is not None else 0
+            except (ValueError, TypeError):
+                if raise_errors:
+                    raise ValueError(f"Item {idx}: Invalid start_time '{fact_obj.get('start_time')}'") from None
+                warnings.warn(f"Item {idx}: Invalid start_time '{fact_obj.get('start_time')}', using default value")
+                start_time = 0
+
+            # Parse end_time
+            try:
+                end_time = fact_obj.get('end_time', 0)
+                end_time = int(end_time) if end_time is not None else 0
+            except (ValueError, TypeError):
+                if raise_errors:
+                    raise ValueError(f"Item {idx}: Invalid end_time '{fact_obj.get('end_time')}'") from None
+                warnings.warn(f"Item {idx}: Invalid end_time '{fact_obj.get('end_time')}', using default value")
+                end_time = 0
+
+            # Parse static as boolean
+            static = fact_obj.get('static', False)
+            if isinstance(static, bool):
+                pass  # Already a boolean
+            elif isinstance(static, str):
+                static_str = static.strip().lower()
+                if static_str in ('true', '1', 'yes', 't', 'y'):
+                    static = True
+                elif static_str in ('false', '0', 'no', 'f', 'n'):
+                    static = False
+                else:
+                    if raise_errors:
+                        raise ValueError(f"Item {idx}: Invalid static value '{static}'")
+                    warnings.warn(f"Item {idx}: Invalid static value '{static}', using default value")
+                    static = False
+            elif isinstance(static, (int, float)):
+                static = bool(static)
+            else:
+                if raise_errors:
+                    raise ValueError(f"Item {idx}: Invalid static value type '{type(static).__name__}'")
+                warnings.warn(f"Item {idx}: Invalid static value type '{type(static).__name__}', using default value")
+                static = False
+
+            # Create and add the fact
+            fact = Fact(fact_text=fact_text, name=name, start_time=start_time, end_time=end_time, static=static)
+            add_fact(fact)
+            loaded_count += 1
+
+        except ValueError as e:
+            if raise_errors:
+                raise ValueError(f"Item {idx}: Failed to parse fact - {e}") from e
+            error_count += 1
+            warnings.warn(f"Item {idx}: Failed to parse fact - {e}")
+        except Exception as e:
+            if raise_errors:
+                raise Exception(f"Item {idx}: Unexpected error - {e}") from e
+            error_count += 1
+            warnings.warn(f"Item {idx}: Unexpected error - {e}")
+
+    # Report results
+    print(f"Loaded {loaded_count} facts from {json_path}")
+    if error_count > 0:
+        print(f"Failed to load {error_count} facts due to errors")
+
+
 def add_annotation_function(function: Callable) -> None:
     """Function to add annotation functions to PyReason. The added functions can be used in rules
 

pyreason/scripts/facts/fact.py

@@ -6,7 +6,45 @@ class Fact:
     def __init__(self, fact_text: str, name: str = None, start_time: int = 0, end_time: int = 0, static: bool = False):
         """Define a PyReason fact that can be loaded into the program using `pr.add_fact()`
 
-        :param fact_text: The fact in text format. Example: `'pred(x,y) : [0.2, 1]'` or `'pred(x,y) : True'`
+        :param fact_text: The fact in text format. Must follow these formatting rules:
+
+            **Format:** `predicate(component)` or `predicate(component):bound`
+
+            **Predicate rules:**
+            - Must start with a letter (a-z, A-Z) or underscore (_)
+            - Can contain letters, digits (0-9), and underscores
+            - Cannot start with a digit
+            - Examples: `viewed`, `has_access`, `_internal`, `pred123`
+
+            **Component rules:**
+            - Node fact: Single component `predicate(node1)`
+            - Edge fact: Two components separated by comma `predicate(node1,node2)`
+            - Cannot contain parentheses, colons, or nested structures
+
+            **Bound rules:**
+            - If omitted, defaults to True (1.0)
+            - Boolean: `True` or `False` (case-insensitive)
+            - Interval: `[lower,upper]` where both values are in range [0, 1]
+            - Negation: `~predicate(component)` (equivalent to False, cannot be combined with explicit bound)
+
+            **Valid examples:**
+            - `'viewed(Zach)'` - defaults to True
+            - `'viewed(Zach):True'` - explicit True
+            - `'viewed(Zach):False'` - explicit False
+            - `'~viewed(Zach)'` - negation (False)
+            - `'viewed(Zach):[0.5,0.8]'` - interval bound
+            - `'connected(Alice,Bob)'` - edge fact
+            - `'connected(Alice,Bob):[0.7,0.9]'` - edge fact with interval
+            - `'~pred(node):[0.2,0.8]'` - negation with explicit bound
+            NOTE: Negating an explicit bound will round the upper and lower bounds to 10 decimal places before taking the negation
+            This is needed to avoid floating point precision errors.
+
+            **Invalid examples:**
+            - `'123pred(node)'` - predicate starts with digit
+            - `'pred@name(node)'` - invalid characters in predicate
+            - `'pred(node1,node2,node3)'` - more than 2 components
+            - `'pred(node):[1.5,2.0]'` - values out of range [0,1]
+
         :type fact_text: str
         :param name: The name of the fact. This will appear in the trace so that you know when it was applied
         :type name: str