django-datalog 0.1.0__py3-none-any.whl

django_datalog/__init__.py

@@ -0,0 +1,9 @@
+# Package for Datalog-like fact & inference engine
+
+__version__ = "0.1.0"
+
+default_app_config = "django_datalog.apps.DjangoDatalogConfig"
+
+# Note: Core functionality (Fact, Var, query, etc.) is available in django_datalog.models
+# Import them directly from there after Django is configured:
+#   from django_datalog.models import Fact, Var, query, store_facts, retract_facts

django_datalog/apps.py

@@ -0,0 +1,9 @@
+from django.apps import AppConfig
+
+
+class DjangoDatalogConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "django_datalog"
+
+    def ready(self):
+        pass

django_datalog/facts.py

@@ -0,0 +1,164 @@
+"""
+Fact system for djdatalog - handles fact definitions, storage, and retrieval.
+"""
+
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+import uuid6
+from django.db import models
+
+
+class FactModel(models.Model):
+    """Abstract base model for storing datalog facts."""
+
+    id = models.UUIDField(primary_key=True, default=uuid6.uuid7, editable=False)
+
+    class Meta:
+        abstract = True
+        unique_together = (("subject", "object"),)
+
+
+@dataclass(eq=False)  # Disable auto-generated __eq__
+class Fact:
+    """Base class for all datalog facts."""
+
+    subject: Any
+    object: Any
+    _django_model: ClassVar[type[models.Model]]
+
+    def __hash__(self):
+        """Make facts hashable for use in sets."""
+        # Use PKs for Django models, actual values for other types
+        subject_key = getattr(self.subject, "pk", self.subject)
+        object_key = getattr(self.object, "pk", self.object)
+        return hash((type(self), subject_key, object_key))
+
+    def __eq__(self, other):
+        """Compare facts for equality."""
+        if not isinstance(other, type(self)):
+            return False
+
+        # Use PKs for Django models, actual values for other types
+        subject_key = getattr(self.subject, "pk", self.subject)
+        other_subject_key = getattr(other.subject, "pk", other.subject)
+        object_key = getattr(self.object, "pk", self.object)
+        other_object_key = getattr(other.object, "pk", other.object)
+
+        return subject_key == other_subject_key and object_key == other_object_key
+
+    def __init_subclass__(cls, **kwargs):
+        """Automatically generate Django models for fact storage and apply dataclass decorator."""
+        super().__init_subclass__(**kwargs)
+
+        # Apply dataclass decorator with unsafe_hash=True to the subclass
+        cls = dataclass(unsafe_hash=True)(cls)
+
+        cls._django_model = cls._create_django_model()
+
+    @classmethod
+    def _create_django_model(cls):
+        """Dynamically create a Django model for this fact type."""
+        import sys
+        from typing import get_type_hints
+
+        from django.db import models
+
+        # Generate model name
+        model_name = f"{cls.__name__}Storage"
+
+        # Get type annotations from the class
+        try:
+            type_hints = get_type_hints(cls)
+        except (NameError, AttributeError):
+            # Fallback to raw annotations if get_type_hints fails
+            type_hints = getattr(cls, "__annotations__", {})
+
+        if "subject" not in type_hints or "object" not in type_hints:
+            raise ValueError(f"Fact {cls.__name__} must have subject and object type annotations")
+
+        # Extract Django model types from Union annotations
+        subject_model = cls._extract_django_model_from_annotation(type_hints["subject"])
+        object_model = cls._extract_django_model_from_annotation(type_hints["object"])
+
+        if not subject_model or not object_model:
+            raise ValueError(
+                f"Could not extract Django model types from {cls.__name__} annotations"
+            )
+
+        # Create Django model fields
+        model_fields = {
+            "subject": models.ForeignKey(subject_model, on_delete=models.CASCADE, related_name="+"),
+            "object": models.ForeignKey(object_model, on_delete=models.CASCADE, related_name="+"),
+            "__module__": cls.__module__,
+        }
+
+        # Create the Django model class
+        django_model = type(model_name, (FactModel,), model_fields)
+
+        # Inject the model into the fact's module so Django can find it
+        fact_module = sys.modules[cls.__module__]
+        setattr(fact_module, model_name, django_model)
+
+        return django_model
+
+    @classmethod
+    def _extract_django_model_from_annotation(cls, type_annotation):
+        """Extract Django model type from Union annotation like 'User | Var'."""
+        if hasattr(type_annotation, "__args__"):
+            # Handle Union types (User | Var)
+            for arg_type in type_annotation.__args__:
+                if hasattr(arg_type, "_meta") and hasattr(arg_type._meta, "app_label"):
+                    return arg_type
+        elif hasattr(type_annotation, "_meta") and hasattr(type_annotation._meta, "app_label"):
+            # Direct Django model reference
+            return type_annotation
+        return None
+
+
+def store_facts(*facts: Fact) -> None:
+    """Store facts in the database."""
+    if not facts:
+        return
+
+    # Group facts by type for batch operations
+    facts_by_type = {}
+    for fact in facts:
+        fact_type = type(fact)
+        if fact_type not in facts_by_type:
+            facts_by_type[fact_type] = []
+        facts_by_type[fact_type].append(fact)
+
+    # Bulk create for each fact type
+    for fact_type, fact_list in facts_by_type.items():
+        django_model = fact_type._django_model
+        model_instances = []
+
+        for fact in fact_list:
+            # Store Django model instances directly in ForeignKey fields
+            model_instances.append(django_model(subject=fact.subject, object=fact.object))
+
+        # Use ignore_conflicts to handle duplicates
+        django_model.objects.bulk_create(model_instances, ignore_conflicts=True)
+
+
+def retract_facts(*facts: Fact) -> None:
+    """Remove facts from the database."""
+    if not facts:
+        return
+
+    # Group facts by type for batch operations
+    facts_by_type = {}
+    for fact in facts:
+        fact_type = type(fact)
+        if fact_type not in facts_by_type:
+            facts_by_type[fact_type] = []
+        facts_by_type[fact_type].append(fact)
+
+    # Batch delete for each fact type
+    for fact_type, fact_list in facts_by_type.items():
+        django_model = fact_type._django_model
+
+        for fact in fact_list:
+            # Delete using Django model instances directly
+            django_model.objects.filter(subject=fact.subject, object=fact.object).delete()

django_datalog/models.py

@@ -0,0 +1,30 @@
+"""
+Datalog system for Django - main module with public API.
+
+This module provides the public interface for django-datalog, importing from
+specialized modules for facts, queries, and rules.
+"""
+
+# Public API imports
+from django_datalog.facts import Fact, retract_facts, store_facts
+from django_datalog.query import Var, _fact_to_django_query, _prefix_q_object, query
+from django_datalog.rules import Rule, get_rules, rule
+
+# django_datalog is a library package - storage models should be defined by consuming applications
+
+# Re-export for backward compatibility and public API
+__all__ = [
+    # Core classes
+    "Fact",
+    "Var",
+    "Rule",
+    # Core functions
+    "query",
+    "store_facts",
+    "retract_facts",
+    "rule",
+    "get_rules",
+    # Internal functions (exposed for testing)
+    "_prefix_q_object",
+    "_fact_to_django_query",
+]

django_datalog/query.py

@@ -0,0 +1,394 @@
+"""
+Query system for djdatalog - handles querying facts with inference and optimization.
+"""
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any
+
+from django.db.models import Q
+
+from django_datalog.facts import Fact
+
+
+@dataclass(slots=True)
+class Var:
+    """Variable placeholder for datalog queries."""
+
+    name: str
+    where: Any = None  # Q object for additional constraints
+
+    def __repr__(self):
+        if self.where is not None:
+            return f"Var({self.name!r}, where={self.where!r})"
+        return f"Var({self.name!r})"
+
+
+def query(*fact_patterns: Fact, hydrate: bool = True) -> Iterator[dict[str, Any]]:
+    """
+    Query facts from the database and apply inference rules.
+
+    Args:
+        *fact_patterns: One or more fact patterns to match as a conjunction
+        hydrate: If True (default), returns full model instances. If False, returns PKs only.
+
+    Yields:
+        Dictionary mapping variable names to their values (models or PKs based on hydrate)
+    """
+    # Get all available facts (both stored and inferred)
+    all_facts = _get_all_facts_with_inference()
+
+    # Get the conjunction results using both stored and inferred facts
+    pk_results = _satisfy_conjunction_with_facts(list(fact_patterns), {}, all_facts)
+
+    if hydrate:
+        # Collect all results first to batch hydration
+        pk_results_list = list(pk_results)
+        # Hydrate PKs to model instances
+        yield from _hydrate_results(pk_results_list, list(fact_patterns))
+    else:
+        # Return PKs directly without hydration
+        yield from pk_results
+
+
+def _get_all_facts_with_inference() -> list[Fact]:
+    """Get all facts including both stored facts and inferred facts from rules."""
+    from django_datalog.rules import apply_rules
+
+    # Get all stored facts from the database
+    stored_facts = _get_all_stored_facts()
+
+    # Apply inference rules to derive new facts
+    all_facts = apply_rules(stored_facts)
+
+    return all_facts
+
+
+def _get_all_stored_facts() -> list[Fact]:
+    """Get all facts currently stored in the database."""
+    from django_datalog.rules import get_rules
+
+    stored_facts = []
+
+    # Get all fact types used in rules to know what to load
+    fact_types = set()
+    for rule in get_rules():
+        fact_types.add(type(rule.head))
+        for condition in rule.body:
+            fact_types.add(type(condition))
+
+    # Load facts of all relevant types from the database
+    for fact_type in fact_types:
+        try:
+            django_model = fact_type._django_model
+            # Get subject and object type from fact type annotations
+            subject_type, object_type = _get_fact_field_types(fact_type)
+
+            # Load facts using select_related for efficient loading
+            for row in django_model.objects.select_related("subject", "object").all():
+                try:
+                    # Access the related Django model instances directly
+                    fact = fact_type(subject=row.subject, object=row.object)
+                    stored_facts.append(fact)
+                except Exception:
+                    # Skip facts that can't be loaded
+                    continue
+        except Exception:
+            # Skip fact types that can't be loaded
+            continue
+
+    return stored_facts
+
+
+def _get_fact_field_types(fact_type):
+    """Get the Django model types for subject and object fields of a fact type."""
+    # Use the cached model types from the Fact class
+    if hasattr(fact_type, "_model_types_cache"):
+        cache = fact_type._model_types_cache
+        return cache.get("subject"), cache.get("object")
+
+    # Fallback: extract from type annotations
+    from dataclasses import fields
+
+    fact_fields = fields(fact_type)
+    subject_field = next((f for f in fact_fields if f.name == "subject"), None)
+    object_field = next((f for f in fact_fields if f.name == "object"), None)
+
+    if not subject_field or not object_field:
+        raise ValueError(f"Fact type {fact_type} missing subject or object field")
+
+    # Extract Django model types from Union annotations (like Person | Var)
+    subject_type = _extract_model_type_from_annotation(subject_field.type)
+    object_type = _extract_model_type_from_annotation(object_field.type)
+
+    return subject_type, object_type
+
+
+def _extract_model_type_from_annotation(type_annotation):
+    """Extract Django model type from type annotation like 'Person | Var'."""
+    if hasattr(type_annotation, "__args__"):
+        # Handle Union types (Person | Var)
+        for arg_type in type_annotation.__args__:
+            if hasattr(arg_type, "_meta") and hasattr(arg_type._meta, "app_label"):
+                # This looks like a Django model
+                return arg_type
+    elif hasattr(type_annotation, "_meta") and hasattr(type_annotation._meta, "app_label"):
+        # Direct Django model reference
+        return type_annotation
+
+    return None
+
+
+def _satisfy_conjunction_with_facts(
+    conditions, bindings, all_facts: list[Fact]
+) -> Iterator[dict[str, Any]]:
+    """Satisfy a conjunction of conditions using the combined set of stored and inferred facts."""
+    if not conditions:
+        yield bindings
+        return
+
+    # Take the first condition
+    condition = conditions[0]
+    remaining = conditions[1:]
+
+    # Query against the complete set of facts (stored + inferred) to avoid duplication
+    for result in _query_against_facts(condition, all_facts):
+        new_bindings = _unify_bindings(bindings, result)
+        if new_bindings is not None:
+            yield from _satisfy_conjunction_with_facts(remaining, new_bindings, all_facts)
+
+
+def _query_against_facts(pattern: Fact, facts: list[Fact]) -> Iterator[dict[str, Any]]:
+    """Query a pattern against a set of in-memory facts."""
+    pattern_type = type(pattern)
+
+    for fact in facts:
+        if type(fact) is pattern_type:
+            # Try to unify the pattern with this fact
+            substitution = _unify_fact_pattern(pattern, fact)
+            if substitution is not None:
+                yield substitution
+
+
+def _unify_fact_pattern(pattern: Fact, concrete_fact: Fact) -> dict[str, Any] | None:
+    """Unify a fact pattern (with variables) against a concrete fact."""
+    substitution = {}
+
+    # Check subject
+    if isinstance(pattern.subject, Var):
+        # Check if subject meets the variable's constraints
+        if pattern.subject.where is not None:
+            if not _check_q_constraint(concrete_fact.subject, pattern.subject.where):
+                return None  # Subject doesn't meet constraints
+
+        substitution[pattern.subject.name] = (
+            concrete_fact.subject.pk
+            if hasattr(concrete_fact.subject, "pk")
+            else concrete_fact.subject
+        )
+    elif pattern.subject != concrete_fact.subject:
+        return None  # Subjects don't match
+
+    # Check object
+    if isinstance(pattern.object, Var):
+        # Check if object meets the variable's constraints
+        if pattern.object.where is not None:
+            if not _check_q_constraint(concrete_fact.object, pattern.object.where):
+                return None  # Object doesn't meet constraints
+
+        var_name = pattern.object.name
+        obj_value = (
+            concrete_fact.object.pk if hasattr(concrete_fact.object, "pk") else concrete_fact.object
+        )
+        # Check for conflicting bindings
+        if var_name in substitution and substitution[var_name] != obj_value:
+            return None
+        substitution[var_name] = obj_value
+    elif pattern.object != concrete_fact.object:
+        return None  # Objects don't match
+
+    return substitution
+
+
+def _check_q_constraint(model_instance, q_constraint) -> bool:
+    """Check if a model instance satisfies a Q constraint."""
+    # Convert the Q constraint to a filter and check if the instance matches
+    try:
+        # Create a queryset for this model and apply the constraint
+        queryset = model_instance.__class__.objects.filter(q_constraint)
+        # Check if this specific instance matches the constraint
+        return queryset.filter(pk=model_instance.pk).exists()
+    except Exception:
+        # If there's any error with the constraint check, assume it fails
+        return False
+
+
+def _satisfy_conjunction(conditions, bindings) -> Iterator[dict[str, Any]]:
+    """Satisfy a conjunction of conditions with the given variable bindings."""
+    if not conditions:
+        yield bindings
+        return
+
+    # Take the first condition
+    condition = conditions[0]
+    remaining = conditions[1:]
+
+    # Generate all possible solutions for this condition
+    for result in _query_single_fact(condition):
+        # Try to unify with existing bindings
+        new_bindings = _unify_bindings(bindings, result)
+        if new_bindings is not None:
+            # Recursively solve remaining conditions
+            yield from _satisfy_conjunction(remaining, new_bindings)
+
+
+def _query_single_fact(fact_pattern: Fact) -> Iterator[dict[str, Any]]:
+    """Query a single fact pattern from the database."""
+    # Get the Django model for this fact type
+    fact_class = type(fact_pattern)
+    django_model = fact_class._django_model
+
+    # Convert fact pattern to Django query
+    query_params, q_objects = _fact_to_django_query(fact_pattern)
+
+    # Build the queryset with both filter params and Q objects
+    queryset = django_model.objects.filter(**query_params)
+    for q_obj in q_objects:
+        queryset = queryset.filter(q_obj)
+
+    # Query the database with values() to get PKs
+    for values_dict in queryset.values("subject", "object"):
+        substitution = _django_result_to_substitution(fact_pattern, values_dict)
+        yield substitution
+
+
+def _fact_to_django_query(fact: Fact) -> tuple[dict[str, Any], list[Any]]:
+    """
+    Convert a fact to Django query parameters and Q objects.
+
+    Returns:
+        tuple: (query_params, q_objects) where q_objects are constraints for Vars
+    """
+    query_params = {}
+    q_objects = []
+
+    if not isinstance(fact.subject, Var):
+        # Use Django model instance directly for ForeignKey lookup
+        query_params["subject"] = fact.subject
+    elif fact.subject.where is not None:
+        # Add Q object constraint with subject__ prefix
+        prefixed_q = _prefix_q_object(fact.subject.where, "subject")
+        q_objects.append(prefixed_q)
+
+    if not isinstance(fact.object, Var):
+        # Use Django model instance directly for ForeignKey lookup
+        query_params["object"] = fact.object
+    elif fact.object.where is not None:
+        # Add Q object constraint with object__ prefix
+        prefixed_q = _prefix_q_object(fact.object.where, "object")
+        q_objects.append(prefixed_q)
+
+    return query_params, q_objects
+
+
+def _prefix_q_object(q_obj, prefix: str):
+    """Prefix all field lookups in a Q object with the given prefix."""
+    if hasattr(q_obj, "children"):
+        # Q object with children (AND/OR operations)
+        new_q = Q()
+        new_q.connector = q_obj.connector
+        new_q.negated = q_obj.negated
+
+        for child in q_obj.children:
+            if isinstance(child, tuple):
+                # This is a field lookup: (field_name, value)
+                field_name, value = child
+                new_field_name = f"{prefix}__{field_name}"
+                new_q.children.append((new_field_name, value))
+            else:
+                # This is another Q object - recurse
+                new_q.children.append(_prefix_q_object(child, prefix))
+        return new_q
+    else:
+        # Simple Q object - create a new one with prefixed fields
+        new_q = Q()
+        new_q.connector = q_obj.connector
+        new_q.negated = q_obj.negated
+        for child in q_obj.children:
+            if isinstance(child, tuple):
+                field_name, value = child
+                new_field_name = f"{prefix}__{field_name}"
+                new_q.children.append((new_field_name, value))
+        return new_q
+
+
+def _django_result_to_substitution(fact: Fact, values_dict: dict) -> dict[str, Any]:
+    """Convert Django query result to variable substitution."""
+    substitution = {}
+    if isinstance(fact.subject, Var):
+        # values_dict contains PKs from ForeignKey fields
+        substitution[fact.subject.name] = values_dict["subject"]
+    if isinstance(fact.object, Var):
+        # values_dict contains PKs from ForeignKey fields
+        substitution[fact.object.name] = values_dict["object"]
+    return substitution
+
+
+def _unify_bindings(existing: dict, new: dict) -> dict[str, Any] | None:
+    """Try to unify two sets of variable bindings."""
+    result = existing.copy()
+    for var, value in new.items():
+        if var in result:
+            if result[var] != value:
+                return None  # Conflict
+        else:
+            result[var] = value
+    return result
+
+
+def _hydrate_results(pk_results: list[dict], fact_patterns: list[Fact]) -> Iterator[dict[str, Any]]:
+    """Hydrate PK results to full model instances."""
+    if not pk_results:
+        return
+
+    # Collect all PKs that need hydration by variable name and model type
+    var_to_model_type = {}
+    pks_to_hydrate = {}
+
+    # First pass: discover what models each variable represents
+    for fact_pattern in fact_patterns:
+        for field_name in ["subject", "object"]:
+            field_val = getattr(fact_pattern, field_name)
+            if isinstance(field_val, Var):
+                var_name = field_val.name
+                # Extract model type from fact pattern using the helper function
+                model_type = _extract_model_type_from_annotation(
+                    fact_pattern.__dataclass_fields__[field_name].type
+                )
+                if model_type and var_name not in var_to_model_type:
+                    var_to_model_type[var_name] = model_type
+                    pks_to_hydrate[var_name] = set()
+
+    # Second pass: collect all PKs for each variable
+    for result in pk_results:
+        for var_name, pk in result.items():
+            if var_name in pks_to_hydrate:
+                pks_to_hydrate[var_name].add(pk)
+
+    # Batch load models by type
+    model_cache = {}
+    for var_name, model_type in var_to_model_type.items():
+        if var_name in pks_to_hydrate:
+            pk_list = list(pks_to_hydrate[var_name])
+            models = model_type.objects.in_bulk(pk_list)
+            model_cache[var_name] = models
+
+    # Hydrate results
+    for result in pk_results:
+        hydrated_result = {}
+        for var_name, pk in result.items():
+            if var_name in model_cache and pk in model_cache[var_name]:
+                hydrated_result[var_name] = model_cache[var_name][pk]
+            else:
+                hydrated_result[var_name] = pk  # Keep as PK if can't hydrate
+        yield hydrated_result

django_datalog/rules.py

@@ -0,0 +1,209 @@
+"""
+Rule system for djdatalog - handles inference rules and rule evaluation.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from django_datalog.facts import Fact
+
+
+@dataclass
+class Rule:
+    """Represents a datalog inference rule."""
+
+    head: Fact
+    body: list[Any]  # List of facts or nested lists (for OR conditions)
+
+    def __repr__(self):
+        return f"Rule({self.head} :- {self.body})"
+
+
+# Global rule registry
+_rules: list[Rule] = []
+
+
+def rule(head: Fact, *body) -> None:
+    """
+    Define an inference rule.
+
+    Args:
+        head: The fact that can be inferred
+        *body: Conditions that must be true (supports nested lists for OR conditions)
+
+    Example:
+        rule(
+            GrandparentOf(Var("grandparent"), Var("grandchild")),
+            ParentOf(Var("grandparent"), Var("parent")),
+            ParentOf(Var("parent"), Var("grandchild"))
+        )
+    """
+    new_rule = Rule(head=head, body=list(body))
+    _rules.append(new_rule)
+
+
+def get_rules() -> list[Rule]:
+    """Get all registered rules."""
+    return _rules.copy()
+
+
+def apply_rules(base_facts: list[Fact]) -> list[Fact]:
+    """
+    Apply inference rules to derive new facts from base facts.
+
+    Args:
+        base_facts: Set of known facts
+
+    Returns:
+        Set of all facts (base + inferred)
+    """
+    all_facts = base_facts[:]
+    changed = True
+    max_iterations = 100  # Prevent infinite loops
+    iterations = 0
+
+    while changed and iterations < max_iterations:
+        changed = False
+        iterations += 1
+
+        for rule_obj in _rules:
+            # Try to apply this rule
+            new_facts = _apply_single_rule(rule_obj, all_facts)
+            for new_fact in new_facts:
+                if new_fact not in all_facts:
+                    all_facts.append(new_fact)
+                    changed = True
+
+    return all_facts
+
+
+def _apply_single_rule(rule_obj: Rule, known_facts: list[Fact]) -> list[Fact]:
+    """Apply a single rule to known facts to derive new facts."""
+    new_facts = []
+
+    # known_facts is already a list
+    fact_list = known_facts
+
+    # Try to find all possible variable bindings that satisfy the rule body
+    bindings_list = _find_all_bindings(rule_obj.body, fact_list)
+
+    # For each valid binding, instantiate the rule head to create a new fact
+    for bindings in bindings_list:
+        try:
+            new_fact = _instantiate_fact(rule_obj.head, bindings)
+            if new_fact and new_fact not in known_facts and new_fact not in new_facts:
+                new_facts.append(new_fact)
+        except Exception:
+            # Skip invalid instantiations
+            continue
+
+    return new_facts
+
+
+def _find_all_bindings(conditions: list[Any], known_facts: list[Fact]) -> list[dict[str, Any]]:
+    """Find all variable bindings that satisfy all conditions."""
+    if not conditions:
+        return [{}]  # Empty binding for empty conditions
+
+    all_bindings = []
+
+    # Start with the first condition
+    first_condition = conditions[0]
+    remaining_conditions = conditions[1:]
+
+    # Find all bindings for the first condition
+    first_bindings = _find_bindings_for_condition(first_condition, known_facts)
+
+    # For each binding of the first condition, try to extend it with remaining conditions
+    for binding in first_bindings:
+        if remaining_conditions:
+            # Recursively find bindings for remaining conditions
+            extended_bindings = _find_all_bindings(remaining_conditions, known_facts)
+            for ext_binding in extended_bindings:
+                # Merge bindings, checking for conflicts
+                merged = _merge_bindings(binding, ext_binding)
+                if merged is not None:
+                    all_bindings.append(merged)
+        else:
+            # No more conditions, this binding is complete
+            all_bindings.append(binding)
+
+    return all_bindings
+
+
+def _find_bindings_for_condition(condition: Any, known_facts: list[Fact]) -> list[dict[str, Any]]:
+    """Find all variable bindings that match a single condition against known facts."""
+    bindings_list = []
+
+    # Check each known fact to see if it matches the condition
+    for fact in known_facts:
+        if type(fact) is type(condition):  # Same fact type
+            binding = _unify_facts(condition, fact)
+            if binding is not None:
+                bindings_list.append(binding)
+
+    return bindings_list
+
+
+def _unify_facts(pattern_fact: Fact, concrete_fact: Fact) -> dict[str, Any] | None:
+    """Unify a pattern fact (with variables) against a concrete fact."""
+    from django_datalog.query import Var
+
+    bindings = {}
+
+    # Check subject
+    if isinstance(pattern_fact.subject, Var):
+        bindings[pattern_fact.subject.name] = concrete_fact.subject
+    elif pattern_fact.subject != concrete_fact.subject:
+        return None  # Subjects don't match
+
+    # Check object
+    if isinstance(pattern_fact.object, Var):
+        var_name = pattern_fact.object.name
+        # Check for conflicting bindings
+        if var_name in bindings and bindings[var_name] != concrete_fact.object:
+            return None
+        bindings[var_name] = concrete_fact.object
+    elif pattern_fact.object != concrete_fact.object:
+        return None  # Objects don't match
+
+    return bindings
+
+
+def _merge_bindings(binding1: dict[str, Any], binding2: dict[str, Any]) -> dict[str, Any] | None:
+    """Merge two variable bindings, checking for conflicts."""
+    merged = binding1.copy()
+
+    for var_name, value in binding2.items():
+        if var_name in merged:
+            if merged[var_name] != value:
+                return None  # Conflict - same variable bound to different values
+        else:
+            merged[var_name] = value
+
+    return merged
+
+
+def _instantiate_fact(pattern_fact: Fact, bindings: dict[str, Any]) -> Fact | None:
+    """Create a concrete fact by substituting variables with their bindings."""
+    from django_datalog.query import Var
+
+    # Substitute subject
+    if isinstance(pattern_fact.subject, Var):
+        if pattern_fact.subject.name not in bindings:
+            return None  # Unbound variable
+        subject = bindings[pattern_fact.subject.name]
+    else:
+        subject = pattern_fact.subject
+
+    # Substitute object
+    if isinstance(pattern_fact.object, Var):
+        if pattern_fact.object.name not in bindings:
+            return None  # Unbound variable
+        obj = bindings[pattern_fact.object.name]
+    else:
+        obj = pattern_fact.object
+
+    # Create new fact instance of the same type
+    fact_class = type(pattern_fact)
+    return fact_class(subject=subject, object=obj)

django_datalog-0.1.0.dist-info/METADATA

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: django-datalog
+Version: 0.1.0
+Summary: Django Datalog - Logic programming and inference engine for Django applications
+Project-URL: Homepage, https://github.com/edelvalle/django-datalog
+Project-URL: Documentation, https://django-datalog.readthedocs.io/
+Project-URL: Repository, https://github.com/edelvalle/django-datalog.git
+Project-URL: Issues, https://github.com/edelvalle/django-datalog/issues
+Project-URL: Changelog, https://github.com/edelvalle/django-datalog/blob/main/CHANGELOG.md
+Author-email: Eddy Ernesto del Valle Pino <eddy@edelvalle.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: datalog,django,facts,inference-engine,logic-programming,query,rules
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: django>=5
+Requires-Dist: uuid6>=2024.1.12
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.12; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-django>=4.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest-django>=4.5; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# django-datalog
+
+Django Datalog - A logic programming and inference engine for Django applications.
+
+## Features
+
+- **Fact-based data modeling**: Define facts as Python classes that integrate seamlessly with Django models
+- **Logic programming**: Write inference rules using a familiar Python syntax  
+- **Query system**: Query facts and derived conclusions with variable binding
+- **Q object constraints**: Filter query results using Django Q objects for powerful filtering
+- **Performance optimized**: Intelligent query reordering and batch hydration for optimal performance
+- **Django integration**: Seamless integration with existing Django models and ORM
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install django-datalog
+```
+
+Add `django_datalog` to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ... your other apps
+    'django_datalog',
+]
+```
+
+Run migrations to create the datalog fact tables:
+
+```bash
+python manage.py migrate
+```
+
+### Basic Example: Company Employee Management
+
+Let's start with a realistic business scenario - managing employees in a company:
+
+```python
+# models.py
+from django.db import models
+from django.contrib.auth.models import User
+from django_datalog.models import Fact, Var
+
+class Company(models.Model):
+    name = models.CharField(max_length=100)
+    
+class Department(models.Model):
+    name = models.CharField(max_length=100)
+    company = models.ForeignKey(Company, on_delete=models.CASCADE)
+
+class Employee(models.Model):
+    user = models.OneToOneField(User, on_delete=models.CASCADE)
+    company = models.ForeignKey(Company, on_delete=models.CASCADE)
+    department = models.ForeignKey(Department, on_delete=models.CASCADE)
+    is_manager = models.BooleanField(default=False)
+
+# Define Facts - Note: No @dataclass decorator needed!
+class WorksFor(Fact):
+    """Employee works for a company."""
+    subject: Employee | Var  # Employee
+    object: Company | Var    # Company
+
+class MemberOf(Fact):
+    """Employee is member of a department."""
+    subject: Employee | Var    # Employee
+    object: Department | Var   # Department
+
+class ColleaguesOf(Fact):
+    """Two employees are colleagues (inferred from working at same company)."""
+    subject: Employee | Var  # Employee 1
+    object: Employee | Var   # Employee 2
+
+class TeamMates(Fact):
+    """Two employees are teammates (inferred from same department)."""
+    subject: Employee | Var  # Employee 1
+    object: Employee | Var   # Employee 2
+```
+
+```python
+# rules.py - Define inference logic
+from django_datalog.rules import rule
+from django_datalog.models import Var
+from .models import WorksFor, MemberOf, ColleaguesOf, TeamMates
+
+# Rule: Employees are colleagues if they work for the same company
+rule(
+    ColleaguesOf(Var("emp1"), Var("emp2")),
+    WorksFor(Var("emp1"), Var("company")),
+    WorksFor(Var("emp2"), Var("company")),
+)
+
+# Rule: Employees are teammates if they work in the same department  
+rule(
+    TeamMates(Var("emp1"), Var("emp2")),
+    MemberOf(Var("emp1"), Var("department")),
+    MemberOf(Var("emp2"), Var("department")),
+)
+```
+
+```python
+# Usage in views.py or management commands
+from django_datalog.models import query, store_facts
+from django.db.models import Q
+
+# Store some facts
+tech_corp = Company.objects.create(name="Tech Corp")
+engineering = Department.objects.create(name="Engineering", company=tech_corp)
+
+alice_user = User.objects.create(username="alice")
+bob_user = User.objects.create(username="bob")
+
+alice = Employee.objects.create(user=alice_user, company=tech_corp, department=engineering, is_manager=True)
+bob = Employee.objects.create(user=bob_user, company=tech_corp, department=engineering)
+
+# Store facts about work relationships
+store_facts(
+    WorksFor(subject=alice, object=tech_corp),
+    WorksFor(subject=bob, object=tech_corp),
+    MemberOf(subject=alice, object=engineering),
+    MemberOf(subject=bob, object=engineering),
+)
+
+# Query: Find all of Alice's colleagues (inferred automatically!)
+colleagues = list(query(ColleaguesOf(alice, Var("colleague"))))
+for result in colleagues:
+    colleague = result["colleague"]
+    print(f"Alice works with {colleague.user.username}")
+
+# Query: Find all teammates in engineering
+teammates = list(query(TeamMates(Var("emp1"), Var("emp2"))))
+for result in teammates:
+    emp1, emp2 = result["emp1"], result["emp2"]
+    print(f"{emp1.user.username} and {emp2.user.username} are teammates")
+
+# Query with constraints: Find managers who work for Tech Corp
+managers = list(query(WorksFor(Var("employee", where=Q(is_manager=True)), tech_corp)))
+for result in managers:
+    manager = result["employee"]
+    print(f"{manager.user.username} is a manager at {tech_corp.name}")
+```
+
+## Advanced Features
+
+### Q Object Constraints
+
+Use Django Q objects to add powerful filtering to your queries:
+
+```python
+from django.db.models import Q
+
+# Find senior employees (with complex constraints)
+senior_employees = query(
+    WorksFor(
+        Var("employee", where=Q(user__date_joined__year__lt=2020) & Q(is_manager=True)), 
+        Var("company")
+    )
+)
+
+# Find employees in specific departments
+engineering_employees = query(
+    MemberOf(Var("employee"), Var("dept", where=Q(name__icontains="engineering")))
+)
+```
+
+### Hydration Control
+
+Control whether to fetch full model instances or just PKs for better performance:
+
+```python
+# Get full objects (default) - includes all related data
+results = list(query(WorksFor(Var("employee"), tech_corp), hydrate=True))
+employee = results[0]["employee"]
+print(employee.user.username)  # Full Employee object with related User
+
+# Get PKs only (better performance for large datasets)  
+results = list(query(WorksFor(Var("employee"), tech_corp), hydrate=False))
+employee_id = results[0]["employee"]  # Just the employee ID (integer)
+```
+
+### Family Relationships Example
+
+Django-datalog also works great for modeling family relationships:
+
+```python
+class Person(models.Model):
+    name = models.CharField(max_length=100)
+    age = models.IntegerField()
+
+class ParentOf(Fact):
+    """Person is parent of another person."""
+    subject: Person | Var  # Parent
+    object: Person | Var   # Child
+
+class GrandparentOf(Fact):
+    """Person is grandparent of another person (inferred)."""
+    subject: Person | Var  # Grandparent  
+    object: Person | Var   # Grandchild
+
+class SiblingOf(Fact):
+    """Person is sibling of another person (inferred)."""
+    subject: Person | Var  # Sibling 1
+    object: Person | Var   # Sibling 2
+
+# Define family rules
+rule(
+    GrandparentOf(Var("grandparent"), Var("grandchild")),
+    ParentOf(Var("grandparent"), Var("parent")),
+    ParentOf(Var("parent"), Var("grandchild")),
+)
+
+rule(
+    SiblingOf(Var("person1"), Var("person2")),
+    ParentOf(Var("parent"), Var("person1")),
+    ParentOf(Var("parent"), Var("person2")),
+)
+
+# Usage
+john = Person.objects.create(name="John", age=65)
+alice = Person.objects.create(name="Alice", age=40) 
+bob = Person.objects.create(name="Bob", age=15)
+
+store_facts(
+    ParentOf(subject=john, object=alice),
+    ParentOf(subject=alice, object=bob)
+)
+
+# Query: Find Bob's grandparents (automatically inferred!)
+grandparents = list(query(GrandparentOf(Var("grandparent"), bob)))
+print(f"Bob's grandparent: {grandparents[0]['grandparent'].name}")  # John
+```
+
+## Key Benefits
+
+- **No complex SQL**: Express complex relationship logic in simple Python rules
+- **Automatic inference**: New facts are derived automatically from your rules
+- **Performance optimized**: Query reordering and batch loading for optimal performance  
+- **Django native**: Works seamlessly with your existing Django models and admin
+- **Type safe**: Full type hints and IDE support with modern Python syntax
+
+## Fact Retraction
+
+Remove facts when relationships change:
+
+```python
+from django_datalog.models import retract_facts
+
+# Remove a work relationship
+retract_facts(WorksFor(subject=alice, object=tech_corp))
+
+# The system will automatically update inferred facts like ColleaguesOf
+```
+
+## Requirements
+
+- Python 3.10+
+- Django 5.0+
+
+## Documentation
+
+For detailed examples, API reference, and advanced usage, see the [repository documentation](https://github.com/edelvalle/django-datalog) and [CHANGELOG.md](CHANGELOG.md).
+
+## Contributing
+
+We welcome contributions! Please see our repository on [GitHub](https://github.com/edelvalle/django-datalog) for details.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

django_datalog-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+django_datalog/__init__.py,sha256=h27hUO5klSo0l8YsGys_NiNhErkDueb-wmaV9762Y4k,374
+django_datalog/apps.py,sha256=ConQakBjws19HPiCCnzpteivsaygVMFCb4Sdfhy5Awg,194
+django_datalog/facts.py,sha256=am7GwmlVg9M7tQL78OkS8BAvIZQw9BxZrsuJc1_ug40,5902
+django_datalog/models.py,sha256=68UJkhbed-FZs-kZY_6JOqn1QbKBRk9FZJMxeV7L77o,848
+django_datalog/query.py,sha256=oyXD8j-V88R_Wbq_If3uxRIXtw0_DAsBfZMqdvJ-cDU,14785
+django_datalog/rules.py,sha256=hKKkmQV_T8P--4KIvJkXEwmA6Q4PriZyohRdowIvO1I,6626
+django_datalog/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_datalog-0.1.0.dist-info/METADATA,sha256=Ip4z9uSsvtDd8rUQXgnTsgmniPsnMsFGWrHcmrGg_N4,10805
+django_datalog-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+django_datalog-0.1.0.dist-info/licenses/LICENSE,sha256=GTVQl3vH6ht70wJXKC0yMT8CmXKHxv_YyO_utAgm7EA,1065
+django_datalog-0.1.0.dist-info/RECORD,,

django_datalog-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_datalog-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.