vulcan-core 1.2.1__py3-none-any.whl

vulcan_core/util.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2025 Latchfield Technologies http://latchfield.com
+
+import functools
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, NoReturn
+
+
+@dataclass(frozen=True)
+class WithContext:
+    """Applies a context manager as a decorator.
+
+    @WithContext(suppress(Exception))
+        def foo():
+            raise Exception("Some Exception")
+    """
+
+    context: AbstractContextManager
+
+    def __call__(self, func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            with self.context:
+                return func(*args, **kwargs)
+
+        return wrapper
+
+
+def not_implemented(func) -> Callable:
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs) -> NoReturn:
+        msg = f"{func.__name__} is not implemented."
+        raise NotImplementedError(msg)
+
+    return wrapper
+
+
+def is_private(key: str) -> bool:
+    return key.startswith("_")
+
+
+class AttrDict(dict):
+    def validate(self, key: str) -> str:
+        if is_private(key):
+            msg = f"Access denied to private attribute: {key}"
+            raise KeyError(msg)
+
+        if key not in self.__annotations__:
+            raise KeyError(key)
+
+        return key
+
+    def __init__(self):
+        if type(self) is AttrDict:
+            msg = f"{AttrDict.__name__} is an abstract class that can not be directly instantiated."
+            raise TypeError(msg)
+
+    def __getitem__(self, key: str) -> Any:
+        try:
+            return getattr(self, self.validate(key))
+        except KeyError:
+            if hasattr(self, "__missing__"):
+                return self.__missing__(key)  # type: ignore
+            else:
+                raise
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        setattr(self, self.validate(key), value)
+
+    def __iter__(self) -> Iterator[str]:
+        return (key for key in self.__annotations__ if not is_private(key))
+
+    def __reversed__(self) -> Iterator[str]:
+        return reversed(list(self))
+
+    def __len__(self) -> int:
+        return sum(1 for _ in self)
+
+    def __contains__(self, key: str) -> bool:
+        return hasattr(self, self.validate(key))
+
+    def __or__(self, other: dict) -> dict:
+        return dict(self) | other
+
+    def __repr__(self) -> str:
+        return repr(dict(self))
+
+    def keys(self) -> list[str]:
+        return list(self)
+
+    def values(self) -> list[Any]:
+        return [getattr(self, key) for key in self]
+
+    def items(self) -> list[tuple[str, Any]]:
+        return [(key, getattr(self, key)) for key in self]
+
+    def get(self, key: str, default: Any = None):
+        return getattr(self, self.validate(key), default)
+
+    def setdefault(self, key: str, default: Any = None) -> Any:
+        if key not in self:
+            self[key] = default
+        return self[key]
+
+    @not_implemented
+    def __delitem__(self, key: str) -> NoReturn: ...
+
+    @not_implemented
+    def __ior__(self, other: dict[str, Any]) -> NoReturn: ...
+
+    @not_implemented
+    def clear(self) -> NoReturn: ...
+
+    @not_implemented
+    def copy(self) -> NoReturn: ...
+
+    @not_implemented
+    def pop(self, key: str, defaul: Any = None) -> NoReturn: ...
+
+    @not_implemented
+    def popitem(self) -> NoReturn: ...
+
+    @not_implemented
+    def update(self, *args, **kwargs) -> NoReturn: ...

vulcan_core-1.2.1.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: vulcan-core
+Version: 1.2.1
+Summary: AI-Hybrid Rules Engine for Logical Reasoning.
+Keywords: rules,logic,reasoning,ai,artificial intelligence,RAG,LLM
+License-Expression: Apache-2.0
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: OS Independent
+Requires-Dist: pyyaml>=6.0.2,<7.0.0
+Requires-Dist: pydantic>=2.11.7,<3.0.0
+Requires-Dist: langchain==0.3.*
+Requires-Dist: langchain-openai==0.3.* ; extra == 'openai'
+Requires-Python: >=3.12, <4.0
+Project-URL: homepage, https://latchfield.com/vulcan
+Project-URL: repository, https://github.com/latchfield/vulcan-core
+Project-URL: documentation, https://latchfield.com/vulcan/docs
+Provides-Extra: openai
+Description-Content-Type: text/markdown
+
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- Copyright 2026 Latchfield Technologies http://latchfield.com -->
+<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)](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.
+
+Learn more about Vulcan at [https://latchfield.com/vulcan](https://latchfield.com/vulcan), or jump in with:
+
+```bash
+uv add vulcan-core
+# or
+poetry add vulcan-core
+# or
+pip install vulcan-core
+```
+
+To gain your bearings, read the documentation for guides and API reference: [https://latchfield.com/vulcan/docs](https://latchfield.com/vulcan/docs).
+
+## Why use Vulcan?
+Vulcan strives to improve AI reliability and explainability by explicitly separating computational logic from LLM prediction through declarative rules and microprompting. Vulcan provides developers with a toolkit to create, manage, and execute rules with seamless integration with LLMs and vector databases.
+
+### Features:
+* **AI-Hybrid Rules** - Combine deterministic logic with LLMs and vector databases
+* **Transparent Decision-Making** - Full explainability of how decisions are made
+* **Developer-Friendly API** - Intuitive interfaces for rule creation and management
+* **Platform Flexibility** - Works across various environments and integrates with existing tools
+
+### Simple Example:
+Turn your lengthy unpredictable prompts:
+
+> As a bakery, I want to buy 10 apples if I have less than 10 in inventory, but only if my supplier has apples used for baking in stock. Given I have 9 apples, and my supplier has "Honeycrisp", how many apples should I order?
+
+Into repeatable, consistent, and explainable rules:
+
+```python
+# Use natural language for prediction and data retrieval:
+engine.rule(
+    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=condition(lambda: Apple.baking and Inventory.apples < 10),
+    then=action(Order(apples=10)),
+)
+
+# Intelligent on-demand rule evaluation:
+engine.fact(Inventory(apples=9))
+engine.fact(Apple(kind="Honeycrisp"))
+```
+
+## Get Involved!
+We welcome contributions from the community to help make Vulcan even better:
+
+* **Contribute Code** - Check out the [contribution guidelines](https://github.com/latchfield/vulcan/blob/main/CONTRIBUTING.md) for information on how to submit pull requests
+* **Report Issues** - Found a bug or have a feature request? Open an issue on our [GitHub repository](https://github.com/latchfield/vulcan-core/issues/)
+* **Join the Community** - Connect with other Vulcan users and developers on [GitHub Discussions](https://github.com/latchfield/vulcan-core/discussions)
+
+## Additional Resources
+Learn more about Vulcan:
+
+* [Core Concepts](https://latchfield.com/vulcan/docs/concepts) - Understand the fundamental principles of Vulcan
+* [Guides & Tutorials](https://latchfield.com/vulcan/docs/guides/quick-start/) - Step-by-step instructions for common use cases
+* [API Reference](https://latchfield.com/vulcan/docs/) - Detailed information about the Vulcan API

vulcan_core-1.2.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+vulcan_core/__init__.py,sha256=pjCnmbMjrsp672WXRQeOV0aSKUEoA_mj0o7q_ouMWs8,1057
+vulcan_core/actions.py,sha256=JeX71MOsNww234vFFJAPTY0kCz-1AhVVZFyrVArKwno,1009
+vulcan_core/ast_utils.py,sha256=bxeouX1_KXZyODKTca49ATLwykswOOwHc0scHPnmUrs,21073
+vulcan_core/conditions.py,sha256=jGr83f3ve6hesltWbkMRHQoeg7wxx_GOyMNYxjomRho,18794
+vulcan_core/engine.py,sha256=W2ki0zR5NuCcxKrM8ii_1uABFAXczIM5sWUNxTJu6dY,11386
+vulcan_core/models.py,sha256=XzeKih2WzKB6Ql_EvAeuVqulrBOmK_Of-0JivATCXaI,8972
+vulcan_core/reporting.py,sha256=p7s5YaGchXdpOHmFLlCpdGppjvWHME5r7iW9DJvPaMQ,22660
+vulcan_core/util.py,sha256=Uq5uWhrfWd8fNv6IeeTFZRGeLBAECPZUx63UjbbSMrA,3420
+vulcan_core-1.2.1.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+vulcan_core-1.2.1.dist-info/METADATA,sha256=dCQdeOwCJCb9BIYBjRdCSKFb6bNXqkGT7OBuQzoZxbc,4273
+vulcan_core-1.2.1.dist-info/RECORD,,

vulcan_core-1.2.1.dist-info/WHEEL

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