ApiLogicServer 15.2.3__py3-none-any.whl → 15.2.10__py3-none-any.whl

api_logic_server_cli/prototypes/manager/.github/.copilot-instructions.md

@@ -1,20 +1,49 @@
+---
+title: Copilot Instructions for Manager Workspace
+Description: Manager-level instructions for creating projects
+Source: ApiLogicServer-src/prototypes/manager/.github/.copilot-instructions.md
+Propagation: BLT process → Manager workspace
+Usage: AI assistants read this when user opens Manager workspace
+version: 2.1
+changelog:
+  - 2.1 (Oct 2025) - Added "What is the Project Manager?" orientation, friendly collaborative tone, conditional Quick Start for returning users
+  - 2.0 (Oct 2025) - OBX improvements, strengthen basic_demo as default path
+  - 1.0 (Initial) - Established project creation methods
+---
+
 # GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) - Project Manager
 
-⚠️ **IMPORTANT FOR AI ASSISTANTS**: Always read and follow these instructions when helping users with this project.
+⚠️ **IMPORTANT FOR AI ASSISTANTS**: Always read and follow these instructions when helping with this project.
+
+## What is the Project Manager?
+
+Welcome! This is the **Project Manager** - think of it as your workspace for creating and managing API Logic Server projects.
+
+**What's here:**
+- Sample databases you can use to create projects (`samples/dbs/`)
+- Training materials and examples (`system/genai/examples/`)
+- A shared virtual environment for all your projects (`venv/`)
+- A place to create new projects (they'll appear as subdirectories)
 
-The Project Manager contains genai training, a virtual environment, and provides a convenient place to create projects.
+**What you'll do here:**
+Create projects from databases - each project becomes a complete, working microservice with API, Admin UI, and business logic support. Once created, you'll work inside that project to customize and extend it.
 
-> Note: your virtual environment is automatically configured in most cases; verify it with `genai-logic` - it it's not there, activate the `venv` in this project.
+> Note: Your virtual environment is automatically configured in most cases; verify it with `genai-logic` - if it's not there, activate the `venv` in this project.
 
-## Quick Start for New Users
+## Quick Start
 
-**ALWAYS start new users with the basic_demo** - it's the best introduction to the system.
+**First time here?** Let's start with the 20-minute basic_demo tutorial - it's the best way to see what GenAI-Logic can do.
 
-It's a small sqlite database, and provides a readme that explores the project, and how to customize it:
+Run this command:
 
 ```bash
 genai-logic create --project_name=basic_demo --db_url=basic_demo
 ```
+
+After it runs, the project will auto-open with its own README and I'll guide you through a hands-on tour.
+
+**Already have basic_demo?** Open it and say "Guide me through basic_demo" for the hands-on tour, or ask me what else we can work on.
+
 <br>
 
 ## Creating Projects
@@ -27,7 +56,7 @@ There are multiple ways to create projects (aka systems, microservices) - see th
 
 ### Method 1: Create Projects from an existing database (Infrastructure Only)
 
-If the user provides a database reference, use the command below.  (Note: sqlite sample databases at `samples/dbs`). 
+If you have a database reference, I can create a project from it. (Sample databases are in `samples/dbs`). 
 
 ```bash
 genai-logic create  --project_name=nw --db_url=sqlite:///samples/dbs/nw.sqlite
@@ -35,13 +64,11 @@ genai-logic create  --project_name=nw --db_url=sqlite:///samples/dbs/nw.sqlite
 
 **Important:** This creates the project structure, API, Admin App, and database models, but **NO business logic rules**.
 
-**To add logic:** Users must add rules separately using:
-- Natural language with Copilot/AI assistant in `logic/declare_logic.py`, or
-- Manual coding with IDE code completion
+**To add logic:** We can add rules together using natural language in `logic/declare_logic.py`, or you can code them manually with IDE autocomplete.
 
 ### Method 2: Create Projects with GenAI (Complete System with Logic)
 
-**Use this when the user provides both database AND business logic requirements.**
+**Use this when you have both database AND business logic requirements.**
 
 Describe database and logic in Natural Language in a prompt file.
 
@@ -58,25 +85,25 @@ genai-logic genai --using=system/genai/examples/genai_demo/genai_demo.prompt --p
 4. Creates test data
 5. Creates API, Admin App, and complete project structure
 
-**When to use:** User provides requirements like "Customer balance is sum of orders" or "Check credit limit" - the LLM will generate the corresponding `Rule.sum`, `Rule.constraint`, etc.
+**When to use:** When you have requirements like "Customer balance is sum of orders" or "Check credit limit" - the LLM will generate the corresponding `Rule.sum`, `Rule.constraint`, etc.
 
 ### Method 3: Create Projects with new databases (Manual Approach)
 
-If the user provides a description but you want to create the database manually:
+If you provide a description but want to create the database manually:
 
-1. Create a sqlite database from the description.  Be sure to include foreign keys.  The system works well with `id INTEGER PRIMARY KEY AUTOINCREMENT`.
-2. Then, use the `genai-logic create` command above.
-3. If logic is provided, translate it using Copilot or `system/genai/learning_requests/logic_bank_api.prompt`.
+1. I'll create a sqlite database from your description. I'll be sure to include foreign keys. The system works well with `id INTEGER PRIMARY KEY AUTOINCREMENT`.
+2. Then, I'll use the `genai-logic create` command above.
+3. If you have logic requirements, we can translate them together using `system/genai/learning_requests/logic_bank_api.prompt`.
 
-## AI Assistant Guidelines
+## Working Together
 
-When users ask "what do I do now?" or similar questions:
+When you ask "what should I do now?" or similar:
 
-1. **Always recommend starting with basic_demo** using the command above
-2. **Use CLI commands** (genai-logic) not Docker scripts for project creation
-3. **Refer to existing sample databases** in `samples/dbs/` for examples
-4. **Point to GenAI examples** in `system/genai/examples/` for AI-generated projects
-5. **Emphasize the 20-minute evaluation workflow** described in the main README
+1. **I'll recommend starting with basic_demo** using the command above
+2. **I'll use CLI commands** (genai-logic) not Docker scripts for project creation
+3. **I'll point you to sample databases** in `samples/dbs/` for examples
+4. **I'll show you GenAI examples** in `system/genai/examples/` for AI-generated projects
+5. **We'll follow the 20-minute workflow** described in the main README
 
 ## Available Databases
 - `basic_demo` - Best for first-time users

api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/.github/.copilot-instructions.md

@@ -26,6 +26,9 @@ This is a **GenAI-Logic (aka API Logic Server) project** - a complete, working m
 
 3. **Automatic Business Logic**: All APIs (standard and custom) automatically inherit LogicBank rules without additional code.
 
+4. **CLI Commands**: Use `genai-logic --help` to see all available commands. When CLI commands exist for a task (e.g., `add-auth`, `genai-add-mcp-client`, `genai-add-app`), ALWAYS use them instead of manual configuration - they handle all setup correctly.
+
+
 ## ⚠️ IMPORTANT: What's Already Built
 
 **DO NOT recreate these - they're already working:**

api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/customizations/logic/declare_logic.py

@@ -32,7 +32,23 @@ def declare_logic():
         from logic.logic_discovery.auto_discovery import discover_logic
         discover_logic()
 
-    # Logic from GenAI: (or, use your IDE w/ code completion)
+    # Logic from GenAI
+    '''
+    You can enter logic in 2 ways:
+        1. Using your IDE and code completion (Rule.)
+
+        2. Use your AI Assistant and enter logic in Natural Language, e.g.:
+            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.
+    Also, using logic/logic_discovery is a Best Practice - see logic/readme_logic.md
+    '''
     from database.models import Product, Order, Item, Customer, SysEmail
 
     # Ensure the customer's balance is less than their credit limit

api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/docs/training/testing.md

@@ -32,6 +32,9 @@ Step 5.  SUGGEST how to run tests (DO NOT run automatically)
   - [ ] @when patterns: carbon neutral > multi-item > single-item
   - [ ] @given patterns: multi-item > single-item
   - [ ] Use `grep -n "@when('.*with" steps/*.py` to verify order
+- [ ] **Clear scenario language?** (Rule #13: Action-oriented wording)
+  - [ ] Use "Order is created" not "Order exists" (shows when rules fire)
+  - [ ] Makes test flow obvious: setup → action → verify
 - [ ] Test data uses timestamps? (Rule #0: Repeatability)
 - [ ] Security config read? (SECURITY_ENABLED value)
 
@@ -167,7 +170,7 @@ def step_impl(context, qty):
     r = requests.patch(url=patch_uri, json=patch_data)
 ```
 
-## The 6 Critical Rules (Read FIRST!)
+## The Critical Rules (Read FIRST!)
 
 ### Rule #0: TEST REPEATABILITY (MOST CRITICAL!) ⚠️
 
@@ -386,18 +389,65 @@ Scenario: Exceed Credit (Constraint FAIL - negative test)
 
 **CRITICAL:** Check `logic/declare_logic.py` for custom Python logic affecting calculations (e.g., discounts, adjustments) before writing constraint test expectations!
 
-### Rule #5: Security Configuration
+### Rule #5: Security Configuration - JWT Authentication
+
+**CRITICAL:** When `SECURITY_ENABLED=True`, tests MUST obtain JWT token and include Authorization header.
+
 ```python
-# Read config/default.env FIRST
-SECURITY_ENABLED = False  # or True
+from pathlib import Path
+import os
+from dotenv import load_dotenv
 
-# Match in test code
-if SECURITY_ENABLED == False:
-    headers = {}  # Empty
-else:
-    headers = test_utils.login()
+# Load config to check SECURITY_ENABLED
+config_path = Path(__file__).parent.parent.parent.parent.parent / 'config' / 'default.env'
+load_dotenv(config_path)
+
+# Cache for auth token (obtained once per test session)
+_auth_token = None
+
+def get_auth_token():
+    """Login and get JWT token if security is enabled"""
+    global _auth_token
+    
+    if _auth_token is not None:
+        return _auth_token
+    
+    # Login with default admin credentials
+    login_url = f'{BASE_URL}/api/auth/login'
+    login_data = {'username': 'admin', 'password': 'p'}
+    
+    response = requests.post(login_url, json=login_data)
+    if response.status_code == 200:
+        _auth_token = response.json().get('access_token')
+        return _auth_token
+    else:
+        raise Exception(f"Login failed: {response.status_code}")
+
+def get_headers():
+    """Get headers including auth token if security is enabled"""
+    security_enabled = os.getenv('SECURITY_ENABLED', 'false').lower() not in ['false', 'no']
+    
+    headers = {'Content-Type': 'application/json'}
+    
+    if security_enabled:
+        token = get_auth_token()
+        if token:
+            headers['Authorization'] = f'Bearer {token}'
+    
+    return headers
+
+# Use in ALL API requests
+response = requests.post(url=api_url, json=data, headers=get_headers())
+response = requests.get(url=api_url, headers=get_headers())
+response = requests.patch(url=api_url, json=data, headers=get_headers())
 ```
 
+**Key Points:**
+- Tests DO NOT automatically include auth - you must code the pattern above
+- Token is cached globally to avoid repeated login calls
+- Works for both `SECURITY_ENABLED=True` and `SECURITY_ENABLED=False`
+- See complete example: `test/api_logic_server_behave/features/steps/order_processing_steps.py`
+
 ### Rule #6: Logic Logging
 ```python
 @when('Good Order Placed')
@@ -535,6 +585,40 @@ def step_impl(context):
         return  # Skip gracefully
 ```
 
+### Rule #13: Use Clear, Action-Oriented Scenario Language ⚠️ NEW
+```gherkin
+# ❌ AMBIGUOUS - "exists" is passive, doesn't show when balance changes
+Scenario: Ship Order Excludes from Balance
+  Given Customer "Charlie" with balance 0 and credit limit 2000
+  And Order exists for "Charlie" with 2 Widget
+  When Order is shipped
+  Then Customer balance should be 0
+
+# Question: How can Charlie have balance 0 AND an order for widgets?
+# Answer: The order EXISTS at test start, but balance calculation is unclear
+
+# ✅ CLEAR - "is created" shows action that triggers rule
+Scenario: Ship Order Excludes from Balance
+  Given Customer "Charlie" with balance 0 and credit limit 2000
+  And Order is created for "Charlie" with 2 Widget  # Action! Balance becomes 180
+  When Order is shipped                              # Action! Balance drops to 0
+  Then Customer balance should be 0                  # Verification
+
+# Now it's obvious:
+# 1. Customer starts with balance 0
+# 2. Creating unshipped order → rule fires → balance becomes 180
+# 3. Shipping order → WHERE clause excludes it → balance drops to 0
+
+# More examples:
+# ❌ "And Shipped order exists for..."
+# ✅ "And Shipped order is created for..."
+
+# Why this matters:
+# - Shows WHEN rules fire (on creation, not just existence)
+# - Makes test flow obvious (setup → action → verify)
+# - Clarifies that declarative rules execute automatically on changes
+```
+
 ## Complete Phase 2 Example
 
 ### .feature File
@@ -631,6 +715,8 @@ def step_impl(context, expected):
 | **"balance: expected 570, got 0.0"** | **Step ordering issue (Rule #0.5)! Multi-item pattern after single-item** |
 | **"context has no attribute 'item_id'"** | **Step ordering issue! Specific pattern defined after general pattern** |
 | "Order created but no items" | Check if wrong step matched (print debug in step) |
+| **"expected 810, got 900"** (carbon neutral) | **Rule #10: Verify actual database values! Check product flags with SQL first** |
+| **"How can balance be 0 with an order?"** | **Rule #13: Use "is created" not "exists" - shows when rules fire** |
 
 ### Debugging Step Ordering Issues
 

api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/iteration/logic/declare_logic.py

@@ -32,7 +32,23 @@ def declare_logic():
         from logic.logic_discovery.auto_discovery import discover_logic
         discover_logic()
 
-    # Logic from GenAI: (or, use your IDE w/ code completion)
+    # Logic from GenAI
+    '''
+    You can enter logic in 2 ways:
+        1. Using your IDE and code completion (Rule.)
+
+        2. Use your AI Assistant and enter logic in Natural Language, e.g.:
+            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.
+    Also, using logic/logic_discovery is a Best Practice - see logic/readme_logic.md
+    '''
     from database.models import Product, Order, Item, Customer
 
     # Ensure the customer's balance is less than their credit limit

api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/logic/declare_logic.py

@@ -31,6 +31,43 @@ def declare_logic():
         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
+
+
+
+    # ************   Python Customization Example ****************
+
+    # Send order details to Kafka if order is shipped.
+    # Formeraly, we had this rule:
+    #       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'})
+    # If the integration were more complex, we could use Python, like this:
+    #als: Demonstrate that logic == Rules + Python (for extensibility)
+
+    def send_order_to_shipping(row: models.Order, old_row: models.Order, logic_row: LogicRow):
+        """ #als: Send Kafka message formatted by OrderShipping RowDictMapper
+
+        Format row per shipping requirements, and send (e.g., a message)
+
+        NB: the after_flush event makes Order.Id avaible.
+
+        Args:
+            row (models.Order): inserted Order
+            old_row (models.Order): n/a
+            logic_row (LogicRow): bundles curr/old row, with ins/upd/dlt logic
+        """
+        if logic_row.is_inserted():
+            kafka_producer.send_kafka_message(logic_row=logic_row,
+                                              row_dict_mapper=OrderShipping,
+                                              kafka_topic="order_shipping",
+                                              kafka_key=str(row.id),
+                                              msg="Sending Order to Shipping")
+            
+    Rule.after_flush_row_event(on_class=models.Order, calling=send_order_to_shipping)  # see above
+
+    # End Logic from GenAI
+
+
     def handle_all(logic_row: LogicRow):  # #als: TIME / DATE STAMPING, OPTIMISTIC LOCKING
         """
         This is generic - executed for all classes.
@@ -53,7 +90,7 @@ def declare_logic():
         Grant.process_updates(logic_row=logic_row)
 
         did_stamping = False
-        if enable_stamping := False:  # #als:  DATE / USER STAMPING
+        if enable_stamping := True:  # #als:  DATE / USER STAMPING
             row = logic_row.row
             if logic_row.ins_upd_dlt == "ins" and hasattr(row, "CreatedOn"):
                 row.CreatedOn = datetime.datetime.now()

api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/test/api_logic_server_behave/features/order_processing.feature

@@ -1,72 +1,81 @@
 Feature: Order Processing with Business Logic
 
-  # Phase 2: CREATE using OrderB2B custom API
-  # Phase 1: UPDATE/DELETE using CRUD for granular rule testing
+  # Tests all declarative rules:
+  # 1. Customer.balance = sum(Order.amount_total) WHERE date_shipped is None
+  # 2. Order.amount_total = sum(Item.amount)
+  # 3. Item.amount = quantity * unit_price (with 10% carbon neutral discount for qty >= 10)
+  # 4. Item.unit_price copied from Product.unit_price
+  # 5. Customer.balance <= credit_limit constraint
+  # 6. Kafka integration when order shipped
 
   Scenario: Good Order Placed via B2B API
-    Given Customer "Alice" with balance 0 and credit limit 1000
+    Given Customer "Alice" with balance 0 and credit limit 5000
     When B2B order placed for "Alice" with 5 Widget
     Then Customer balance should be 450
     And Order amount_total should be 450
-    And Order created successfully
+    And Item amount should be 450
+    And Item unit_price should be 90
 
-  Scenario: Item Quantity Update Recalculates Amounts
-    Given Customer "Bob" with balance 0 and credit limit 2000
-    And Order exists for "Bob" with 5 Widget
+  Scenario: Multi-Item Order via B2B API
+    Given Customer "Bob" with balance 0 and credit limit 3000
+    When B2B order placed for "Bob" with 3 Widget and 2 Gadget
+    Then Customer balance should be 570
+    And Order amount_total should be 570
+
+  Scenario: Carbon Neutral Discount Applied
+    Given Customer "Diana" with balance 0 and credit limit 5000
+    When B2B order placed for "Diana" with 10 carbon neutral Gadget
+    Then Customer balance should be 1350
+    And Item amount should be 1350
+    
+  Scenario: Item Quantity Change
+    Given Customer "Charlie" with balance 0 and credit limit 2000
+    And Order is created for "Charlie" with 5 Widget
     When Item quantity changed to 10
     Then Item amount should be 900
     And Order amount_total should be 900
     And Customer balance should be 900
 
-  Scenario: Change Order Customer Adjusts Both Balances
-    Given Customer "Charlie" with balance 0 and credit limit 1500
-    And Customer "Diana" with balance 0 and credit limit 2000
-    And Order exists for "Charlie" with 2 Gadget
-    When Order customer changed to "Diana"
-    Then Customer "Charlie" balance should be 0
-    And Customer "Diana" balance should be 300
+  Scenario: Change Product in Item
+    Given Customer "Alice" with balance 0 and credit limit 5000
+    And Order is created for "Alice" with 5 Widget
+    When Item product changed to "Gadget"
+    Then Item unit_price should be 150
+    And Item amount should be 750
+    And Order amount_total should be 750
+    And Customer balance should be 750
 
-  Scenario: Delete Item Reduces Order Total and Customer Balance
-    Given Customer "TestCustomer" with balance 0 and credit limit 3000
-    And Order exists for "TestCustomer" with 3 Widget and 2 Gadget
-    When First item deleted
+  Scenario: Delete Item Reduces Order
+    Given Customer "Bob" with balance 0 and credit limit 3000
+    And Order is created for "Bob" with 3 Widget and 2 Gadget
+    When First item is deleted
     Then Order amount_total should be 300
     And Customer balance should be 300
 
-  Scenario: Ship Order Excludes from Balance (WHERE exclude)
-    Given Customer "ShipTest" with balance 0 and credit limit 5000
-    And Order exists for "ShipTest" with 10 Widget
+  Scenario: Change Order Customer
+    Given Customer "Alice" with balance 0 and credit limit 5000
+    And Customer "Bob" with balance 0 and credit limit 3000
+    And Order is created for "Alice" with 5 Widget
+    When Order customer changed to "Bob"
+    Then Customer "Alice" balance should be 0
+    And Customer "Bob" balance should be 450
+
+  Scenario: Ship Order Excludes from Balance
+    Given Customer "Charlie" with balance 0 and credit limit 2000
+    And Order is created for "Charlie" with 2 Widget
     When Order is shipped
     Then Customer balance should be 0
+    And Order amount_total should be 180
 
-  Scenario: Unship Order Includes in Balance (WHERE include)
-    Given Customer "UnshipTest" with balance 0 and credit limit 5000
-    And Shipped order exists for "UnshipTest" with 5 Gadget
+  Scenario: Unship Order Includes in Balance
+    Given Customer "Diana" with balance 0 and credit limit 5000
+    And Shipped order is created for "Diana" with 3 Gadget
     When Order is unshipped
-    Then Customer balance should be 750
-
-  Scenario: Exceed Credit Limit Rejected (Constraint FAIL)
-    Given Customer "LimitTest" with balance 0 and credit limit 500
-    When B2B order placed for "LimitTest" with 10 Gadget
-    Then Order creation should fail
-    And Error message should contain "credit limit"
-
-  Scenario: Carbon Neutral Discount Applied (Custom Logic)
-    Given Customer "GreenBuyer" with balance 0 and credit limit 2000
-    When B2B order placed for "GreenBuyer" with 10 carbon neutral Gadget
-    Then Item amount should be 1350
-    And Order amount_total should be 1350
-    And Customer balance should be 1350
-
-  Scenario: Product Unit Price Copied to Item
-    Given Customer "PriceCopy" with balance 0 and credit limit 3000
-    When B2B order placed for "PriceCopy" with 1 Green
-    Then Item unit_price should be 109
+    Then Customer balance should be 450
+    And Order amount_total should be 450
 
-  Scenario: Change Product Updates Unit Price (FK Change)
-    Given Customer "ProductChange" with balance 0 and credit limit 5000
-    And Order exists for "ProductChange" with 2 Widget
-    When Item product changed to "Gadget"
-    Then Item unit_price should be 150
-    And Item amount should be 300
-    And Order amount_total should be 300
+  Scenario: Exceed Credit Limit Rejected
+    Given Customer "Silent" with balance 0 and credit limit 1000
+    When B2B order placed for "Silent" with 20 Widget
+    Then Order should be rejected
+    And Error message should contain "exceeds credit limit"