ApiLogicServer 15.0.47__py3-none-any.whl → 15.0.54__py3-none-any.whl

api_logic_server_cli/prototypes/basic_demo/docs/system-creation-vibe.md

@@ -0,0 +1,161 @@
+---
+title: Vibe MCP / Microservice
+version: 0.23 from docsite 7/11/2025
+---
+<style>
+  .md-typeset h1,
+  .md-content__button {
+    display: none;
+  }
+</style>
+
+<< Under Construction >>
+
+# Vibe an MCP Microservice
+
+See the Readme for detailed walk through.
+
+Scenario: we have an existing database (customers, order, items and product), and we require:
+
+* An MCP-enabled API, for integration
+* MCP client support to send emails for overdue orders
+* Business Logic to check credit by rolling up Items and Orders.
+
+This is a record of how we created the system using CoPilot Chat (*Vibe*).
+
+<br>
+
+## Initialize CoPilot
+
+```
+Please find and read `.github/.copilot-instructions.md`.
+```
+
+<br>
+
+## Create the System
+
+```bash title="Create a project from an existing database"
+# in the GenAI-Logic Manager:
+Create a database project from samples/dbs/basic_demo.sqlite
+```
+
+<br>
+
+## Verify the API and Admin App
+
+The project should automatically open a new window in VSCode.  Again, open CoPilot and bootstrap it with: <br>
+
+```bash title="Initialize CoPilot"
+Please find and read `.github/.copilot-instructions.md`**.
+```
+
+Verify it as follows:
+
+* **Click F5** to start server, open app at http://localhost:5656/
+* **Verify API:** filtering, sorting, pagination, optimistic locking and related data access - see the Swagger
+* **Verify Admin App:** multi-page, multi-table, automatic joins, lookups, cascade add - collaboration-ready
+
+<br>
+
+## Create a Custom React App
+
+**Create Start App**
+```bash title="Create a custom react app"
+Create a react app.
+```
+
+<br>
+
+**Customize - add cards**
+```txt title='Customize using Natural Language'
+In the ui/react app, update the Product list to provide users an option to see results in a list,
+or in cards.
+```
+<br>
+
+todo - diagram 
+
+**Test: verify option for cards on `http://localhost:3000`**
+
+<br>
+
+## MCP Client - Overdue Orders
+
+**Stop the Server**
+
+<br>
+
+**Create MCP Executor: process request - invokes the LLM to obtain a series of API calls to run, and runs them**
+``` bash title="Create an MCP Client Executor"
+Create the mcp client executor
+```
+<br>
+
+**Add a Table to Track Sent Emails**
+``` bash title="Add a Table to Track Sent Emails"
+Create a table SysEmail in `database/db.sqlite` as a child of customer, 
+with columns id, message, subject, customer_id and CreatedOn.
+```
+Follow the suggestions to update the admin app.
+
+<br>
+
+**Create the email service stub using SysEmail as a Request Table**
+``` bash title="Create the email service using SysEmail as a Request Table"
+Add an after_flush event on SysEmail to produce a log message "email sent",
+unless the customer has opted out.
+```
+
+<br>
+
+**Business Logic to Honor Email Opt-out**
+```bash title="Business Logic to Honor Email Opt-out"
+Add an after_flush event on SysEmail to produce a log message "email sent",
+unless the customer has opted out.
+```
+
+<br>
+
+**Test: restart the server/admin app - Click SysMCP >> Create New, and enter:**
+```text title="Test the MCP Client: Click SysMCP >> Create New, and enter"
+List the orders date_shipped is null and CreatedOn before 2023-07-14, 
+and send a discount email (subject: 'Discount Offer') to the customer for each one.
+```
+
+<br>
+todo - diagram 
+
+**Use the Admin App to Verify the first customer has an email**
+
+<br>
+
+## Check Credit Business Logic
+
+**1. Stop the Server** (Red Stop button, or Shift-F5 -- see Appendix)
+
+**2. Add Business Logic**
+
+```bash title="Check Credit Logic (instead of 220 lines of code)"
+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.
+```
+
+To test the logic:
+
+**1. Use the Admin App to access the first order for `Customer Alice`**
+
+**2. Edit its first item to a very high quantity**
+
+todo - diagram 
+
+The update is properly rejected because it exceeds the credit limit.  Observe the rules firing in the console log - see Logic In Action, below.
+
+<br>

api_logic_server_cli/prototypes/basic_demo/logic/declarative-vs-procedural-comparison.html

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>Page Moved - Declarative vs Procedural Comparison</title>
+    <meta http-equiv="refresh" content="3; url=https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html">
+    <link rel="canonical" href="https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html">
+    <style>
+        body { 
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif; 
+            max-width: 600px; 
+            margin: 50px auto; 
+            padding: 20px;
+            line-height: 1.6;
+        }
+        .redirect-box { 
+            border: 2px solid #007acc; 
+            padding: 30px; 
+            border-radius: 8px; 
+            background: linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%);
+            box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+        }
+        .countdown { 
+            font-weight: bold; 
+            color: #007acc; 
+            font-size: 1.2em;
+        }
+        .manual-link {
+            display: inline-block;
+            background: #007acc;
+            color: white;
+            padding: 12px 24px;
+            text-decoration: none;
+            border-radius: 5px;
+            margin: 10px 0;
+            font-weight: bold;
+        }
+        .manual-link:hover {
+            background: #005c99;
+        }
+        h1 { color: #333; margin-top: 0; }
+        .progress-bar {
+            width: 100%;
+            height: 6px;
+            background: #ddd;
+            border-radius: 3px;
+            margin: 15px 0;
+            overflow: hidden;
+        }
+        .progress-fill {
+            height: 100%;
+            background: #007acc;
+            width: 100%;
+            transition: width 1s linear;
+        }
+    </style>
+    <script>
+        let seconds = 3;
+        function redirect() {
+            window.location.href = "https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html";
+        }
+        function updateCountdown() {
+            const countdownElement = document.getElementById('countdown');
+            const progressElement = document.getElementById('progress-fill');
+            
+            if (countdownElement) {
+                countdownElement.textContent = seconds;
+            }
+            if (progressElement) {
+                progressElement.style.width = ((3-seconds)/3 * 100) + '%';
+            }
+            
+            if (seconds <= 0) {
+                redirect();
+            } else {
+                seconds--;
+                setTimeout(updateCountdown, 1000);
+            }
+        }
+        window.onload = function() {
+            updateCountdown();
+            // Fallback redirect in case JavaScript fails
+            setTimeout(redirect, 3100);
+        }
+    </script>
+</head>
+<body>
+    <div class="redirect-box">
+        <h1>📄 Page Moved</h1>
+        <p>The <strong>Declarative vs Procedural Logic Comparison</strong> has moved to a new location.</p>
+        
+        <div class="progress-bar">
+            <div id="progress-fill" class="progress-fill" style="width: 0%;"></div>
+        </div>
+        
+        <p>Redirecting automatically in <span id="countdown" class="countdown">3</span> seconds...</p>
+        
+        <p><strong>If you are not redirected automatically:</strong></p>
+        <a href="https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html" class="manual-link">
+            👉 Go to New Location
+        </a>
+        
+        <hr style="margin: 25px 0; border: none; border-top: 1px solid #ddd;">
+        <p><small>
+            <strong>New URL:</strong><br>
+            <code>https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html</code>
+        </small></p>
+    </div>
+</body>
+</html>

api_logic_server_cli/prototypes/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/.vscode/settings.json

@@ -20,5 +20,5 @@
     "workbench.editorAssociations": {
         "*.md": "vscode.markdown.preview.editor"
     },
-    "workbench.colorTheme": "Visual Studio Light"
+    "workbench.colorTheme": "Arduino Light"
 }

api_logic_server_cli/prototypes/manager/{run_sample.sh → samples/docker_samples/run_sample_docker.sh}

@@ -14,8 +14,8 @@ if [ $# -eq 0 ]
     # echo "shell: $SHELL"
     echo " eg:"
     echo " "
-    echo "   > cd webgenai  # or ApiLogicServer"
-    echo "   > sh run_sample.sh nw_sample_nocust"
+    echo "   > cd ApiLogicServer # ONLY if already running under docker"
+    echo "   > sh samples/docker_samples/run_sample_docker.sh nw_sample_nocust"
     echo " "
     exit 0
 fi
@@ -26,5 +26,5 @@ if [ "$1" = "$" ]
     sample="nw_sample"
   fi
 
-cd samples/$sample
-docker run -it --rm --name api_logic_project -p 5656:5656 --env-file ./devops/docker-standard-image/env.list -v ./:/app apilogicserver/web_genai python3 /app/api_logic_server_run.py
+pushd samples/$sample
+docker run -it --rm --name api_logic_project_${sample}_$(date +%s) -p 5656:5656 --env-file ./devops/docker-standard-image/env.list -v ./:/app apilogicserver/web_genai python3 /app/api_logic_server_run.py

api_logic_server_cli/prototypes/manager/samples/docker_samples/run_web_genai.sh

@@ -0,0 +1,5 @@
+# Run WebGenAI docker container
+
+# sh samples/docker_samples/run_web_genai.sh
+
+docker compose -f webgenai/docker-compose.yml up

api_logic_server_cli/prototypes/manager/samples/prompts/add_email.prompt

@@ -0,0 +1,8 @@
+Create a table SysEmail in `database/db.sqlite` as a child of customer, 
+with columns id, message, subject, customer_id and CreatedOn.
+
+Add an after_flush event on SysEmail to produce a log message "email sent",
+unless the customer has opted out.
+
+List the orders date_shipped is null and CreatedOn before 2023-07-14, 
+and send a discount email (subject: 'Discount Offer') to the customer for each one.

api_logic_server_cli/prototypes/manager/samples/prompts/elections.prompt

@@ -0,0 +1,3 @@
+Create a Star wars themed presidential election app.
+
+Create at least 15 tables.

api_logic_server_cli/prototypes/manager/samples/prompts/emp_dept.prompt

@@ -0,0 +1,4 @@
+System for Departments and Employees.
+
+LogicBank:
+1. Sum of employee salaries cannot exceed department budget

api_logic_server_cli/prototypes/manager/samples/prompts/genai_demo.prompt

@@ -0,0 +1,13 @@
+Create a system with customers, orders, items and products.
+
+Include a notes field for orders.
+
+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.