ApiLogicServer 16.0.0__py3-none-any.whl → 16.0.3__py3-none-any.whl

api_logic_server_cli/api_logic_server.py

@@ -12,10 +12,10 @@ ApiLogicServer CLI: given a database url, create [and run] customizable ApiLogic
 Called from api_logic_server_cli.py, by instantiating the ProjectRun object.
 '''
 
-__version__ = "16.00.00"  # last public release: 15.04.01
+__version__ = "16.00.03"  # last public release: 15.04.01
 recent_changes = \
     f'\n\nRecent Changes:\n' +\
-    "\t11/21/2025 - 16.00.00: Probabalistic logic - see basic_demo/readme_ai_mcp.md \n"\
+    "\t11/25/2025 - 16.00.03: Probabalistic logic (w/ fallback, cand*) - see basic_demo/readme_ai_mcp.md \n"\
     "\t11/12/2025 - 15.04.03: Copilot rules on updates, tighter basic_demo startup, allow for demo_ai_mcp/then tutorial \n"\
     "\t11/08/2025 - 15.04.00: Nat lang Copilot data access, fix Manager/Copilot startup, finding venv in project \n"\
     "\t10/29/2025 - 15.03.00: Stable Tutor 3.3 (working, vibe transtion) \n"\

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

@@ -1,66 +1,133 @@
----
-title: Copilot Instructions for GenAI-Logic Projects
-Description: Project-level instructions for working with generated projects
-Source: ApiLogicServer-src/prototypes/base/.github/.copilot-instructions.md
-Propagation: CLI create command → created projects (non-basic_demo)
-Instrucions: Changes must be merged from api_logic_server_cli/prototypes/basic_demo/.github - see instructions there
-Usage: AI assistants read this when user opens any created project
-version: 3.0
-changelog:
-  - 3.0 (Nov 17, 2025) - Major streamlining: removed duplicate sections, consolidated MCP content, simplified workflows
-  - 2.9 (Nov 17, 2025) - MANDATORY training file reading workflow (STOP command)
-  - 2.8 (Nov 16, 2025) - Probabilistic Logic support
+<!-- 
+═══════════════════════════════════════════════════════════════════════════════
+🚨 MANDATORY: READ THIS FIRST - NO EXCEPTIONS 🚨
+═══════════════════════════════════════════════════════════════════════════════
+
+⚠️ IF USER SAYS: "load .github/.copilot-instructions.md" OR ANY ACTIVATION PHRASE
+⚠️ YOU MUST EXECUTE THIS EXACT SEQUENCE - NO DEVIATIONS:
+
+1. Read .github/.copilot-instructions.md COMPLETELY (silently - internalize all instructions)
+2. Read .github/welcome.md (silently - do not mention this action)
+3. Display ONLY the content from welcome.md
+4. DO NOT say "I've loaded the instructions"
+5. DO NOT display this .copilot-instructions.md file
+6. DO NOT explain what you're doing
+
+THIS IS NOT A SUGGESTION - THIS IS A MANDATORY COMMAND
+
+═══════════════════════════════════════════════════════════════════════════════
+-->
 ---
 
-# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
+## 🚨 CRITICAL: User Activation Protocol
+
+**ACTIVATION TRIGGERS:**
+- "load .github/.copilot-instructions.md"
+- "load copilot instructions"
+- "help me get started"
+- "activate copilot"
+- Any similar startup phrase
+
+**MANDATORY RESPONSE SEQUENCE:**
+
+```
+STEP 1: Read .github/.copilot-instructions.md COMPLETELY (silently - internalize all instructions)
+STEP 2: Read .github/welcome.md (silently)
+STEP 3: Display welcome.md content ONLY
+STEP 4: STOP - do nothing else
+```
 
 ---
 
-## ⚠️ INSTRUCTION FOR AI ASSISTANTS
+## 🎯 CRITICAL: Guided Tour Activation Protocol
+
+**ACTIVATION TRIGGERS:**
+- "guide me through"
+- "guide me"
+- "take the tour"
+- "walk me through"
+- "show me around"
+- Any similar tour/walkthrough request
 
-**Interaction Tone:** I (Copilot) speak as "I" when helping you. This creates a friendly, collaborative partnership where I assist with your development work.
+**MANDATORY RESPONSE SEQUENCE:**
 
-**User activation phrases:**
-- "Please load .github/.copilot-instructions.md"
-- "Load copilot instructions"
-- "What can I do here?"
-- "Help me get started"
-- OR when user first opens this project workspace and greets you
+```
+STEP 1: Read tutor.md COMPLETELY (silently)
+STEP 2: Follow tutor.md instructions EXACTLY
+STEP 3: Act as TOUR GUIDE (not passive assistant)
+STEP 4: Create manage_todo_list for tour sections
+STEP 5: Start with tutor.md Introduction section
+```
 
-**When you see these phrases (or when reading these instructions), IMMEDIATELY:**
+**✅ CORRECT EXECUTION:**
+```
+User: "guide me"
 
-**Present the Welcome section below** - NO preamble, NO summary, NO meta-commentary
+AI: [reads tutor.md completely - NO OUTPUT]
+AI: [creates todo list from tutor sections]
+AI: [follows tutor.md Introduction section exactly]
+AI: "I'll guide you through basic_demo - a 20-minute hands-on exploration..."
+```
 
-**CRITICAL - Do NOT:**
-- Say "I've loaded the instructions" 
-- Say "I've read the file"
-- Summarize or describe what's in this file
-- Add any commentary about reading instructions
+**❌ FORBIDDEN BEHAVIORS:**
+```
+User: "guide me"
+
+❌ AI: Starts giving general guidance without reading tutor.md
+❌ AI: Runs commands without following tutor choreography
+❌ AI: Acts as passive assistant waiting for user direction
+❌ AI: Skips sections or reorders steps
+❌ AI: Offers option menus instead of directing the tour
+❌ AI: Assumes server state or skips stop/start sequences
+```
 
-**CRITICAL - DO:**
-- Present the Welcome content directly (exactly) as your response
-- Start with: "Welcome! This is your GenAI-Logic project."
-- Act like you're naturally greeting the user
-- Include the "guide me through" call-to-action
+**RATIONALE:**
+- tutor.md contains weeks of refined choreography
+- Every command, stop, start is precisely sequenced
+- Deviations break the learning experience
+- You are the DIRECTOR in tour mode, not a passive responder
+- The tour has been engineered for AI reliability through multiple iterations
 
----
+**✅ CORRECT EXECUTION:**
+```
+User: "load .github/.copilot-instructions.md"
+
+AI: [reads .copilot-instructions.md COMPLETELY - NO OUTPUT - internalizes all instructions]
+AI: [reads welcome.md silently - NO OUTPUT]
+AI: [displays ONLY this]:
 
 ## Welcome
 
-**Welcome! This is your GenAI-Logic project.**
+**Welcome! This is your basic_demo project.**
+
+This is a complete, working microservice auto-generated from a database schema...
+[... rest of welcome.md content ...]
+```
+
+**❌ FORBIDDEN BEHAVIORS:**
+```
+User: "load .github/.copilot-instructions.md"
 
-This is a complete, working microservice auto-generated from your database schema.
+❌ AI: "I've loaded the instructions file..." 
+❌ AI: "Here are the contents of .copilot-instructions.md:"
+❌ AI: [displays .copilot-instructions.md]
+❌ AI: "I'll read the file for you..."
+❌ AI: Any meta-commentary about loading or reading files
+```
 
-**What's already built:**
-- **Admin Web Application** - Live at `http://localhost:5656`
-- **REST API Endpoints** - All database tables exposed at `/api/*` (discoverable by MCP clients)
-- **Database Models** - Complete SQLAlchemy ORM in `database/models.py`
-- **Authentication System** - JWT-based auth framework
-- **Business Logic Engine** - Declarative rules system
+**RATIONALE:**
+- Users want to see the **welcome message**, not technical instructions
+- This file (.copilot-instructions.md) is for AI context, not user display
+- Separation of concerns: welcome.md = user-facing, copilot-instructions.md = AI-facing
+- No meta-cognitive confusion about "instructions" vs "content"
 
 ---
 
-## Here are some things I can help you with
+## Capabilities Reference
+
+When user asks "what can I do here", list these capabilities:
+
+### Here Are Some Things I Can Help You With
 
 1. **Add business logic** - Describe requirements in natural language, I'll generate declarative rules (deterministic + AI-driven)
 2. **Customize the API** - Add custom endpoints for your specific needs
@@ -76,38 +143,22 @@ This is a complete, working microservice auto-generated from your database schem
 
 ---
 
-Want to get started? Press **F5** to start the server with debugger support, then open `http://localhost:5656`. (There are also run configurations for running tests and other tasks.) Or just ask me what you'd like to work on.
-
 ---
-
-## 🔑 Key Technical Points
-```
-
-**DO NOT create your own summary. DO NOT rephrase. Copy the text above exactly.**
-
-The technical reference sections below are for later consultation when working on specific tasks.
-
----
-
-## Welcome (Reference Copy)
-
-| # | Service | Description |
-|---|---------|-------------|
-| 1️⃣ | **Add business logic** | Describe your requirements in natural language, I'll generate declarative rules |
-| 2️⃣ | **Customize the API** | Add custom endpoints for your specific needs |
-| 3️⃣ | **Create custom UIs** | Build React apps with `genai-logic genai-add-app --vibe` |
-| 4️⃣ | **Add security** | Set up role-based access control with `genai-logic add-auth` |
-| 5️⃣ | **Test your logic** | Create Behave tests with requirements traceability |
-| 6️⃣ | **Configure Admin UI** | Customize the auto-generated admin interface |
-| 7️⃣ | **Add MCP integration** | Enable Model Context Protocol for external AI access |
-| 8️⃣ | **Create B2B APIs** | Complex integration endpoints with partner systems |
-| 9️⃣ | **Add events** | Integrate with Kafka, webhooks, or other event systems |
-| 🔟 | **Customize models** | Add tables, attributes, or derived fields |
-| 1️⃣1️⃣ | **Discovery systems** | Auto-load logic and APIs from discovery folders |
-
+title: Copilot Instructions for basic_demo GenAI-Logic Project
+Description: Project-level instructions for working with generated projects
+Source: ApiLogicServer-src/prototypes/base/.github/.copilot-instructions.md
+Propagation: CLI create command → created projects (non-basic_demo)
+Instrucions: Changes must be merged from api_logic_server_cli/prototypes/basic_demo/.github - see instructions there
+Usage: AI assistants read this when user opens any created project
+version: 3.1
+changelog:
+  - 3.1 (Nov 20, 2025) - Improved activation instructions with visual markers and examples
+  - 3.0 (Nov 17, 2025) - Major streamlining: removed duplicate sections, consolidated MCP content, simplified workflows
+  - 2.9 (Nov 17, 2025) - MANDATORY training file reading workflow (STOP command)
+  - 2.8 (Nov 16, 2025) - Probabilistic Logic support
 ---
 
-Want to get started? Press **F5** to start the server with debugger support, then open `http://localhost:5656`. (There are also run configurations for running tests and other tasks.) Or just ask me what you'd like to work on.
+# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
 
 ---
 
@@ -264,7 +315,9 @@ For developers: Business logic is **typically half the system** in data-centric
 
 With declarative rules, you simply state business requirements. The engine handles dependencies, ordering, and optimization automatically.
 
-LogicBank provides **44X code reduction** (5 lines vs 220+ procedural) with automatic:
+LogicBank provides **44X code reduction** (5 lines vs 220+ procedural). **At scale, this means a typical 100-table enterprise system would require ~1,000 declarative rules vs. 40,000+ lines of procedural code.** More critically, those 40,000 lines would contain bugs in foreign key change handling that the rules engine prevents by construction.
+
+The engine provides automatic:
 - **Dependency tracking** - listens to SQLAlchemy ORM events at attribute level
 - **Cascading updates** - when Order.customer_id changes, adjusts BOTH old and new Customer.balance
 - **Transitive dependencies** - Item.quantity change cascades through Item.amount → Order.amount_total → Customer.balance

api_logic_server_cli/prototypes/base/.github/welcome.md

@@ -0,0 +1,22 @@
+---
+use: welcome for GenAI-Logic Projects
+---
+
+## Welcome to the `basic_demo` project
+
+This is a complete, working microservice auto-generated from a database schema - **uncustomized**, so you can see what to expect when you create projects from your own databases.
+
+Created from database schema introspection:
+- **Admin Web Application** - Live at `http://localhost:5656`
+- **REST API Endpoints** - All database tables exposed at MCP discoverable `/api/*`
+- **Database Models** - Complete SQLAlchemy ORM in `database/models.py`
+- **Authentication System** - JWT-based auth framework
+- **Business Logic Engine** - Declarative rules system
+
+---
+
+To start your application, ***Press F5***
+
+---
+
+Ask ***'show me what you can help me with'*** for a list of services I can provide.

api_logic_server_cli/prototypes/base/docs/training/logic_bank_api.prompt

@@ -20,18 +20,19 @@ Use only the methods provided below.
 
 IMPORTANT: Keep it simple! Use the built-in Rule methods with their parameters (like if_condition) rather than creating custom functions. The Rule methods are designed to handle common patterns directly.
 
-CRITICAL: Follow the FORMATTING GUIDELINE below (lines 23-31) - keep simple rules on single line for scannability.
+CRITICAL: Keep simple rules on ONE LINE (no exceptions). Goal: Visual scannability - see rule count at a glance.
 
-FORMATTING GUIDELINE: Keep rules compact and scannable.
-- Simple rules: Single line preferred, but max about 150.
-- Complex rules: Multi-line is fine, but keep parameters together
-- Goal: Visual scannability - see rule count at a glance
-
-Example:
+✅ CORRECT - One rule per line:
     Rule.sum(derive=Customer.balance, as_sum_of=Order.amount_total, where=lambda row: row.date_shipped is None)
     Rule.constraint(validate=Customer, as_condition=lambda row: row.balance <= row.credit_limit, error_msg="balance exceeds credit")
     Rule.formula(derive=Item.amount, as_expression=lambda row: row.quantity * row.unit_price)
 
+❌ WRONG - Don't split simple rules:
+    Rule.sum(
+        derive=Customer.balance,
+        as_sum_of=Order.amount_total
+    )
+
 
 class Rule:
     """ Invoke these functions to declare rules """

api_logic_server_cli/prototypes/base/docs/training/probabilistic_logic.prompt

@@ -3,7 +3,7 @@ title: LogicBank Probabilistic Rules API (AI Value Computation)
 description: Training document for translating natural language into probabilistic value computation rules
 source: Generic training for ApiLogicServer projects with probabilistic rules
 usage: AI assistants read this to generate probabilistic + deterministic rules implementations
-version: 3.1 - proper initialization of ai_request data
+version: 3.1
 date: November 21, 2025
 prerequisites:
   - docs/training/genai_logic_patterns.md (CRITICAL import patterns, auto-discovery)
@@ -399,9 +399,9 @@ def select_supplier_via_ai(row: models.SysSupplierReq, old_row, logic_row: Logic
     populating AI Results: chosen_supplier_id and chosen_unit_price.
     
     Strategy:
-    1. Check for test context first (for reproducible testing)
-    2. If no test context and API key exists, call OpenAI
-    3. If no API key, use fallback (min cost)
+    1. Load test context for INPUT conditions (world conditions like "Suez Canal blocked")
+    2. Always try AI with those conditions
+    3. If no API key or API fails, use fallback (min cost)
     """
     if not logic_row.is_inserted():
         return
@@ -417,7 +417,7 @@ def select_supplier_via_ai(row: models.SysSupplierReq, old_row, logic_row: Logic
         row.fallback_used = True
         return
     
-    # Check for test context first (BEFORE API key check)
+    # Load test context for world conditions (not for predetermined supplier selection)
     from pathlib import Path
     import yaml
     
@@ -425,25 +425,17 @@ def select_supplier_via_ai(row: models.SysSupplierReq, old_row, logic_row: Logic
     project_root = current_file.parent.parent.parent.parent
     context_file = project_root / 'config' / 'ai_test_context.yaml'
     
-    selected_supplier = None
-    
+    test_context = {}
     if context_file.exists():
         with open(str(context_file), 'r') as f:
-            test_context = yaml.safe_load(f)
-            if test_context and 'selected_supplier_id' in test_context:
-                supplier_id = test_context['selected_supplier_id']
-                selected_supplier = next((s for s in suppliers if s.supplier_id == supplier_id), None)
-                if selected_supplier:
-                    # Build candidate summary for request field
-                    candidate_summary = ', '.join([f"{s.supplier.name if s.supplier else 'Unknown'}(${s.unit_cost})" for s in suppliers])
-                    world = test_context.get('world_conditions', 'normal conditions')
-                    row.request = f"Select supplier for {product.name}: Candidates=[{candidate_summary}], World={world}"
-                    row.reason = f"TEST MODE: Selected {selected_supplier.supplier.name if selected_supplier.supplier else 'supplier'} (${selected_supplier.unit_cost}) - world: {world}"
-                    logic_row.log(f"Using test context: supplier {supplier_id}")
-                    row.fallback_used = False
+            test_context = yaml.safe_load(f) or {}
+    
+    world_conditions = test_context.get('world_conditions', 'normal conditions')
     
-    # If no test context, try AI (check for API key)
-    if not selected_supplier:
+    selected_supplier = None
+    
+    # Try AI (check for API key)
+    if True:  # Always try AI unless no key
         api_key = os.getenv("APILOGICSERVER_CHATGPT_APIKEY")
         if api_key:
             try:
@@ -453,18 +445,22 @@ def select_supplier_via_ai(row: models.SysSupplierReq, old_row, logic_row: Logic
                 
                 client = OpenAI(api_key=api_key)
                 
-                # Build candidate data for prompt
+                # Build candidate data for prompt - include ALL supplier fields for AI decision
                 candidate_data = []
                 for supplier in suppliers:
+                    supplier_obj = supplier.supplier
                     candidate_data.append({
                         'supplier_id': supplier.supplier_id,
-                        'supplier_name': supplier.supplier.name if supplier.supplier else 'Unknown',
+                        'supplier_name': supplier_obj.name if supplier_obj else 'Unknown',
+                        'supplier_region': supplier_obj.region if supplier_obj else None,
+                        'supplier_contact': supplier_obj.contact_name if supplier_obj else None,
+                        'supplier_phone': supplier_obj.phone if supplier_obj else None,
+                        'supplier_email': supplier_obj.email if supplier_obj else None,
                         'unit_cost': float(supplier.unit_cost) if supplier.unit_cost else 0.0,
-                        'lead_time_days': supplier.lead_time_days if hasattr(supplier, 'lead_time_days') else None
+                        'lead_time_days': supplier.lead_time_days if hasattr(supplier, 'lead_time_days') else None,
+                        'supplier_part_number': supplier.supplier_part_number if hasattr(supplier, 'supplier_part_number') else None
                     })
                 
-                world_conditions = test_context.get('world_conditions', 'normal conditions') if 'test_context' in locals() else 'normal conditions'
-                
                 prompt = f"""
 You are a supply chain optimization expert. Select the best supplier from the candidates below.
 
@@ -483,11 +479,14 @@ Respond with ONLY valid JSON in this exact format (no markdown, no code blocks):
 }}
 """
                 
-                # Populate request field with actual prompt summary
-                candidate_list = ', '.join([c['supplier_name'] + '($' + str(c['unit_cost']) + ')' for c in candidate_data])
-                row.request = f"AI Prompt: Product={product.name}, World={world_conditions}, Candidates={len(candidate_data)}: {candidate_list}"
+                # Populate request field with actual prompt summary including key fields
+                candidate_summary = ', '.join([
+                    f"{c['supplier_name']}(${c['unit_cost']}, {c['supplier_region'] or 'unknown region'}, {c['lead_time_days'] or '?'}days)" 
+                    for c in candidate_data
+                ])
+                row.request = f"Select supplier for {product.name}: Candidates=[{candidate_summary}], World={world_conditions}"
                 
-                logic_row.log(f"Calling OpenAI API with {len(candidate_data)} candidates")
+                logic_row.log(f"Calling OpenAI API with {len(candidate_data)} candidates, world conditions: {world_conditions}")
                 
                 response = client.chat.completions.create(
                     model="gpt-4o-2024-08-06",
@@ -508,7 +507,7 @@ Respond with ONLY valid JSON in this exact format (no markdown, no code blocks):
                 selected_supplier = next((s for s in suppliers if s.supplier_id == ai_result['chosen_supplier_id']), None)
                 if selected_supplier:
                     supplier_name = selected_supplier.supplier.name if selected_supplier.supplier else 'Unknown'
-                    row.reason = f"AI: {supplier_name} (${selected_supplier.unit_cost}) - {ai_result.get('reason', 'No reason provided')}"
+                    row.reason = f"Selected {supplier_name} (${selected_supplier.unit_cost}) - {ai_result.get('reason', 'No reason provided')}"
                     row.fallback_used = False
                 else:
                     logic_row.log(f"AI selected invalid supplier_id {ai_result['chosen_supplier_id']}, using fallback")
@@ -582,15 +581,21 @@ def get_supplier_selection_from_ai(product_id: int, item_id: int, logic_row: Log
 
 ### Key Implementation Points
 
-**Test Context Priority:**
-- ALWAYS check test context BEFORE API key
-- Enables reproducible testing without API calls
+**Test Context Usage:**
+- Load test context for INPUT conditions (world_conditions like "Suez Canal blocked")
+- Test context provides CONDITIONS for AI, NOT predetermined outputs
 - File: `config/ai_test_context.yaml`
+- Example: `world_conditions: "Suez Canal blocked, use alternate shipping routes"`
+
+**AI Strategy:**
+- Always try AI if API key exists
+- Pass world_conditions from test context to AI prompt
+- AI makes decision based on those conditions
 
 **Fallback Strategy:**
 - When no suppliers: Set `fallback_used = True`, return early
-- When no test context and no API key: Use min cost
-- When no test context but have API key: Call API (or fallback for demo)
+- When no API key: Use min cost fallback
+- When API call fails: Use min cost fallback
 
 **Type Handling:**
 - Foreign keys (IDs): Must be `int` not `Decimal`
@@ -789,8 +794,10 @@ class Product(Base):  # Has FK from SysSupplierReq.product_id
 class Item(Base):  # Has FK from SysSupplierReq.item_id
     SysSupplierReqList : Mapped[List["SysSupplierReq"]] = relationship(back_populates="item")
 
-class Supplier(Base):  # Has FK from SysSupplierReq.chosen_supplier_id
-    SysSupplierReqList : Mapped[List["SysSupplierReq"]] = relationship(foreign_keys="SysSupplierReq.chosen_supplier_id")
+# ✅ DO NOT add relationship to Supplier for chosen_supplier_id
+#    - This is an AI result field (not standard parent-child relationship)
+#    - Access via SysSupplierReq.chosen_supplier (unidirectional) is sufficient
+#    - Adding reverse relationship causes NoForeignKeysError
 
 # ✅ DO NOT add relationship to ProductSupplier (no FK exists)
 ```

api_logic_server_cli/prototypes/base/docs/training/probabilistic_logic_guide.md

@@ -154,11 +154,15 @@ def supplier_id_from_ai(row: models.SysSupplierReq, old_row, logic_row):
     if not has_api_key():
         min_supplier = min(suppliers, key=lambda s: s.unit_cost)
     else:
-        # Call AI service
+        # Load test context for INPUT conditions (world_conditions)
+        test_context = load_test_context()
+        world_conditions = test_context.get('world_conditions', 'normal conditions')
+        
+        # Call AI service with world conditions
         result = call_ai_service(
             candidates=suppliers,
             optimize_for='fastest reliable delivery',
-            context=load_test_context()
+            world_conditions=world_conditions  # Test context provides conditions, not outputs
         )
         min_supplier = result.chosen_supplier
     
@@ -281,14 +285,15 @@ def test_ai_handler_with_mock(mock_ai):
         'reason': 'Lowest cost'
     }
     
-    # Create test context
+    # Create test context with INPUT conditions (not predetermined outputs)
+    # Example: test_context = {'world_conditions': 'Suez Canal blocked'}
     row = create_test_item()
     logic_row = create_test_logic_row(row)
     
-    # Call handler
+    # Call handler (AI will make decision based on world conditions)
     result = get_supplier_price_from_ai(row, logic_row, ...)
     
-    # Verify
+    # Verify AI was called with proper conditions
     assert result == 95.00
     assert mock_ai.called
 ```
@@ -421,6 +426,39 @@ audit_logic_row.insert(reason="AI")
 
 ---
 
+## Test Context: Input Conditions vs Output Mocking
+
+**CRITICAL DISTINCTION:** Test context provides INPUT CONDITIONS for AI, NOT predetermined outputs.
+
+**Purpose:**
+- Test how AI responds to different scenarios (e.g., "Suez Canal blocked")
+- Verify AI considers world conditions in its decision-making
+- Enable repeatable testing with varying conditions
+
+**Example Test Context (config/ai_test_context.yaml):**
+```yaml
+# ✅ CORRECT - Provides input conditions
+world_conditions: "Suez Canal blocked, alternate routes required"
+
+# ❌ WRONG - Predetermines outputs (defeats AI testing)
+# selected_supplier_id: 2  # Don't do this!
+```
+
+**How It Works:**
+1. Load test context for `world_conditions`
+2. Pass conditions to AI prompt
+3. AI makes decision based on those conditions
+4. Verify AI selected appropriate supplier given the conditions
+
+**Testing Strategy:**
+- **Normal conditions:** AI should optimize for cost
+- **Disrupted conditions:** AI should prioritize reliability/alternate routes
+- **No API key:** System uses fallback (min cost)
+
+**Key Insight:** Test context lets you verify AI adapts to different scenarios WITHOUT mocking the AI itself.
+
+---
+
 ## Summary
 
 **Probabilistic Logic Pattern:**
@@ -433,6 +471,7 @@ audit_logic_row.insert(reason="AI")
 **Key Benefits:**
 - Seamless integration with deterministic rules
 - Full audit trail of AI decisions
+- Test context for scenario-based testing
 - Graceful fallback when AI unavailable
 - Testable at multiple levels
 - Reusable AI handlers across use cases