Vulcan

https://latchfield.com/vulcan/docs
Admin
Vulcan is a forward-chaining inference engine written in Python that seamlessly integrates...
Tokens:35,231
Snippets:294
Trust Score:4.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Vulcan with OpenAI Support (Poetry)

Source: https://latchfield.com/vulcan/docs/guides/quick-start_q=

Adds Vulcan with OpenAI support as a dependency to your project using Poetry. This prepares your project for AI rule implementation.

```bash
poetry add "vulcan-core[openai]"
```

--------------------------------

### Install Vulcan Core with Pip or Poetry

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Installs the core Vulcan package using either pip or poetry. This is the first step to integrating Vulcan into your project.

```bash
pip install vulcan-core
```

```bash
poetry add vulcan-core
```

--------------------------------

### Install Vulcan with OpenAI Support (Pip)

Source: https://latchfield.com/vulcan/docs/guides/quick-start_q=

Installs Vulcan with the necessary dependencies for OpenAI integration using pip. This enables the use of AI-powered rules.

```bash
pip install "vulcan-core[openai]"
```

--------------------------------

### Install Vulcan Core with Poetry

Source: https://latchfield.com/vulcan/docs/guides/quick-start_q=

Adds the core Vulcan package as a dependency to your project using Poetry. This integrates Vulcan into your project's dependency management.

```bash
poetry add vulcan-core
```

--------------------------------

### Enable Explainability Reporting with Vulcan (Python & YAML)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Shows how to enable explainability reporting by calling engine.evaluate(audit=True) and then generating a YAML report using engine.yaml_report(). Includes example Python code and the resulting YAML output.

```python
from functools import partial

engine = RuleEngine()

engine.rule(
    name="Order more apples if delicious",
    when=condition(f"Are {Inventory.apple_kind} considered delicious by most people?"),
    then=action(partial(QueuedOrder, apples=50)),
)

engine.fact(Inventory(apples=5, apple_kind="fuji"))

engine.evaluate(audit=True)

engine.yaml_report()
```

```yaml
report:
  iterations:
  - id: 0
    timestamp: '2025-07-14T16:07:14.742891Z'
    elapsed: 2.441
    matches:
    - rule: 205a7ab3:Order more apples if delicious
      timestamp: '2025-07-14T16:07:14.742920Z'
      elapsed: 2.441
      evaluation: True = Are {Inventory.apple_kind|fuji|} considered delicious by most people?
      consequences:
        QueuedOrder.apples: 50
      rationale: Fuji apples are generally considered delicious by most people due to their sweetness and crisp texture.
```

--------------------------------

### Install Vulcan Core with Pip

Source: https://latchfield.com/vulcan/docs/guides/quick-start_q=

Installs the core Vulcan package using pip. This is the most straightforward way to add Vulcan to your Python project.

```bash
pip install vulcan-core
```

--------------------------------

### Enable and Generate Explainability Report (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start_q=

Demonstrates how to enable explainability reporting by passing `audit=True` to `engine.evaluate()` and then generating a YAML report using `engine.yaml_report()`. The report provides details on rule evaluation, consequences, and AI rationale.

```Python
from functools import partial

engine = RuleEngine()

engine.rule(
    name="Order more apples if delicious",
    when=condition(f"Are {Inventory.apple_kind} considered delicious by most people?"),
    then=action(partial(QueuedOrder, apples=50)),
)

engine.fact(Inventory(apples=5, apple_kind="fuji"))

engine.evaluate(audit=True)

engine.yaml_report()
```

--------------------------------

### Create Chroma Vector Store with LangChain Adapter (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Shows how to set up a Chroma Vector Store using LangChain, including embedding documents and creating a retriever adapter for Vulcan. This is used to handle similarity searches for facts.

```python
from langchain.schema import Document
from langchain_chroma import Chroma
from langchain_openai import OpenAIEmbeddings
from vulcan_core.models import RetrieverAdapter

headlines = [
    "Potato prices are on a decline due to a surplus in the market.",
    "Brussel sprout futures are trading at a premium.",
    "Fuji apples are in short supply due to a poor harvest.",
]
documents = [Document(value) for value in headlines]

# Create a store that returns the topmost similar document
store = Chroma(embedding_function=OpenAIEmbeddings(model="text-embedding-3-small"))
retriever = store.as_retriever(search_kwargs={"k": 1})
retriever.add_documents(documents)

adapter = RetrieverAdapter(store=retriever)
```

--------------------------------

### Example Explainability Report (YAML)

Source: https://latchfield.com/vulcan/docs/guides/quick-start_q=

A sample YAML output from `engine.yaml_report()`, showing the details of a rule evaluation, including the rule name, timestamp, elapsed time, evaluation result, consequences, and the AI's rationale for the decision.

```YAML
report:
  iterations:
  - id: 0
    timestamp: '2025-07-14T16:07:14.742891Z'
    elapsed: 2.441
    matches:
    - rule: 205a7ab3:Order more apples if delicious
      timestamp: '2025-07-14T16:07:14.742920Z'
      elapsed: 2.441
      evaluation: True = Are {Inventory.apple_kind|fuji|} considered delicious by most people?
      consequences:
        QueuedOrder.apples: 50
      rationale: Fuji apples are generally considered delicious by most people due to their sweetness and crisp texture.
```

--------------------------------

### Instantiate Fact, Add Rule, and Evaluate Engine (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Illustrates how to instantiate a Fact with a similarity adapter, add it to the Vulcan engine, define a rule referencing the similarity attribute, and evaluate the engine. Includes the expected text output.

```python
news_fact = News(headlines=adapter)
engine.fact(news_fact)

# Define a rule to check if the news headline is relevant to apples
engine.rule(
    when=condition(
        f"Is there any indication in {News.headlines} that {Inventory.apple_kind} apple prices may increase?"
    ),
    then=action(QueuedOrder(apples=100)),
)

# Evaluate the engine
engine.evaluate()

# Print the facts to see the result
print(engine.facts)
```

```text
mappingproxy({Inventory: Inventory(apples=5, apple_kind='fuji'),
              News: News(headlines=RetrieverAdapter(search_type=similarity)),
              QueuedOrder: QueuedOrder(apples=100)})
```

--------------------------------

### Create Simple Rules with Vulcan (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Defines rules for the Vulcan engine using `condition` and `action`. Rules are evaluated when dependent facts change. This example sets rules for ordering apples based on inventory levels.

```python
from vulcan_core import RuleEngine, action, condition

engine = RuleEngine()

# Rule to order 10 apples if the inventory is less than or equal to 10
engine.rule(
    when=condition(lambda: Inventory.apples <= 10),  
    then=action(QueuedOrder(apples=10)),  
)

# Rule to order 0 apples if the inventory is greater than 10
engine.rule(
    when=condition(lambda: Inventory.apples > 10),
    then=action(QueuedOrder(apples=0)),
)
```

--------------------------------

### Evaluate Vulcan Rules and Inspect Facts (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Sets initial facts, evaluates the rules engine, and prints the current state of facts. Demonstrates how rules modify facts based on conditions.

```python
engine.fact(Inventory(apples=5))
engine.evaluate()
print(engine.facts)
```

--------------------------------

### Complete Vulcan Model Configuration Example in Python

Source: https://latchfield.com/vulcan/docs/guides/model-configuration

A comprehensive example illustrating the integration of multiple LangChain models (OpenAI) with Vulcan's rule engine. It demonstrates rule-specific and scoped model configurations for advanced use cases.

```python
from functools import partial

from langchain_openai import ChatOpenAI
from vulcan_core import Fact, RuleEngine, action, condition


# Define the fact schema
class Inventory(Fact):
    apples: int
    apple_kind: str


class AppleQualities(Fact):
    delicious: bool = False
    suitable_for_baking: bool = False


class QueuedOrder(Fact):
    apples: int = 0


# Configure the models
gpt_4o = ChatOpenAI(model="gpt-4o", temperature=0, max_tokens=100)
gpt_4o_mini = ChatOpenAI(model="gpt-4o-mini", temperature=0, max_tokens=100)
condition = partial(condition, model=gpt_4o_mini)

# Define the rule set
engine = RuleEngine()

engine.rule(
    when=condition(f"Are {Inventory.apple_kind} considered delicious by most people?", model=gpt_4o),  
    then=action(lambda: partial(AppleQualities, delicious=True)),
)

engine.rule(
    when=condition(f"Are {Inventory.apple_kind} suitable for baking pies?"),  
    then=action(lambda: partial(AppleQualities, suitable_for_baking=True)),
)

engine.rule(
    when=condition(lambda: AppleQualities.delicious and AppleQualities.suitable_for_baking),
    then=action(QueuedOrder(apples=50)),
)

# Add initial facts
engine.fact(Inventory(apples=5, apple_kind="Fuji"))

# Evaluate and print the decision

```

--------------------------------

### Update Facts and Re-evaluate Rules (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Modifies an existing fact and re-evaluates the rules engine to show how Vulcan reacts to changes. This example updates the inventory and observes the change in the `QueuedOrder` fact.

```python
engine.fact(Inventory(apples=15))
engine.evaluate()
print(engine.facts)
```

--------------------------------

### Complete Vulcan Model Configuration Example

Source: https://latchfield.com/vulcan/docs/guides/model-configuration_q=

A comprehensive example showcasing multiple model configurations, including rule-specific and scoped models, within a Vulcan rule engine. It defines facts, configures models, sets up rules, and evaluates initial facts.

```python
from functools import partial

from langchain_openai import ChatOpenAI
from vulcan_core import Fact, RuleEngine, action, condition


# Define the fact schema
class Inventory(Fact):
    apples: int
    apple_kind: str


class AppleQualities(Fact):
    delicious: bool = False
    suitable_for_baking: bool = False


class QueuedOrder(Fact):
    apples: int = 0


# Configure the models
gpt_4o = ChatOpenAI(model="gpt-4o", temperature=0, max_tokens=100)
gpt_4o_mini = ChatOpenAI(model="gpt-4o-mini", temperature=0, max_tokens=100)
condition = partial(condition, model=gpt_4o_mini)

# Define the rule set
engine = RuleEngine()

engine.rule(
    when=condition(f"Are {Inventory.apple_kind} considered delicious by most people?", model=gpt_4o),
    then=action(lambda: partial(AppleQualities, delicious=True)),
)

engine.rule(
    when=condition(f"Are {Inventory.apple_kind} suitable for baking pies?"),
    then=action(lambda: partial(AppleQualities, suitable_for_baking=True)),
)

engine.rule(
    when=condition(lambda: AppleQualities.delicious and AppleQualities.suitable_for_baking),
    then=action(QueuedOrder(apples=50)),
)

# Add initial facts
engine.fact(Inventory(apples=5, apple_kind="Fuji"))

# Evaluate and print the decision

```

--------------------------------

### Create AI Rules with Vulcan and OpenAI (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Defines an AI-powered rule using a natural language condition processed by an LLM (OpenAI in this case). The rule orders apples based on a subjective assessment of apple kind.

```python
class Inventory(Fact):
    apples: int
    apple_kind: str


engine.fact(Inventory(apples=5, apple_kind="fuji"))


# Rule to order 50 apples if the type of apple is delicious
engine.rule(
    when=condition(f"Are {Inventory.apple_kind} considered delicious by most people?"),
    then=action(QueuedOrder(apples=50)),
)

engine.evaluate()
print(engine.facts)
```

--------------------------------

### Install Vulcan with OpenAI Extra

Source: https://latchfield.com/vulcan/docs/guides/model-configuration

Installs the Vulcan core package with the OpenAI extra, enabling the use of OpenAI models. This is a prerequisite for using OpenAI as a model provider.

```bash
pip install "vulcan-core[openai]"
```

```bash
poetry add "vulcan-core[openai]"
```

--------------------------------

### Define Facts for Vulcan Rules (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Declares fact classes that represent the domain for which Vulcan will reason. These facts serve as the data that rules will operate on. Example shows `Inventory` and `QueuedOrder` facts.

```python
from vulcan_core import Fact


class Inventory(Fact):
    apples: int


class QueuedOrder(Fact):
    apples: int = 0
```

--------------------------------

### Vulcan Rule Engine: Iterative Evaluation Example (Python)

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

Demonstrates the iterative evaluation process of the Vulcan rule engine using Python. It defines facts, rules with conditions and actions, and shows how the engine processes them, generating a YAML report detailing each iteration and rule match. This example highlights dependent rule evaluation and fact modification.

```python
class Subtotal(Fact):
    amount: float = 0.0


class Discount(Fact):
    percentage: float = 0.0


class FinalTotal(Fact):
    amount: float = 0.0


engine = RuleEngine()

engine.rule(
    name="Calculate subtotal",
    when=condition(lambda: CartItem.quantity > 0),
    then=action(lambda: partial(Subtotal, amount=CartItem.quantity * CartItem.price_per_item)),
)

engine.rule(
    name="Large order discount",
    when=condition(lambda: Subtotal.amount > 10.0),
    then=action(partial(Discount, percentage=0.10)),
)

engine.rule(
    name="Calculate final total",
    when=condition(lambda: Subtotal.amount > 0 and Discount.percentage >= 0),
    then=action(lambda: partial(FinalTotal, amount=Subtotal.amount * (1 - Discount.percentage))),
)

engine.fact(CartItem(quantity=5))

engine.evaluate(audit=True)
engine.yaml_report()
```

--------------------------------

### Define Actions Using Facts

Source: https://latchfield.com/vulcan/docs/guides/understanding-facts_q=

Provides examples of defining Vulcan actions using Facts. This includes creating actions that apply a full Fact, a partial Fact, or dynamically update a Fact based on existing data in working memory.

```python
from vulcan_core import action, Fact
from functools import partial

class Inventory(Fact):
    apples: int
    oranges: int


act1 = action(Inventory(apples=10, oranges=20))

act2 = action(partial(Inventory, apples=10))

act3 = action(lambda: partial(Inventory, apples=Inventory.apples + 10))
```

--------------------------------

### Vulcan Rule Engine: Rule Evaluation Details Example (Python)

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

Illustrates how Vulcan provides detailed evaluation information for rules that match facts. This Python example defines a rule with a condition and shows the resulting YAML report's 'evaluation' field, explaining how the condition was evaluated with specific fact values and the final boolean outcome. It highlights cases where conditions are not met.

```python
class SpecialHandling(Fact):
    required: bool = False


engine = RuleEngine()

engine.rule(
    name="Special handling for large perishable orders",
    when=condition(lambda: CartItem.quantity > 10 and CartItem.is_perishable),
    then=action(partial(SpecialHandling, required=True)),
)

engine.fact(CartItem(quantity=5, is_perishable=True))

engine.evaluate(audit=True)
engine.yaml_report()
```

--------------------------------

### Showing Rule Consequences and Inverse Actions

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

This example illustrates how the Rule Engine reports consequences, including modifications to fact attributes and the execution of inverse actions when a rule's condition is false. It presents Python code for defining rules with 'then' and 'inverse' actions, and the corresponding YAML report output.

```python
engine = RuleEngine()

engine.rule(  
    name="Age verification",
    when=condition(lambda: Customer.age >= 21),
    then=action(partial(Checkout, age_verification_required=False)),
    inverse=action(partial(Checkout, age_verification_required=True)),
)

engine.rule(
    name="VIP processing",
    when=condition(lambda: TotalCost.amount > 200),
    then=action(partial(Checkout, special_handling_required=True)),
)

engine.fact(Customer(age=19))
engine.fact(TotalCost(amount=45))

engine.evaluate(audit=True)
engine.yaml_report()
```

```yaml
report:
  iterations:
  - id: 0
    timestamp: '2025-07-14T13:21:00.399432Z'
    elapsed: 0.0
    matches:
    - rule: 5c314431:Age verification
      timestamp: '2025-07-14T13:21:00.399444Z'
      elapsed: 0.0
      evaluation: False = (Customer.age|19| >= 21)
      consequences:
        Checkout.age_verification_required: true
    - rule: 7a81de31:VIP processing
      timestamp: '2025-07-14T13:21:00.399534Z'
      elapsed: 0.0
      evaluation: False = (TotalCost.amount|45| > 200)
      consequences: None
```

--------------------------------

### Vulcan Rule Engine: Short-Circuit Evaluation in Python

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

Illustrates Vulcan's short-circuit evaluation for logical expressions. If a condition in an 'or' or 'and' expression evaluates to False, subsequent conditions are not evaluated. This example defines rules with compound conditions and demonstrates how the YAML report reflects short-circuiting, showing evaluated facts for lambdas and '|-|' for unevaluated decorated functions.

```python
class Checkout(Fact):
    payment_approved: bool = False
    special_handling_required: bool = False
    age_verification_required: bool = False


engine = RuleEngine()


@condition
def loyalty_check(customer: Customer) -> bool:
    return len(customer.review_history) > 100


low_total = condition(lambda: TotalCost.amount < 10.0)

engine.rule(
    name="Lambda short circuit evaluation",
    when=condition(lambda: Customer.age >= 21 and TotalCost.amount > 100.0),
    then=action(partial(Checkout, payment_approved=True)),
)

engine.rule(
    name="Compound condition short circuit evaluation",
    when=low_total | loyalty_check,
    then=action(partial(Checkout, special_handling_required=True)),
)

engine.fact(Customer(age=18, review_history="First time customer"))
engine.fact(TotalCost(amount=5.0))

engine.evaluate(audit=True)
engine.yaml_report()
```

--------------------------------

### Vulcan Rule Engine: Lambda vs Decorated Functions in Python

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

Demonstrates the difference in report notation between lambda conditions and decorated functions in Vulcan's rule engine. Lambda conditions are parenthesized, while decorated functions appear as function calls. This example shows how rules are defined, facts are asserted, and the engine evaluates them, generating a YAML report.

```python
class Customer(Fact):
    is_loyalty_member: bool = False
    age: int = 18
    review_history: str = ""


@condition
def qualifies_for_volume_discount(total: TotalCost) -> bool:
    return total.amount > 20.0


engine = RuleEngine()

engine.rule(
    name="Apply volume discount",
    when=qualifies_for_volume_discount,
    then=action(partial(Discount, percentage=0.08)),
    inverse=action(partial(Discount, percentage=0)),
)

engine.rule(
    name="Apply loyalty discount",
    when=condition(lambda: Discount.percentage < 0 and Customer.is_loyalty_member),
    then=action(partial(Discount, percentage=0.05)),
)

engine.fact(CartItem(quantity=5, price_per_item=3.00))
engine.fact(Customer(is_loyalty_member=True))
engine.fact(TotalCost(amount=15.0))

engine.evaluate(audit=True)
engine.yaml_report()
```

--------------------------------

### Define Similarity Attribute on Fact (Python)

Source: https://latchfield.com/vulcan/docs/guides/quick-start

Demonstrates how to define a 'Similarity' attribute on a custom Fact class using Vulcan Core. This allows facts to leverage similarity search for RAG rules.

```python
from vulcan_core import Similarity


class News(Fact):
    headlines: Similarity
```

--------------------------------

### Define a Rule with Conditions and Actions (Python)

Source: https://latchfield.com/vulcan/docs/api/engine

Demonstrates how to define a rule using the 'rule' method of the RuleEngine. This includes specifying a name, a condition ('when'), and actions for both when the condition is met ('then') and when it is not ('inverse').

```python
from vulcan.core.rule_engine import RuleEngine
from vulcan.core.expressions import Expression
from vulcan.core.actions import Action

# Assuming Expression and Action are defined elsewhere
# Example placeholders:
class MockExpression(Expression):
    pass

class MockAction(Action):
    pass

rule_engine = RuleEngine()

# Example usage of the rule method
rule_engine.rule(
    name="MyFirstRule",
    when=MockExpression(),
    then=MockAction(),
    inverse=MockAction()
)
```

--------------------------------

### AST Transformers and Trackers

Source: https://latchfield.com/vulcan/docs/api/AST_Utils_q=

Documentation for classes that transform AST nodes and track lambda function positions.

```APIDOC
## AST Transformers and Trackers

### Classes

#### `AttributeTransformer`
  * **Description**: Transformer to replace static class attribute access with parameterized instances.
  * **Bases**: `NodeTransformer`

#### `LambdaTracker` `dataclass`
  * **Description**: Index entry for tracking the parsing position of lambda functions in source lines.
  * **Attributes**:
    * **`source`** (`str`) - The source code string containing lambda functions
    * **`positions`** (`list[int]`) - Positions where lambda functions are found in the source
    * **`index`** (`int`) - The lambda being parsed within the source string.
    * **`in_use`** (`bool`) - Whether this source is currently being processed or not, making it eligible for cache deletion.
```

--------------------------------

### RetrieverAdapter: Similarity Search with Chroma and OpenAI

Source: https://latchfield.com/vulcan/docs/api/models_q=

Illustrates the usage of RetrieverAdapter for performing similarity searches using the Chroma vector store and OpenAI embeddings. It shows how to check for the existence of a match and retrieve matching content.

```python
from vulcan.models import RetrieverAdapter

# Assuming retriever is an instance of RetrieverAdapter
# if 'some_key' in retriever:
#     results = retriever['some_key']
```

--------------------------------

### Python Fact Instantiation with Keyword Arguments

Source: https://latchfield.com/vulcan/docs/guides/understanding-facts

Demonstrates the correct method for instantiating a Vulcan Fact using keyword arguments. This practice enhances readability and minimizes the risk of errors by explicitly naming each field during instantiation.

```python
class Inventory(Fact):
    apples: int = 0


i = Inventory(apples=15)
```

--------------------------------

### Python: Set Facts and Evaluate Rule Engine

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

This Python snippet demonstrates how to add initial facts to a rule engine, including customer and cart item details. It then proceeds to evaluate the complete checkout process with audit enabled and generates a YAML report.

```python
reviews = "".join([
        "January - Worst company ever.;",
        "February - I got a good deal with a coupon!;",
        "March - Got broken product.",
    ])

engine.fact(Customer(is_loyalty_member=True, age=28, review_history=reviews))
engine.fact(CartItem(quantity=12, price_per_item=4.25, is_perishable=True, category="alcohol"))

# Run the complete checkout process with full explainability
engine.evaluate(audit=True)
engine.yaml_report()
```

--------------------------------

### YAML Report with AI Rationale Output

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports

This YAML snippet represents the output of the `engine.yaml_report()` method when `audit=True` is used in the Python example. It specifically highlights the `rationale` field, which contains the LLM's explanation for the rule evaluation.

```yaml
report:
  iterations:
  - id: 0
    timestamp: '2025-07-14T13:21:01.854969Z'
    elapsed: 1.214
    matches:
    - rule: edfcae78:Customer retention discount
      timestamp: '2025-07-14T13:21:01.855002Z'
      elapsed: 1.214
      evaluation: True = Does the {Customer.review_history} overall sentiment indicate an unhappy customer?
      consequences:
        Discount.percentage: 0.15
      context:
      - Customer.review_history: 'January: Worst company ever.;Feburary: I got a good deal with a coupon!;March: Got broken product.'
      rationale: The review history includes both negative and positive sentiments, but the negative reviews outweigh the positive ones, indicating overall unhappiness.
```

--------------------------------

### Python Rule Engine with AI Condition and YAML Report

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

Demonstrates setting up a Python RuleEngine, defining a rule with an AI condition based on customer review history, and evaluating it. The output includes a YAML report detailing the rule evaluation, consequences, and the AI-generated rationale.

```python
engine = RuleEngine()

engine.rule(
    name="Customer retention discount",
    when=condition(f"Does the {Customer.review_history} overall sentiment indicate an unhappy customer?"),
    then=action(partial(Discount, percentage=0.15)),
)

reviews = "".join([
    "January: Worst company ever.;",
    "Feburary: I got a good deal with a coupon!;",
    "March: Got broken product.",
])
engine.fact(Customer(review_history=reviews))

engine.evaluate(audit=True)
engine.yaml_report()
```

```yaml
report:
  iterations:
  - id: 0
    timestamp: '2025-07-14T13:21:01.854969Z'
    elapsed: 1.214
    matches:
    - rule: edfcae78:Customer retention discount
      timestamp: '2025-07-14T13:21:01.855002Z'
      elapsed: 1.214
      evaluation: True = Does the {Customer.review_history} overall sentiment indicate an unhappy customer?
      consequences:
        Discount.percentage: 0.15
      context:
      - Customer.review_history: 'January: Worst company ever.;Feburary: I got a good deal with a coupon!;March: Got broken product.'
      rationale: The review history includes both negative and positive sentiments, but the negative reviews outweigh the positive ones, indicating overall unhappiness.
```

--------------------------------

### Apply Context Manager as Decorator with WithContext

Source: https://latchfield.com/vulcan/docs/api/util_q=

The WithContext decorator applies a context manager to a function. This example demonstrates its use with a suppress exception context manager to handle exceptions gracefully. It takes a context manager instance as an argument.

```python
from vulcan.util import WithContext
from contextlib import suppress

@WithContext(suppress(Exception))
def foo():
    raise Exception("Some Exception")
```

--------------------------------

### Compose Conditions with Logical Operators in Python

Source: https://latchfield.com/vulcan/docs/guides/understanding-conditions

Demonstrates composing conditions using '&' (AND), '|' (OR), and '~' (NOT) operators, along with parentheses for order of operations. This allows for readable and maintainable complex logic by breaking it down into smaller, reusable components. It shows how to define Facts, create conditions, and test them.

```python
class Inventory(Fact):
    apples: int


class CurrentDate(Fact):
    day_of_week: int

is_weekend = condition(lambda: CurrentDate.day_of_week in (0, 6))
low_apple_stock = condition(lambda: Inventory.apples < 5)

# Don't reorder apples on the weekend:
time_to_reorder_apples = low_apple_stock & ~is_weekend

# Test the condition:
result = time_to_reorder_apples(Inventory(apples=4), CurrentDate(day_of_week=0))
print(result)
```

--------------------------------

### Python Condition: Lambda Referencing Multiple Facts

Source: https://latchfield.com/vulcan/docs/guides/understanding-conditions

An example of a Python lambda condition that references multiple Facts ('Inventory' and 'CurrentDate') to evaluate a more complex logical expression. This demonstrates how to combine data from different sources within a single condition.

```python
class Inventory(Fact):
    apples: int


class CurrentDate(Fact):
    is_weekend: bool


order_more_apples = condition(lambda: Inventory.apples <= 5 and not CurrentDate.is_weekend)
```

--------------------------------

### AST Utility Classes

Source: https://latchfield.com/vulcan/docs/api/AST_Utils

Documentation for classes involved in AST manipulation and processing.

```APIDOC
## AST Utility Classes

This section details the classes used for transforming and processing Abstract Syntax Trees.

### `AttributeTransformer`

**Description:** Transformer to replace static class attribute access with parameterized instances.

**Bases:** `NodeTransformer`

### `LambdaTracker`

**Description:** Index entry for tracking the parsing position of lambda functions in source lines.

**Attributes:**
- **`source`** (`str`) - The source code string containing lambda functions
- **`positions`** (`list[int]`) - Positions where lambda functions are found in the source
- **`index`** (`int`) - The lambda being parsed within the source string.
- **`in_use`** (`bool`) - Whether this source is currently being processed or not, making it eligible for cache deletion.

**Type:** `dataclass`

### `ASTProcessor`

**Description:** This class extracts source code from functions or lambda expressions, parses them into Abstract Syntax Trees (AST), and performs various validations and transformations. The processor validates that functions have proper type hints, all parameters are subclasses of Fact, no nested attribute access is used, no async functions are processed, lambda expressions do not contain parameters, and no duplicate parameter types exist in function signatures. For lambda expressions, it automatically transforms attribute access patterns into parameterized functions.

**Note:** This class is not thread-safe and should not be used concurrently across multiple threads.

**Type Parameters:**
- `T`: The type of the callable to process.

**Attributes:**
- **`func`** (`T`) - The callable to process, a lambda or a function
- **`decorator`** (`Callable`) - The decorator type that initiated the processing (e.g., `condition` or `action`)
- **`return_type`** (`type | TypeAliasType`) - Expected return type for the callable
- **`source`** (`str`) - Extracted source code of func (set during post-init)
- **`tree`** (`Module`) - Parsed AST of the source code (set during post-init)
- **`facts`** (`tuple[str, ...]`) - Tuple of fact strings discovered in the callable (set during post-init)

**Properties:**
None explicitly defined in the provided text.

**Raises:**
- `OSError` - When source code cannot be extracted
- `ScopeAccessError` - When accessing undefined classes or using nested attributes
- `CallableSignatureError` - When function signature doesn't meet requirements
- `NotAFactError` - When parameter types are not Fact subclasses
- `ASTProcessingError` - When AST processing encounters internal errors

**Type:** `dataclass`
```

--------------------------------

### Displaying Long Strings in Report Context

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

This snippet demonstrates how the Rule Engine uses a 'context' section in reports to display the full values of long strings or similarity fact attributes, preventing clutter in the main evaluation section. It shows a Python example setting up a rule and facts, followed by the generated YAML report.

```python
engine = RuleEngine()

engine.rule(
    name="Vocal customer discount",
    when=condition(lambda: len(Customer.review_history) > 100),
    then=action(partial(Discount, percentage=0.05)),
)

reviews = "A long string that represents customer reviews"
engine.fact(Customer(review_history=reviews))

engine.evaluate(audit=True)
engine.yaml_report()
```

```yaml
report:
  iterations:
  - id: 0
    timestamp: '2025-07-14T13:21:00.376838Z'
    elapsed: 0.0
    matches:
    - rule: 424d225c:Vocal customer discount
      timestamp: '2025-07-14T13:21:00.376869Z'
      elapsed: 0.0
      evaluation: False = (len(Customer.review_history) > 100)
      consequences: None
      context:
      - Customer.review_history: A long string that represents customer reviews
```

--------------------------------

### Python Grocery Checkout System with Vulcan Rule Engine

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

This Python code defines a rule engine for a grocery store checkout system. It includes fact definitions for cart items, customer information, pricing, promotions, and checkout status. Custom actions and rules are defined to calculate subtotals, apply discounts (bulk and loyalty), handle age verification, and approve payments. The system demonstrates a step-by-step processing of checkout logic.

```python
from functools import partial

from vulcan_core import ActionReturn, Fact, RuleEngine, action, condition


# Fact definitions
class CartItem(Fact):
    quantity: int
    price_per_item: float = 2.50
    is_perishable: bool = False
    category: str = "general"


class Customer(Fact):
    is_loyalty_member: bool = False
    age: int = 18
    review_history: str = ""


class Pricing(Fact):
    subtotal: float = 0.0
    discount_amount: float = 0.0
    tax_rate: float = 0.08
    total_amount: float = 0.0


class Promotions(Fact):
    applied: bool = False
    bulk_discount_applied: bool = False
    loyalty_discount_applied: bool = False


class Checkout(Fact):
    age_verification_required: bool = False
    payment_approved: bool = False
    special_handling_required: bool = False


class Alert(Fact):
    message: str = ""


# Custom actions
@action
def calculate_total(pricing: Pricing) -> ActionReturn:
    """Calculate the total rounded amount based on applied promotions."""
    amount = (pricing.subtotal - pricing.discount_amount) * (1 + pricing.tax_rate)
    amount = round(amount, 2)
    return partial(Pricing, total_amount=amount)


# Create the rule engine and add rule definitions
engine = RuleEngine()

# Iteration 0: Initial cart processing
engine.rule(
    name="Calculate initial subtotal",
    when=condition(lambda: CartItem.quantity > 0),
    then=action(lambda: partial(Pricing, subtotal=CartItem.quantity * CartItem.price_per_item)),
)

engine.rule(
    name="Special handling for perishables",
    when=condition(lambda: CartItem.is_perishable and CartItem.quantity > 5),
    then=action(partial(Checkout, special_handling_required=True)),
)

engine.rule(
    name="Age verification for restricted items",
    when=condition(lambda: CartItem.category == "alcohol"),
    then=action(partial(Checkout, age_verification_required=True)),
)

# Iteration 1: Apply promotions (after subtotal calculated)
engine.rule(
    name="Bulk discount eligibility",
    when=condition(lambda: CartItem.quantity >= 10 and Pricing.subtotal > 30.0),
    then=action(partial(Promotions, bulk_discount_applied=True)),
    inverse=action(partial(Promotions, bulk_discount_applied=False)),
)

engine.rule(
    name="Customer retention discount",
    when=condition(lambda: Pricing.subtotal > 30.0)
    & condition(f"Does the {Customer.review_history} overall sentiment indicate an unhappy customer?")
    & condition(lambda: Customer.is_loyalty_member),
    then=action(partial(Promotions, loyalty_discount_applied=True)),
)

# Iteration 2: Calculate any discount amounts
engine.rule(
    name="Apply bulk discount amount",
    when=condition(lambda: Promotions.bulk_discount_applied),
    then=action(
        lambda: (
            partial(Pricing, discount_amount=round(Pricing.subtotal * 0.15, 2)),
            partial(Promotions, applied=True),
        )
    ),
)

engine.rule(
    name="Apply loyalty discount amount",
    when=condition(lambda: Promotions.loyalty_discount_applied and not Promotions.bulk_discount_applied),
    then=action(
        lambda: (
            partial(Pricing, discount_amount=round(Pricing.subtotal * 0.08, 2)),
            partial(Promotions, applied=True),
        )
    ),
)

# Iteration 3: Final calculations and approvals
engine.rule(
    name="Calculate final total with tax",
    when=condition(lambda: Promotions.applied and Pricing.subtotal > 0),
    then=calculate_total,
)

engine.rule(
    name="Payment approval",
    when=condition(lambda: Customer.age >= 21 or not Checkout.age_verification_required)
    & condition(lambda: Pricing.total_amount > 0),
    then=action(partial(Checkout, payment_approved=True)),
)

engine.rule(
    name="High-value purchase alert",
    when=condition(lambda: Pricing.total_amount > 100.0),
    then=action(lambda: partial(Alert, message=f"High-value transaction: ${Pricing.total_amount:.2f}")),
)

```

--------------------------------

### Update and Evaluate Rules with Facts (Python)

Source: https://latchfield.com/vulcan/docs/api/engine

Shows how to update the RuleEngine's working memory with new facts and then trigger an evaluation of the rules. It also illustrates how to perform an immediate update and evaluation with a specific fact.

```python
from vulcan.core.rule_engine import RuleEngine
from vulcan.core.facts import Fact
from vulcan.core.expressions import Expression
from vulcan.core.actions import Action

# Assuming Fact, Expression, and Action are defined elsewhere
# Example placeholders:
class MockFact(Fact):
    pass

class MockExpression(Expression):
    pass

class MockAction(Action):
    pass

rule_engine = RuleEngine()

# Add a rule first (example)
rule_engine.rule(
    name="SampleRule",
    when=MockExpression(),
    then=MockAction()
)

# Update facts and evaluate all rules
rule_engine.update_facts(MockFact())
rule_engine.evaluate()

# Update with a specific fact and evaluate immediately
rule_engine.evaluate(fact=MockFact())
```

--------------------------------

### Demonstrate Vulcan Rule Warnings with Python and YAML

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

This snippet shows how to define rules in Python using the Vulcan RuleEngine and generate a YAML report that highlights potential issues like Rule Ordering and Fact Replacement. It demonstrates a scenario where multiple rules affect the same attributes, leading to warnings in the audit report.

```python
engine = RuleEngine()

engine.rule(
    name="Approve payment for loyalty members",
    when=condition(lambda: Customer.is_loyalty_member),
    then=action(partial(Checkout, payment_approved=True)),
)

engine.rule(
    name="For demonstration, negate the previous rule",
    when=condition(lambda: Customer.is_loyalty_member),
    then=action(partial(Checkout, payment_approved=False)),
)

engine.rule(
    name="Deny payment for minors",
    when=condition(lambda: Customer.age <= 18),
    then=action(Checkout(special_handling_required=False)),
)

engine.fact(Customer(is_loyalty_member=True, age=17))
engine.evaluate(audit=True)


engine.yaml_report()
```

```yaml
report:
  iterations:
  - id: 0
    timestamp: '2025-07-14T13:21:03.090673Z'
    elapsed: 0.0
    matches:
    - rule: 9a5b47a0:Approve payment for loyalty members
      timestamp: '2025-07-14T13:21:03.090684Z'
      elapsed: 0.0
      evaluation: True = (Customer.is_loyalty_member|True|)
      consequences:
        Checkout.payment_approved: true
    - rule: 533ce3b0:For demonstration, negate the previous rule
      timestamp: '2025-07-14T13:21:03.090790Z'
      elapsed: 0.0
      evaluation: True = (Customer.is_loyalty_member|True|)
      consequences:
        Checkout.payment_approved: false
      warnings:
      - Rule Ordering | Rule:9a5b47a0 consequence (Checkout.payment_approved|True|) was overridden by Rule:533ce3b0 (Checkout.payment_approved|False|) within the same iteration
    - rule: c8ca9130:Deny payment for minors
      timestamp: '2025-07-14T13:21:03.090872Z'
      elapsed: 0.0
      evaluation: True = (Customer.age|17| <= 18)
      consequences:
        Checkout.payment_approved: false
        Checkout.special_handling_required: false
        Checkout.age_verification_required: false
      warnings:
      - Fact Replacement | Rule:c8ca9130 consequence replaces (Checkout), potentially altering unintended attributes. Consider using a partial update to ensure only intended changes.
```

--------------------------------

### Configure Scoped Model with functools.partial in Python

Source: https://latchfield.com/vulcan/docs/guides/model-configuration

Shows how to pre-configure a model for multiple rules using `functools.partial`. This reduces code duplication by creating a customized `condition` function with a default model.

```python
from functools import partial

condition = partial(condition, model=ChatOpenAI(model="gpt-4o-mini"))  

engine.rule(
    when=condition(f"Are {Inventory.apple_kind} considered delicious by most people?"),  
    then=action(QueuedOrder(apples=50)),
)
```

--------------------------------

### RetrieverAdapter: Similarity Search with Chroma and OpenAI

Source: https://latchfield.com/vulcan/docs/api/models

Illustrates the use of RetrieverAdapter for performing similarity searches using the Chroma vector store and OpenAI embeddings. This class inherits from Similarity and provides methods for searching and checking for matches.

```python
from vulcan.models import RetrieverAdapter

# Assuming retriever_adapter is an initialized instance of RetrieverAdapter
# Example usage:
results = retriever_adapter['example query']
exists = 'example query' in retriever_adapter
```

--------------------------------

### Configure Rule-Specific Model in Python

Source: https://latchfield.com/vulcan/docs/guides/model-configuration

Demonstrates how to explicitly set a custom LangChain model (ChatOpenAI) for a specific rule's condition. This allows fine-grained control over model usage per rule.

```python
from langchain_openai import ChatOpenAI

my_model = ChatOpenAI(model="gpt-4o-mini", temperature=0, max_tokens=100)  

engine.rule(
    when=condition(f"Are {Inventory.apple_kind} considered delicious by most people?", model=my_model),  
    then=action(QueuedOrder(apples=50)),
)
```

--------------------------------

### Displaying Long Strings in Reports with Context (Python)

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports

This Python code demonstrates how to use the RuleEngine to manage long strings in reports. It shows how a 'context' section can be used to display the full value of long strings or similarity searches, improving report readability by keeping inline evaluations concise. The engine is configured, a rule is defined, a long string is added as a fact, and then the report is generated.

```python
engine = RuleEngine()

engine.rule(
    name="Vocal customer discount",
    when=condition(lambda: len(Customer.review_history) > 100),
    then=action(partial(Discount, percentage=0.05)),
)

reviews = "A long string that represents customer reviews"
engine.fact(Customer(review_history=reviews))

engine.evaluate(audit=True)
engine.yaml_report()
```

--------------------------------

### Use Descriptive Rule Names in Python

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

This Python snippet demonstrates the best practice of using descriptive names for rules within the Vulcan RuleEngine. Clear rule names enhance the readability and understandability of audit reports, making it easier to trace rule logic and outcomes.

```python
engine.rule(name="Apply senior citizen discount", when=..., then=...)
```

--------------------------------

### Avoid Vague or Missing Rule Names in Python

Source: https://latchfield.com/vulcan/docs/guides/explainability-reports_q=

This Python snippet illustrates the anti-pattern of using vague or missing names for rules in the Vulcan RuleEngine. Such practices lead to less informative audit reports, making it difficult to identify the purpose and impact of individual rules.

```python
engine.rule(name="Rule 42", when=..., then=...)
engine.rule(when=..., then=...)
```
Tokens:
Raw