ApiLogicServer 15.0.61__py3-none-any.whl → 15.1.0__py3-none-any.whl

api_logic_server_cli/prototypes/manager/samples/basic_demo/logic/procedural/declarative-vs-procedural-comparison.md

@@ -0,0 +1,295 @@
+# Declarative vs. Procedural Business Logic: A Comprehensive Comparison
+
+<br>
+
+## Foreword
+
+This document presents a real-world A/B comparison of two approaches to implementing the **same business logic requirements.**  We asked AI to generate both a **procedural** implementation using conventional code, and a **declarative** implementation using the LogicBank rules engine. 
+
+This experiment highlights fundamental differences between the two approaches, and what they mean for building reliable, maintainable systems.  It's important, because business logic typically represents *nearly half the effort* in database projects. 
+
+When asked to produce logic, AI (by itself) defaults to procedural code — because that’s all it knows. This study uncovered two critical problems with that approach:
+1. **Quality:** The AI-generated procedural code contained subtle but serious bugs, even for just five rules—falling far short of basic reliability.
+2.	**Maintainability:** The procedural implementation exploded to over 200 lines — more than 40X the size of its declarative equivalent — creating “Franken-Code” that is brittle, opaque, and costly to maintain.
+
+By contrast, the declarative approach was error free, and 5 Python statements.
+
+The answer isn’t to reject AI. Its speed and simplicity are transformative. The key is to **teach AI about declarative rules** so it can produce concise, expressive rules instead of hundreds of lines of brittle procedural code. These rules are then executed by an **automated runtime engine** (like LogicBank), ensuring correctness, scalability, and maintainability — while preserving the velocity that makes AI so valuable.
+
+By combining AI with declarative automation, GenAI-Logic delivers the best of both worlds: rapid development and enterprise-grade governance.
+
+![visually](declarative-vs-procedural-comparison.png)
+
+<br>
+
+### Deeper Dive
+
+[GenAI-Logic](https://www.genai-logic.com) is free and open source, so you can install it to explore declarative logic - [click here](https://apilogicserver.github.io/Docs/Install-Express/).  This project is available in github - [click here](https://github.com/ApiLogicServer/basic_demo/blob/main/logic/declarative-vs-procedural-comparison.md).
+
+<br>
+
+### How this Document Was Created
+
+We created this document from the following scenario:
+
+1. Built the `basic_demo` project [as described here](https://apilogicserver.github.io/Docs/Sample-Basic-Demo/).
+2. We asked CoPilot to **rebuild the logic *using a procedural approach*** - that is, without the LogicBank rule engine (part of GenAI-Logic).
+    * Resulting Procedural Logic: `logic/procedural_logic.py`
+    * Declarative logic: `logic/declare_logic.py` (*with LogicBank,* [below](#business-requirements))
+3. We asked Copilot: **what would happen if the orders' customer-id were changed?**
+    * Copilot accepted this as a serious error, and made the bug fix.
+4. We then asked Copilot: *what if the items' product-id were changed?*
+    * Copilot became agitated at finding yet another serious bug...
+    * It fixed it, and - ***unprompted* - provided the following analysis** of *Declarative vs Procedural Business Logic.*
+
+<br>
+
+> Here's the Copilot analysis, in its own words.
+
+<br>
+
+
+## TL;DR
+
+**LogicBank declarative rules provide a 44X reduction in code complexity** compared to traditional procedural implementations:
+
+| Aspect | LogicBank Declarative | Procedural Code |
+|--------|----------------------|-----------------|
+| **Lines of Code** | 5 lines | 220+ lines |
+| **Complexity** | Simple rule declarations | Complex event handling |
+| **Maintenance** | Self-documenting business logic | Implementation details obscure logic |
+| **Performance** | Built-in optimization & pruning | Multiple queries, N+1 problems |
+| **Error Handling** | Automatic cascading | Manual event management |
+| **Business Alignment** | Rules match requirements | Code doesn't reflect business intent |
+
+**Bottom Line**: Declarative business logic eliminates complexity while providing better performance, maintainability, and business alignment.
+
+---
+
+## Overview
+
+This document compares two approaches to implementing business logic in enterprise applications:
+- **Declarative Logic** using LogicBank rules
+- **Traditional Procedural Logic** using event handlers
+
+The comparison is based on implementing the same business requirements using both approaches in an order management system.
+
+## Business Requirements
+
+Our test case implements these common business rules:
+
+1. **Copy unit_price from Product to Item**
+2. **Calculate Item amount = quantity × unit_price**
+3. **Calculate Order total = sum of Item amounts**
+4. **Update Customer balance = sum of unshipped Order totals**
+5. **Ensure Customer balance ≤ credit_limit**
+6. **Validate Item quantity > 0**
+7. **Log order events**
+
+## Code Comparison
+
+### LogicBank Declarative Rules (~5 lines)
+
+```python
+# Business logic expressed as simple, readable rules
+def declare_logic():
+    # Rule 1: Copy unit price from product to item
+    Rule.copy(derive=Item.unit_price, from_parent=Product.unit_price)
+    
+    # Rule 2: Calculate item amount
+    Rule.formula(derive=Item.amount, as_expression=lambda row: row.quantity * row.unit_price)
+    
+    # Rule 3: Calculate order total
+    Rule.sum(derive=Order.amount_total, as_sum_of=Item.amount)
+    
+    # Rule 4: Update customer balance
+    Rule.sum(derive=Customer.balance, as_sum_of=Order.amount_total, 
+             where=lambda row: row.date_shipped is None)
+    
+    # Rule 5: Validate credit limit
+    Rule.constraint(validate=Customer, 
+                   as_condition=lambda row: row.balance <= row.credit_limit,
+                   error_msg="Customer balance exceeds credit limit")
+```
+
+### Procedural Implementation (~220 lines)
+
+```python
+# Complex event handling with manual cascading
+def handle_item_update(mapper, connection, target: models.Item):
+    session = Session.object_session(target)
+    
+    # Get OLD version to detect changes
+    old_item = session.query(models.Item).get(target.id)
+    
+    # Validate quantity
+    ProceduralBusinessLogic.validate_item_quantity(target)
+    
+    # Handle product changes (CRITICAL BUG FIX)
+    if old_item and old_item.product_id != target.product_id:
+        ProceduralBusinessLogic.copy_unit_price_from_product(target, session)
+    
+    # Recalculate item amount
+    ProceduralBusinessLogic.calculate_item_amount(target)
+    
+    # Handle order changes (another potential bug!)
+    if old_item and old_item.order_id != target.order_id:
+        # Update OLD order total
+        old_order = session.query(models.Order).get(old_item.order_id)
+        if old_order:
+            ProceduralBusinessLogic.calculate_order_total(old_order, session)
+            # Update old customer balance
+            old_customer = session.query(models.Customer).get(old_order.customer_id)
+            if old_customer:
+                ProceduralBusinessLogic.update_customer_balance(old_customer, session)
+                ProceduralBusinessLogic.validate_credit_limit(old_customer)
+    
+    # Update NEW order total
+    if target.order_id:
+        order = session.query(models.Order).get(target.order_id)
+        if order:
+            ProceduralBusinessLogic.calculate_order_total(order, session)
+            customer = session.query(models.Customer).get(order.customer_id)
+            if customer:
+                ProceduralBusinessLogic.update_customer_balance(customer, session)
+                ProceduralBusinessLogic.validate_credit_limit(customer)
+```
+
+## Detailed Comparison
+
+### 1. **Code Volume**
+| Aspect | LogicBank | Procedural |
+|--------|-----------|------------|
+| Lines of Code | ~5 | ~220 |
+| Complexity | Simple rule declarations | Complex event handling |
+| Ratio | **44X MORE CONCISE** | Baseline |
+
+### 2. **Maintainability**
+
+**LogicBank:**
+- ✅ Rules are self-documenting
+- ✅ Business logic is immediately recognizable
+- ✅ Changes are localized to specific rules
+- ✅ Easy to add new rules without affecting existing ones
+
+**Procedural:**
+- ❌ Business logic buried in implementation details
+- ❌ Hard to understand the complete business flow
+- ❌ Changes require understanding entire event chain
+- ❌ Risk of breaking existing functionality
+
+### 3. **Error Handling & Edge Cases**
+
+**LogicBank:**
+- ✅ Automatic handling of all change scenarios
+- ✅ Built-in transaction rollback
+- ✅ No need to manually track old/new values
+- ✅ Automatic cascade management
+
+**Procedural:**
+- ❌ Manual handling of every edge case
+- ❌ Comments like "CRITICAL BUG FIX" indicate complexity
+- ❌ Must manually track old values for comparison
+- ❌ Easy to miss scenarios (product changes, order moves, etc.)
+
+### 4. **Performance**
+
+**LogicBank:**
+- ✅ **Pruning**: Rules only fire when dependent attributes change
+- ✅ **Optimization**: Uses SQL "adjustment" updates vs full recalculations
+- ✅ **Minimal SQL**: Optimized query patterns
+- ✅ **No N+1 problems**: Intelligent batching
+
+**Procedural:**
+- ❌ Multiple queries per operation
+- ❌ Potential N+1 problems
+- ❌ Full recalculations even for minor changes
+- ❌ No automatic optimization
+
+### 5. **Debugging & Observability**
+
+**LogicBank:**
+- ✅ Clear rule execution logs
+- ✅ Shows rule chains and dependencies
+- ✅ Easy to trace business logic flow
+- ✅ Built-in logging with row state changes
+
+**Procedural:**
+- ❌ Hard to trace through event handlers
+- ❌ Must manually add logging
+- ❌ Difficult to understand execution flow
+- ❌ Error messages don't relate to business rules
+
+### 6. **Testing**
+
+**LogicBank:**
+- ✅ Test individual rules independently
+- ✅ Clear rule execution reports
+- ✅ Behave testing integration
+- ✅ Rules map directly to test scenarios
+
+**Procedural:**
+- ❌ Must test entire event chain
+- ❌ Hard to isolate specific logic
+- ❌ Complex test setup required
+- ❌ Brittle tests that break with changes
+
+### 7. **Business Alignment**
+
+**LogicBank:**
+- ✅ Rules read like business requirements
+- ✅ Business users can understand the logic
+- ✅ Direct mapping from requirements to code
+- ✅ Self-documenting business policies
+
+**Procedural:**
+- ❌ Implementation details obscure business logic
+- ❌ Business users cannot read the code
+- ❌ No clear mapping from requirements
+- ❌ Business logic scattered across handlers
+
+## Real-World Impact
+
+### Development Time
+- **LogicBank**: Write rules once, they work everywhere
+- **Procedural**: Must consider every possible scenario upfront
+
+### Risk Management
+- **LogicBank**: Automatic handling reduces risk of bugs
+- **Procedural**: High risk of missing edge cases
+
+### Team Productivity
+- **LogicBank**: New team members can quickly understand rules
+- **Procedural**: Requires deep understanding of event system
+
+### Business Agility
+- **LogicBank**: Easy to modify rules as business changes
+- **Procedural**: Changes require extensive testing and validation
+
+## Conclusion
+
+The comparison demonstrates that **LogicBank provides a 44X reduction in code complexity** while delivering:
+
+- **Better Maintainability**: Rules are self-documenting and easy to modify
+- **Higher Quality**: Automatic handling eliminates common bugs
+- **Better Performance**: Built-in optimizations and pruning
+- **Business Alignment**: Rules directly express business requirements
+- **Faster Development**: Write less code, get more functionality
+
+### The LogicBank Advantage
+
+> **"Logic is declarative, not procedural"**
+
+LogicBank represents a fundamental shift from asking **"How do I implement this?"** to **"What do I want to happen?"**
+
+This declarative approach:
+1. **Eliminates the complexity** of manual event handling
+2. **Reduces maintenance burden** through automatic rule management
+3. **Improves business alignment** with readable, requirements-based rules
+4. **Accelerates development** with dramatically less code
+
+The evidence is clear: **Declarative business logic is not just more concise—it's fundamentally superior for enterprise application development.**
+
+---
+
+*This comparison is based on actual implementations in the API Logic Server project, demonstrating real-world benefits of declarative business logic.*

api_logic_server_cli/prototypes/manager/samples/basic_demo/logic/readme_logic.md

@@ -0,0 +1,249 @@
+This describes how to use Logic; for more information, [see here](https://apilogicserver.github.io/Docs/Logic-Why).
+
+> What is Logic: Multi-table Derivation and Constraint Rules, Extensible with Python 
+<br>Rules are:
+<br>1. **Declared** in your IDE - 40X more concise
+<br>2. **Activated** on server start
+<br>3. **Executed** - *automatically* -  on updates (using SQLAlchemy events)
+<br>4. **Debugged** in your IDE, and with the console log
+<br>For more on rules, [click here](https://apilogicserver.github.io/Docs/Logic-Why/).
+
+&nbsp;
+
+## 🚀 Quick Start, using the `basic_demo` sample database
+
+You can provide prompts like this to CoPilot.  This is a good approach for new users:
+
+```text title="Declare Logic in Natural Language"
+Create Business Logic for Use Case = Check Credit:  
+    1. The Customer's balance is less than the credit limit
+    2. The Customer's balance is the sum of the Order amount_total where date_shipped is null
+    3. The Order's amount_total is the sum of the Item amount
+    4. The Item amount is the quantity * unit_price
+    5. The Item unit_price is copied from the Product unit_price
+
+Use case: App Integration
+    1. Send the Order to Kafka topic 'order_shipping' if the date_shipped is not None.
+```
+
+Basic process:
+1. Create a file such as `logic/logic_discovery/check_credit.py` (e.g., copy from `use_case.py`).
+2. Paste the prompt above into CoPilot - use `docs/training` to generate logic
+3. Paste the generated logic into `logic/logic_discovery/check_credit.py`
+
+From the Natural Language, Copilot will create Python rules (you can also create these directly using code completion):
+```python
+    if os.environ.get("WG_PROJECT"):
+        # Inside WG: Load rules from docs/expprt/export.json
+        load_verify_rules()
+    else:
+        # Outside WG: load declare_logic function
+        from logic.logic_discovery.auto_discovery import discover_logic
+        discover_logic()
+
+    # Logic from GenAI: (or, use your IDE w/ code completion)
+    from database.models import Product, Order, Item, Customer, SysEmail
+
+    # Ensure the customer's balance is less than their credit limit
+    Rule.constraint(validate=Customer, as_condition=lambda row: row.balance <= row.credit_limit, error_msg="Customer balance ({row.balance}) exceeds credit limit ({row.credit_limit})")
+
+    # Derive the customer's balance as the sum of order totals where not yet shipped.
+    Rule.sum(derive=Customer.balance, as_sum_of=Order.amount_total, where=lambda row: row.date_shipped is None)
+
+    # Derive the order's total amount from the sum of item amounts.
+    Rule.sum(derive=Order.amount_total, as_sum_of=Item.amount)
+
+    # Calculate item amount based on quantity and unit price.
+    Rule.formula(derive=Item.amount, as_expression=lambda row: row.quantity * row.unit_price)
+
+    # Copy unit price from product to item.
+    Rule.copy(derive=Item.unit_price, from_parent=Product.unit_price)
+
+    # Send order details to Kafka if order is shipped.
+    Rule.after_flush_row_event(on_class=Order, calling=kafka_producer.send_row_to_kafka, if_condition=lambda row: row.date_shipped is not None, with_args={'topic': 'order_shipping'})
+
+    # End Logic from GenAI
+```
+
+## Natural Language vs. IDE
+
+If you are using WebGenAI, you can specify rules in Natural Language. You can also augment them in the IDE using code completion.  There are some important usage guidelines.  
+
+> You should generally not alter any files in the `wg_rules` directory.  For more information, see [WebGenAI](https://apilogicserver.github.io/Docs/WebGenAI/), and [WebGenAI Logic](https://apilogicserver.github.io/Docs/WebGenAI-CLI.md#natural-language-logic).
+
+&nbsp;
+
+## Using Discovery
+
+You can declare logic in `declare_logic.py`,
+but that can lead to a lot of rules in 1 file.
+
+A *best practice* is to create logic files in `logic/logic_discovery`,
+named after the use case (e.g., `check_credit.py`).  
+
+The easiest way to to copy/paste `use_case.py` to a new file, then
+add your logic either by Natural Language (use your Coding Assistant, such as CoPilot),
+or your IDE's code completion.
+
+<br>
+
+## Examples      
+Examples from tutorial project:
+* Examples drawn from [tutorial project](https://github.com/ApiLogicServer/demo/blob/main/logic/declare_logic.py)
+* Use Shift + "." to view in project mode
+
+You can [find the rules here](https://apilogicserver.github.io/Docs/Logic).  Below, we explore the syntax of 3 typical rules.
+
+&nbsp;
+
+### 1. Multi-Table Derivations
+
+This declares the Customer.Balance as the sum of the unshipped Order.AmountTotal:
+
+```python
+    Rule.sum(derive=models.Customer.Balance,
+            as_sum_of=models.Order.AmountTotal,
+            where=lambda row: row.ShippedDate is None)
+```
+It means the rule engine **watches** for these changes:
+* Order inserted/deleted, or
+* AmountTotal or ShippedDate or CustomerID changes
+
+Iff changes are detected, the engine **reacts** by *adjusting* the Customer.Balance.  SQLs are [optimized](#declarative-logic-important-notes).
+
+This would **chain** to check the Customers' Constraint rule, described below.
+
+&nbsp;
+
+### 2. Constraints: lambda or function
+
+Constraints are multi-field conditions which must be true for transactions to succeed (else an exception is raised).  You can express the condition as a lambda or a function:
+
+**As a lambda:**
+```python
+    Rule.constraint(validate=models.Customer,
+        as_condition=lambda row: row.Balance <= row.CreditLimit,  # parent references are supported
+        error_msg="balance ({row.Balance}) exceeds credit ({row.CreditLimit})")
+```
+
+**Or, as a function:**
+```python
+    def check_balance(row: models.Customer, old_row: models.Customer, logic_row: LogicRow):
+        if logic_row.ins_upd_dlt != "dlt":  # see also: logic_row.old_row
+            return row.Balance <= row.CreditLimit
+        else:
+            return True
+
+    Rule.constraint(validate=models.Customer,
+        calling=check_balance,
+        error_msg=f"balance ({row.Balance}) exceeds credit ({row.CreditLimit})")
+```
+
+&nbsp;
+
+### 3. Row Events: Extensible with Python
+
+Events are procedural Python code, providing extensibility for declarative rules:
+```python
+    def congratulate_sales_rep(row: models.Order, old_row: models.Order, logic_row: LogicRow):
+        pass  # event code here - sending email, messages, etc.
+
+    Rule.commit_row_event(on_class=models.Order, calling=congratulate_sales_rep)
+```
+Note there are multiple kinds of events, so you can control whether they run before or after rule execution.  For more information, [see here](https://apilogicserver.github.io/Docs/Logic-Type-Constraint).
+
+&nbsp;
+
+## LogicRow: old_row, verb, etc
+
+A key argument to functions is `logic_row`:
+
+* **Wraps row and old_row,** plus methods for insert, update and delete - rule enforcement
+
+* **Additional instance variables:** ins_upd_dlt, nest_level, session, etc.
+
+* **Helper Methods:** are_attributes_changed, set_same_named_attributes, get_parent_logic_row(role_name), get_derived_attributes, log, is_inserted, etc
+
+Here is an example:
+
+```python
+"""
+    STATE TRANSITION LOGIC, using old_row
+"""
+def raise_over_20_percent(row: models.Employee, old_row: models.Employee, logic_row: LogicRow):
+    if logic_row.ins_upd_dlt == "upd" and row.Salary > old_row.Salary:
+        return row.Salary >= Decimal('1.20') * old_row.Salary
+    else:
+        return True
+
+Rule.constraint(validate=models.Employee,
+                calling=raise_over_20_percent,
+                error_msg="{row.LastName} needs a more meaningful raise")
+```
+
+Note the `log` method, which enables you to write row/old_row into the log with a short message:
+
+```python
+logic_row.log("no manager for this order's salesrep")
+```
+
+&nbsp;
+
+## Declarative Logic: Important Notes
+
+Logic *declarative*, which differs from conventional *procedural* logic:
+
+1. **Automatic Invocation:** you don't call the rules; they execute in response to updates (via SQLAlchemy events).
+
+2. **Automatic Ordering:** you don't order the rules; execution order is based on system-discovered depencencies.
+
+3. **Automatic Optimizations:** logic is optimized to reduce SQLs.
+
+    * Rule execution is *pruned* if dependent attributes are not altered
+    * SQL is optimized, e.g., `sum` rules operate by *adjustment*, not expensive SQL `select sum`
+
+These simplify maintenance / iteration: you can be sure new logic is always called, in the correct order.
+
+&nbsp;
+
+## Debugging
+
+Debug rules using **system-generated logic log** and your **IDE debugger**; for more information, [see here](https://apilogicserver.github.io/Docs/Logic-Use).
+
+&nbsp;
+
+### Using the debugger
+
+Use the debugger as shown below.  Note you can stop in lambda functions.
+
+![Logic Debugger](https://apilogicserver.github.io/Docs/images/logic/logic-debug.png)
+
+&nbsp;
+
+### Logic Log
+
+Logging is performed using standard Python logging, with a logger named `logic_logger`.  Use `info` for tracing, and `debug` for additional information (e.g., all declared rules are logged).
+
+In addition, the system logs all rules that fire, to aid in debugging.  Referring the the screen shot above:
+
+*   Each line represents a rule execution, showing row state (old/new values), and the _{reason}_ that caused the update (e.g., client, sum adjustment)
+*   Log indention shows multi-table chaining
+
+&nbsp;
+
+## How Logic works
+
+*Activation* occurs in `api_logic_server_run.py`:
+```python
+    LogicBank.activate(session=session, activator=declare_logic, constraint_event=constraint_handler)
+```
+
+This installs the rule engine as a SQLAlchemy event listener (`before_flush`).  So, Logic *runs* automatically, in response to transaction commits (typically via the API).
+
+Rules plug into SQLAlchemy events, and execute as follows:
+
+| Logic Phase | Why It Matters |
+|:-----------------------------|:---------------------|
+| **Watch** for changes at the attribute level | Performance - Automatic Attribute-level Pruning |
+| **React** by recomputing value | Ensures Reuse - Invocation is automatic<br>Derivations are optimized (e.g. *adjustment updates* - not aggregate queries) |
+| **Chain** to other referencing data | Simplifies Maintenance - ordering is automatic<br>Multi-table logic automation |