vulcan-core 1.0.0__tar.gz → 1.1.1__tar.gz

{vulcan_core-1.0.0 → vulcan_core-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: vulcan-core
-Version: 1.0.0
+Version: 1.1.1
 Summary: AI-Hybrid Rules Engine for Logical Reasoning.
 License: Apache-2.0
 Keywords: rules,logic,reasoning,ai,artificial intelligence,RAG,LLM
@@ -15,7 +15,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: openai
 Requires-Dist: langchain ; extra == "openai"
 Requires-Dist: langchain-openai ; extra == "openai"
-Requires-Dist: pydantic (>=2.10.6,<2.11.0)
+Requires-Dist: pydantic (>=2.11.1,<2.12.0)
 Project-URL: Documentation, https://latchfield.com/vulcan/docs
 Project-URL: Homepage, https://latchfield.com/vulcan
 Project-URL: Repository, https://github.com/latchfield/vulcan_core
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 <img alt="Vulcan Logo" src="https://latchfield.com/vulcan/assets/images/vulcan-logo.svg" height="100px">
 
 # AI-Hybrid Rules Engine for Logical Reasoning
-![Version](https://img.shields.io/pypi/v/vulcan_core)
+[![Version](https://img.shields.io/pypi/v/vulcan_core)](https://pypi.org/project/vulcan-core/)
 
 Vulcan is an AI-hybrid rules engine designed for advanced automated reasoning. It combines the power of rule-based decision systems with LLMs (Large Language Models) for improved consistency and explainability in AI-powered systems.
 
@@ -59,14 +59,14 @@ Into repeatable, consistent, and explainable rules:
 ```python
 # Use natural language for prediction and data retrieval:
 engine.rule(
-    when(f"Are {Apple.kind} considered good for baking?"),
-    then(Apple(baking=True)),
+    when=condition(f"Are {Apple.kind} considered good for baking?"),
+    then=action(Apple(baking=True)),
 )
 
 # Use computed logic for operations that must be correct:
 engine.rule(
-    when(Apple.baking && lambda: Inventory.apples < 10),
-    then(Order(apples=10)),
+    when=condition(Apple.baking && lambda: Inventory.apples < 10),
+    then=action(Order(apples=10)),
 )
 
 # Intelligent on-demand rule evaluation:

{vulcan_core-1.0.0 → vulcan_core-1.1.1}/README.md

@@ -3,7 +3,7 @@
 <img alt="Vulcan Logo" src="https://latchfield.com/vulcan/assets/images/vulcan-logo.svg" height="100px">
 
 # AI-Hybrid Rules Engine for Logical Reasoning
-![Version](https://img.shields.io/pypi/v/vulcan_core)
+[![Version](https://img.shields.io/pypi/v/vulcan_core)](https://pypi.org/project/vulcan-core/)
 
 Vulcan is an AI-hybrid rules engine designed for advanced automated reasoning. It combines the power of rule-based decision systems with LLMs (Large Language Models) for improved consistency and explainability in AI-powered systems.
 
@@ -36,14 +36,14 @@ Into repeatable, consistent, and explainable rules:
 ```python
 # Use natural language for prediction and data retrieval:
 engine.rule(
-    when(f"Are {Apple.kind} considered good for baking?"),
-    then(Apple(baking=True)),
+    when=condition(f"Are {Apple.kind} considered good for baking?"),
+    then=action(Apple(baking=True)),
 )
 
 # Use computed logic for operations that must be correct:
 engine.rule(
-    when(Apple.baking && lambda: Inventory.apples < 10),
-    then(Order(apples=10)),
+    when=condition(Apple.baking && lambda: Inventory.apples < 10),
+    then=action(Order(apples=10)),
 )
 
 # Intelligent on-demand rule evaluation:

{vulcan_core-1.0.0 → vulcan_core-1.1.1}/pyproject.toml

@@ -20,7 +20,7 @@ requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
-version = "1.0.0" # Update manually, or use plugin
+version = "1.1.1" # Update manually, or use plugin
 packages = [{ include = "vulcan_core", from="src" }]
 requires-poetry = "~2.1.1"
 classifiers = [
@@ -80,10 +80,13 @@ branch = true # Could be an issue if true for native decoration: https://github.
 #poetry-plugin-up = "0.9.0"
 
 [tool.poetry.dependencies]
-pydantic = "~2.10.6"
+pydantic = "~2.11.1"
 langchain = { version = "~0.3.20", optional = true } 
 langchain-openai = { version = "~0.3.9", optional = true }
 
+[tool.poetry.extras]
+openai = ["langchain", "langchain-openai"]
+
 [project.optional-dependencies]
 openai = ["langchain", "langchain-openai"]
 

{vulcan_core-1.0.0 → vulcan_core-1.1.1}/src/vulcan_core/ast_utils.py

@@ -24,7 +24,7 @@ class ContractError(Exception):
 
 class ScopeAccessError(ContractError):
     """Raised when a callable attempts to access instances not passed as parameters or when decorated functions attempt
-    a toccess class attributes instead of parameter instance attributes ."""
+    to access class attributes instead of parameter instance attributes."""
 
 
 class NotAFactError(ContractError):
@@ -152,16 +152,35 @@ class ASTProcessor[T: Callable]:
             raise ASTProcessingError(msg)
 
         # The source includes the entire line of code (e.g., assignment and condition() call)
-        # We need to parse parentheses to extract just the lambda expression, handling any
-        # nested parentheses in the lambda's body correctly
+        # We need to extract just the lambda expression, handling nested structures correctly
         source = self.source[lambda_start:]
+
+        # Track depth of various brackets to ensure we don't split inside valid nested structures apart from trailing
+        # arguments within the condition() call
         paren_level = 0
+        bracket_level = 0
+        brace_level = 0
+
         for i, char in enumerate(source):
             if char == "(":
                 paren_level += 1
-            elif char == ")" and paren_level > 0:
-                paren_level -= 1
-            elif char == ")" and paren_level == 0:
+            elif char == ")":
+                if paren_level > 0:
+                    paren_level -= 1
+                elif paren_level == 0:  # End of expression in a function call
+                    return source[:i]
+            elif char == "[":
+                bracket_level += 1
+            elif char == "]":
+                if bracket_level > 0:
+                    bracket_level -= 1
+            elif char == "{":
+                brace_level += 1
+            elif char == "}":
+                if brace_level > 0:
+                    brace_level -= 1
+            # Only consider comma as a separator when not inside any brackets
+            elif char == "," and paren_level == 0 and bracket_level == 0 and brace_level == 0:
                 return source[:i]
 
         return source

{vulcan_core-1.0.0 → vulcan_core-1.1.1}/src/vulcan_core/conditions.py

@@ -8,11 +8,11 @@ import re
 from abc import abstractmethod
 from dataclasses import dataclass, field
 from enum import Enum, auto
+from functools import lru_cache
 from string import Formatter
 from typing import TYPE_CHECKING
 
 from langchain.prompts import ChatPromptTemplate
-from langchain_openai import ChatOpenAI
 from pydantic import BaseModel, Field
 
 from vulcan_core.actions import ASTProcessor
@@ -22,11 +22,16 @@ if TYPE_CHECKING:  # pragma: no cover - not used at runtime
     from langchain_core.language_models import BaseChatModel
     from langchain_core.runnables import RunnableSerializable
 
+import importlib.util
+import logging
+
+logger = logging.getLogger(__name__)
+
 
 @dataclass(frozen=True, slots=True)
 class Expression(DeclaresFacts):
     """
-    Abstract base class for defining deferred logical expressions. It captures the assosciation of logic with Facts so
+    Abstract base class for defining deferred logical expressions. It captures the association of logic with Facts so
     that upon a Fact update, the logical expression can be selectively evaluated. It also provides a set of logical
     operators for combining conditions, resulting in a new CompoundCondition.
     """
@@ -58,7 +63,7 @@ class Expression(DeclaresFacts):
 @dataclass(frozen=True, slots=True)
 class Condition(FactHandler[ConditionCallable, bool], Expression):
     """
-    A Condition is a container to defer logical epxressions against a supplied Fact. The expression can be inverted
+    A Condition is a container to defer logical expressions against a supplied Fact. The expression can be inverted
     using the `~` operator. Conditions also support the '&',  '|', and '^' operators for combinatorial logic.
 
     Attributes:
@@ -182,6 +187,7 @@ class LiteralFormatter(Formatter):
 @dataclass(frozen=True, slots=True)
 class AICondition(Condition):
     chain: RunnableSerializable
+    model: BaseChatModel
     system_template: str
     inquiry_template: str
     func: None = field(init=False, default=None)
@@ -238,13 +244,23 @@ def ai_condition(model: BaseChatModel, inquiry: str) -> AICondition:
     )
     structured_model = model.with_structured_output(BooleanDecision)
     chain = prompt_template | structured_model
-    return AICondition(chain=chain, system_template=system, inquiry_template=inquiry, facts=facts)
+    return AICondition(chain=chain, model=model, system_template=system, inquiry_template=inquiry, facts=facts)
 
 
-default_model = ChatOpenAI(model="gpt-4o-mini", temperature=0, max_tokens=100)  # type: ignore[call-arg] - pyright can't see the args for some reason
+@lru_cache(maxsize=1)
+def _detect_default_model() -> BaseChatModel:
+    # TODO: Expand this to detect other providers
+    if importlib.util.find_spec("langchain_openai"):
+        from langchain_openai import ChatOpenAI
+
+        logger.debug("Using OpenAI as the default LLM model provider.")
+        return ChatOpenAI(model="gpt-4o-mini", temperature=0, max_tokens=100)  # type: ignore[call-arg] - pyright can't see the args for some reason
+    else:
+        msg = "Unable to import a default LLM provider. Please install `vulcan_core` with the approriate extras package or specify your custom model explicitly."
+        raise ImportError(msg)
 
 
-def condition(func: ConditionCallable | str) -> Condition:
+def condition(func: ConditionCallable | str, model: BaseChatModel | None  = None) -> Condition:
     """
     Creates a Condition object from a lambda or function. It performs limited static analysis of the code to ensure
     proper usage and discover the facts/attributes accessed by the condition. This allows the rule engine to track
@@ -284,10 +300,14 @@ def condition(func: ConditionCallable | str) -> Condition:
     """
 
     if not isinstance(func, str):
+        # Logic condition assumed, ignore kwargs
         processed = ASTProcessor[ConditionCallable](func, condition, bool)
         return Condition(processed.facts, processed.func)
     else:
-        return ai_condition(default_model, func)
+        # AI condition assumed
+        if not model:
+            model = _detect_default_model()
+        return ai_condition(model, func)
 
 
 # TODO: Create a convenience function for creating OnFactChanged conditions

{vulcan_core-1.0.0 → vulcan_core-1.1.1}/src/vulcan_core/engine.py

@@ -9,6 +9,7 @@ from types import MappingProxyType
 from typing import TYPE_CHECKING
 from uuid import UUID, uuid4
 
+from vulcan_core.ast_utils import NotAFactError
 from vulcan_core.models import DeclaresFacts, Fact
 
 if TYPE_CHECKING:  # pragma: no cover - not used at runtime
@@ -104,6 +105,10 @@ class RuleEngine:
 
         if isinstance(fact, partial):
             fact_name = fact.func.__name__
+            fact_class = fact.func
+            if not issubclass(fact_class, Fact):  # type: ignore
+                raise NotAFactError(fact_class)
+
             if fact_name in self._facts:
                 self._facts[fact_name] |= fact
             else:
@@ -113,19 +118,24 @@ class RuleEngine:
                     msg = f"Fact '{fact_name}' is missing and lacks sufficient defaults to create from partial: {fact}"
                     raise InternalStateError(msg) from err
         else:
+            fact_class = type(fact)
+            if not issubclass(fact_class, Fact):
+                raise NotAFactError(fact_class)
+
             self._facts[type(fact).__name__] = fact
 
-    def rule[T: Fact](self, *, name: str | None = None, when: Expression, then: Action, inverse: Action | None = None):
+    def rule[T: Fact](self, *, name: str | None = None, when: Expression, then: Action, inverse: Action | None = None) -> None:
         """
         Convenience method for adding a rule to the rule engine.
 
         Args:
-          name (Optional[str]): The name of the rule. Defaults to None.
-          when (Expression): The condition that triggers the rule.
-          then (Action): The action to be executed when the condition is met.
-          inverse (Optional[Action]): The action to be executed when the condition is not met. Defaults to None.
+            name (Optional[str]): The name of the rule. Defaults to None.
+            when (Expression): The condition that triggers the rule.
+            then (Action): The action to be executed when the condition is met.
+            inverse (Optional[Action]): The action to be executed when the condition is not met. Defaults to None.
 
-        Returns: None
+        Returns:
+            None
         """
         rule = Rule(name, when, then, inverse)
 

{vulcan_core-1.0.0 → vulcan_core-1.1.1}/src/vulcan_core/models.py

@@ -120,7 +120,7 @@ class FactMetaclass(type):
 
 class Fact(ImmutableAttrAsDict, metaclass=FactMetaclass):
     """
-    An abstract class that must be used define rule engine fact schemas and instantiate data into working memory. Facts
+    An abstract class that must be used to define rule engine fact schemas and instantiate data into working memory. Facts
     may be combined with partial facts of the same type using the `|` operator. This is useful for Actions that only
     need to update a portion of working memory.
 
@@ -133,8 +133,16 @@ class Fact(ImmutableAttrAsDict, metaclass=FactMetaclass):
         lefthand operand is created with the partial Fact's keywords applied.
         """
         if isinstance(other, Fact):
+            if type(self) is not type(other):
+                msg = f"Union operator disallowed for types {type(self).__name__} and {type(other).__name__}"
+                raise TypeError(msg)
+
             return other  # type: ignore
         else:
+            if type(self) is not other.func:
+                msg = f"Union operator disallowed for types {type(self).__name__} and {other.func}"
+                raise TypeError(msg)
+
             new_fact = copy(self)
             for kw, value in other.keywords.items():
                 object.__setattr__(new_fact, kw, value)
@@ -258,3 +266,6 @@ class RetrieverAdapter(Similarity):
 
     def __len__(self) -> int:
         raise NotImplementedError
+
+    def __str__(self) -> str:
+        return f"RetrieverAdapter(search_type={self.store.search_type})"

{vulcan_core-1.0.0 → vulcan_core-1.1.1}/src/vulcan_core/util.py

@@ -11,7 +11,7 @@ from typing import Any, NoReturn
 
 @dataclass(frozen=True)
 class WithContext:
-    """Applys a context manager as a decorator.
+    """Applies a context manager as a decorator.
 
     @WithContext(suppress(Exception))
         def foo():