Explainability Reports¶

from functools import partial

from vulcan_core import Fact, RuleEngine, action, condition


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


class TotalCost(Fact):
    amount: float = 0.0


# Create an engine instance and add a simple rule
engine = RuleEngine()

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

# Add initial facts and evaluate with auditing enabled
engine.fact(CartItem(quantity=3))
engine.evaluate(audit=True)

engine.yaml_report()

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()

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()

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()

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()

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()

engine = RuleEngine()

engine.rule(  # (1)!
    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()

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()

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()

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}")),
)

# Add initial facts
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()