ApiLogicServer 15.1.2__py3-none-any.whl → 15.2.0__py3-none-any.whl

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

@@ -0,0 +1,741 @@
+
+
+
+# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
+
+## Project Type: Auto-Generated Microservice
+
+This is a **GenAI-Logic (aka API Logic Server) project** - a complete, working microservice - auto-generated from a database schema.
+
+## 🔑 Key Technical Points
+
+**Critical Implementation Details:**
+
+1. **Discovery Systems**: 
+   - **Logic Discovery**: Business rules automatically loaded from `logic/logic_discovery/use_case.py` via `logic/logic_discovery/auto_discovery.py`
+   - **API Discovery**: Custom APIs automatically loaded from `api/api_discovery/[service_name].py` via `api/api_discovery/auto_discovery.py`
+   - Do NOT manually duplicate rule calls or API registrations
+
+2. **API Record ID Pattern**: When creating records via custom APIs, use `session.flush()` before accessing the ID to ensure it's generated:
+   ```python
+   session.add(sql_alchemy_row)
+   session.flush()  # Ensures ID is generated
+   record_id = sql_alchemy_row.id
+   return {"message": "Success", "record_id": record_id}
+   ```
+
+3. **Automatic Business Logic**: All APIs (standard and custom) automatically inherit LogicBank rules without additional code.
+
+## ⚠️ IMPORTANT: What's Already Built
+
+**DO NOT recreate these - they're already working:**
+
+1. **Admin Web Application** - Live at `http://localhost:5656`
+2. **REST API Endpoints** - All database tables exposed at `/api/*`
+3. **Database Models** - Complete SQLAlchemy ORM in `database/models.py`
+4. **Authentication System** - JWT-based auth framework
+5. **Business Logic Engine** - Declarative rules system
+
+> **📋 Testing:** For comprehensive testing conventions, patterns, and examples, see `docs/training/testing.md` (555 lines - MUST READ FIRST before creating any tests)
+
+## 🎯 Common Tasks
+
+If the user asks "what do I do now?", these subsections are good suggestions.
+
+List these as choices, do not just do all of them at once - that would be overwhelming.
+
+### Set Up Virtual Environment
+If it is not already set, you can often find a `venv` in the GenAI-Logic Manager - a parent or grandparent directory.
+
+### 🚀 To Run This Project
+
+Use F5 (pre-configured run configuration - supports debugger for server logic), or (when focused on client apps):
+
+```bash
+python api_logic_server_run.py
+# Then open: http://localhost:5656
+```
+
+### Adding Business Logic
+`docs/training` explains how to translate Natural Language logic into LogicBank (Python) rules like:
+
+```python
+# Edit: logic/declare_logic.py
+Rule.sum(derive=Customer.Balance, as_sum_of=Order.AmountTotal)
+Rule.constraint(validate=Customer, as_condition=lambda row: row.Balance <= row.CreditLimit)
+```
+
+As described in `docs/training/logic_bank_api.prompt`, logic includes rules for sums, formulas, constraints, and more.  They also include events, which are used to trigger actions like sending emails or updating related records.
+
+For project `basic_demo`, the best place to begin is to provide CoPilot with the natural language logic below.  CoPilot will then offer to translate the logic into LogicBank rules. Also 
+1. Provide the analysis (below) showing the 44X code reduction.
+2. Stress the importance of business logic - it's half the project, and requires an underlying rules engine.  Using AI alone is not sufficient - you will wind up with procedural code, with the issues noted in the analysis below.
+
+Here's the natural language logic to provide to CoPilot:
+
+```text
+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.
+```
+
+**Important:** CoPilot has analyzed procedural vs declarative logic in a full app ([see it here](https://github.com/ApiLogicServer/basic_demo/blob/main/logic/declarative-vs-procedural-comparison.md)):
+
+<analysis>
+**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<br>Automatic Ordering | Implementation details obscure logic<br>Complex analysis to determine insert points, impacts |
+| **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.
+
+> **Note**: The procedural implementation was generated by AI (GitHub Copilot) and still required at least 2 critical and subtle bug fixes during development, highlighting the error-prone nature of procedural approaches even when AI-assisted.
+
+**Why the Rules Engine is a Correctness Guarantee:**
+
+The "2 critical bugs" mentioned above were:
+1. **Changing Order.customer_id** - procedural code failed to adjust BOTH the old and new customer balances
+2. **Changing Item.product_id** - procedural code failed to re-copy the unit_price from the new product
+
+These bugs illustrate why declarative rules are **mandatory, not optional**:
+
+**Dependency Chains:** In the logic above, `Customer.balance` has transitive dependencies:
+- Direct: `Order.amount_total`, `Order.date_shipped`
+- Through Order: `Item.amount` (affects Order.amount_total)
+- Through Item: `Item.quantity`, `Item.unit_price` (affect Item.amount)
+- Through Product: `Product.unit_price` (copied to Item.unit_price)
+
+**Automatic Completeness:** The declarative rules engine:
+- Listens to **SQLAlchemy ORM events** at the attribute level
+- When `Order.customer_id` changes, **automatically adjusts both old and new customer balances**
+- When `Item.product_id` changes, **automatically re-copies from the new product**
+- Uses **dependency ordering** to fire rules in correct sequence
+- Applies **optimized chaining** (uses deltas, not re-aggregation)
+
+**Why Procedural Code Fails:** Even AI-generated procedural code requires explicit handlers for EVERY possible change path. It's easy to miss:
+- Foreign key changes affecting multiple parents
+- Transitive dependencies through multiple tables
+- Where clause conditions that include/exclude rows
+
+The rules engine eliminates this entire class of bugs by automatically handling all change paths.
+
+</analysis>
+
+Generally CoPilot solicits Natural Language logic for translation (see logic/readme_logic.md), 
+but you can also offer to suggest rules.
+
+### Discovery Systems
+
+**IMPORTANT**: The project uses automated discovery systems that:
+
+**Logic Discovery:**
+1. **Automatically loads business logic** from `logic/logic_discovery/*.py`
+    * **CRITICAL: Always create separate files named for each use case** (e.g., `check_credit.py`, `app_integration.py`)
+    * **Never put multiple use cases in `use_case.py`** - that file is for templates/examples only
+2. **Discovers rules at startup** via `logic/logic_discovery/auto_discovery.py`
+3. **No manual rule loading required** - the `discover_logic()` function automatically finds and registers rules
+
+**API Discovery:**
+1. **Automatically loads custom APIs** from `api/api_discovery/[service_name].py`
+2. **Discovers services at startup** via `api/api_discovery/auto_discovery.py` (called from `api/customize_api.py`)
+3. **No manual API registration required** - services are automatically discovered and exposed
+
+**Do NOT duplicate** by calling them manually. The discovery systems handle this automatically.
+
+**Implementation Locations**:
+- Business rules: `logic/logic_discovery/use_case.py`
+- Custom APIs: `api/api_discovery/[service_name].py`
+- System automatically discovers and loads both
+
+**Pattern**:
+```python
+# logic/logic_discovery/use_case.py
+def declare_logic():
+    """Business logic rules for the application"""
+    Rule.sum(derive=Customer.balance, as_sum_of=Order.amount_total)
+    Rule.constraint(validate=Customer, as_condition=lambda row: row.balance <= row.credit_limit)
+    # ... other rules
+```
+
+**PATTERN RECOGNITION for Business Logic**:
+When users provide natural language with multiple use cases like:
+- "Use case: Check Credit" + "Use case: App Integration"
+
+**ALWAYS create separate files**:
+- `logic/logic_discovery/check_credit.py` - for credit checking rules
+- `logic/logic_discovery/app_integration.py` - for integration rules
+
+**NEVER put everything in `use_case.py`** - that defeats the discovery system purpose.
+
+### Automated Testing
+
+**CRITICAL WORKFLOW - When User Says "Create Tests":**
+
+```
+1. STOP ✋ - Do NOT create tests yet!
+2. READ docs/training/testing.md FIRST (555 lines - comprehensive guide with ALL patterns)
+3. This file contains EVERY discovered bug pattern from achieving 11/11 test success
+4. Pay special attention to:
+   - Rule #0: Test Repeatability (timestamps for uniqueness)
+   - Rule #0.5: Behave Step Ordering (specific before general patterns)
+   - Top 5 Critical Bugs section (common AI mistakes)
+   - Filter format: filter[column]=value (NOT OData)
+   - No circular imports (test files = black box, API only)
+   - Null-safe constraints (handle None values)
+   - Fresh test data (timestamps for uniqueness)
+5. THEN create tests following the patterns exactly
+6. NEVER create duplicate rules - all patterns already documented
+```
+
+**Why This Matters:** AI-generated tests fail 80% of the time without reading this guide first. The training material documents every common mistake (circular imports, wrong filter format, null-unsafe constraints, step ordering, etc.) with exact fixes. This guide achieved 11/11 test success (100%) and contains all discovered patterns.
+
+**`docs/training/testing.md`** explains how to create Behave tests from declarative rules, execute test suites, and generate automated documentation with complete logic traceability.
+
+**Key capabilities:**
+- **Create tests from rules** - Analyze declarative rules to generate appropriate test scenarios
+- **Execute test suite** - Run all tests with one command (Launch Configuration: "Behave Run")
+- **Generate documentation** - Auto-create wiki reports showing requirements, tests, rules used, and execution traces
+- **Requirements traceability** - Complete chain from business requirement → test → declarative rule → execution log
+
+**The Innovation:** Unlike traditional testing, Behave Logic Reports show **which declarative rules fired** during each test, providing complete transparency from requirement to execution. This solves the 44X advantage in testing - tests verify "what" (business rules) not "how" (procedural code).
+
+See `test/api_logic_server_behave/` for examples and [published report](https://apilogicserver.github.io/Docs/Behave-Logic-Report/).
+
+**Common Mistakes to Avoid (from testing.md):**
+1. ❌ Wrong filter: `filter="name eq 'Alice'"` → ✅ Use: `filter[name]="Alice"`
+2. ❌ Importing logic/database modules → ✅ Import only: behave, requests, test_utils
+3. ❌ Unsafe constraints: `row.x <= row.y` → ✅ Use: `row.x is None or row.y is None or row.x <= row.y`
+4. ❌ Step execution: `step_impl.execute_step()` → ✅ Use: `context.execute_steps('when Step')`
+5. ❌ Reusing test data → ✅ Create fresh with: `f"{name} {int(time.time()*1000)}"`
+
+**For detailed test creation patterns, see `docs/training/testing.md` which documents all critical rules including Rule #0.5 (Behave Step Ordering).**
+
+#### Critical Learnings: Behave Logic Report Generation
+
+**PROBLEM**: Reports not showing logic details for test scenarios.
+
+**ROOT CAUSES DISCOVERED**:
+
+1. **Empty behave.log** (Most Common Issue)
+   - ❌ Running: `python behave_run.py` 
+   - ✅ Must run: `python behave_run.py --outfile=logs/behave.log`
+   - Without `--outfile`, behave.log remains empty (0 bytes) and report has no content
+
+2. **Scenario Name Mismatch** 
+   - Log files must match scenario names from .feature file
+   - ❌ Using custom names: `scenario_name = f'B2B Order - {quantity} {product_name}'`
+   - ✅ Use actual scenario: `scenario_name = context.scenario.name`
+   - Report generator truncates to 25 chars and looks for matching .log files
+
+3. **Report Generator Logic Bug**
+   - Original code only showed logic when blank line followed "Then" step
+   - Only worked for ~30% of scenarios (those with blank lines in behave.log)
+   - ✅ Fixed: Trigger logic display when next scenario starts OR at end of file
+
+**CORRECT PATTERN FOR WHEN STEPS**:
+
+```python
+@when('B2B order placed for "{customer_name}" with {quantity:d} {product_name}')
+def step_impl(context, customer_name, quantity, product_name):
+    """
+    Phase 2: CREATE using OrderB2B API - Tests OrderB2B integration
+    """
+    scenario_name = context.scenario.name  # ← CRITICAL: Use actual scenario name
+    test_utils.prt(f'\n{scenario_name}\n', scenario_name)
+    
+    # ... test implementation ...
+```
+
+**WORKFLOW FOR REPORT GENERATION**:
+
+```bash
+# 1. Run tests WITH outfile to generate behave.log
+python behave_run.py --outfile=logs/behave.log
+
+# 2. Generate report (reads behave.log + scenario_logic_logs/*.log)
+python behave_logic_report.py run
+
+# 3. View report
+open reports/Behave\ Logic\ Report.md
+```
+
+**WHAT THE REPORT SHOWS**:
+- Each scenario gets a `<details>` section with:
+  - **Rules Used**: Which declarative rules fired (numbered list)
+  - **Logic Log**: Complete trace showing before→after values for all adjustments
+- Demonstrates the 44X code reduction by showing rule automation
+
+**DEBUGGING TIPS**:
+
+```bash
+# Check if behave.log has content
+ls -lh logs/behave.log  # Should be several KB, not 0 bytes
+
+# Check if scenario logs exist with correct names
+ls logs/scenario_logic_logs/ | head -10
+
+# Count detail sections in report (should equal number of scenarios)
+grep -c "<details markdown>" reports/Behave\ Logic\ Report.md
+
+# View a specific scenario's log directly
+cat logs/scenario_logic_logs/Delete_Item_Reduces_Order.log
+```
+
+**KEY INSIGHT**: The report generator uses a two-step process:
+1. Reads behave.log for scenario structure (Given/When/Then steps)
+2. Matches scenario names to .log files in scenario_logic_logs/
+3. Injects logic details at the right location in the report
+
+If scenario names don't match between behave.log and .log filenames, logic details won't appear!
+
+### Adding MCP
+
+The API is automatically MCP-enabled. The project includes a comprehensive MCP client executor at `integration/mcp/mcp_client_executor.py`, but to enable the **user interface** for MCP requests, you must run this command:
+
+```bash
+genai-logic genai-add-mcp-client
+```
+
+**CRITICAL DISTINCTION**:
+- **`integration/mcp/mcp_client_executor.py`** = MCP processing engine (already exists)
+- **`genai-logic genai-add-mcp-client`** = Command to add SysMcp table and UI infrastructure (must be run)
+
+**When users ask to "Create the MCP client executor"**, they mean run the `genai-logic genai-add-mcp-client` command, NOT recreate the existing processing engine.
+
+This command adds:
+1. **SysMcp table** for business users to enter natural language requests
+2. **Admin App integration** for MCP request interface
+3. **Database infrastructure** for MCP client operations
+
+### Configuring Admin UI
+
+This is built when project is created - no need to add it.
+Customize by editing the underlying yaml.
+
+```yaml
+# Edit: ui/admin/admin.yaml
+resources:
+  Customer:
+    attributes:
+      - name: CompanyName
+        search: true
+        sort: true
+```
+
+### Create and Customize React Apps
+
+**REQUIRED METHOD**: Complete customization is provided by generating a React Application (requires OpenAI key, Node):
+
+**DO NOT use `create-react-app` or `npx create-react-app`**
+**ALWAYS use this command instead:**
+
+```bash
+# Create: ui/admin/my-app-name
+genai-logic genai-add-app --app-name=my-app-name --vibe
+```
+
+Then, `npm install` and `npm start`
+
+Temporary restriction: security must be disabled.
+
+**IMPORTANT**: When working with React apps, ALWAYS read `docs/training` first. This file contains critical data access provider configuration that was built when the project was created. The data provider handles JSON:API communication and record context - ignore this at your peril.
+
+Customize using CoPilot chat, with `docs/training`.
+
+#### React Component Development Best Practices
+
+**Critical Pattern for List/Card Views**: When implementing custom views (like card layouts) in React Admin components:
+
+1. **Use `useListContext()` correctly**: Access `data` as an array, not as an object with `ids`
+   ```javascript
+   // CORRECT Pattern:
+   const { data, isLoading } = useListContext();
+   return (
+     <Grid container spacing={2}>
+       {data?.map(record => (
+         <Grid item key={record.id}>
+           <CustomCard record={record} />
+         </Grid>
+       ))}
+     </Grid>
+   );
+   
+   // AVOID: Trying to use data[id] pattern - this is for older React Admin versions
+   ```
+
+
+2. **Component Naming Consistency**: Ensure component names match their usage in JSX - mismatched names cause runtime errors.
+
+3. **Simple Error Handling**: Use straightforward loading states rather than complex error checking:
+    ```javascript
+    if (isLoading) return <div>Loading...</div>;
+    ```
+
+4. 🃏 Card View Action Links (Show, Edit, Delete) **IMPORTANT:** All card views (e.g., Product cards) must include action links or buttons for **Show**, **Edit**, and **Delete** for each record (not just the display fields), matching the functionality of the table/list view.
+
+
+**Common Mistakes to Avoid**:
+- Using `{ data, ids }` destructuring and trying to map over `ids` - this pattern is outdated
+- Creating complex error handling when simple loading checks suffice
+- Not referencing existing working implementations before creating new patterns
+
+### Security - Role-Based Access Control
+
+Configure:
+```
+als add-auth --provider-type=sql --db-url=
+als add-auth --provider-type=sql --db_url=postgresql://postgres:p@localhost/authdb
+
+als add-auth --provider-type=keycloak --db-url=localhost
+als add-auth --provider-type=keycloak --db-url=hardened
+
+als add-auth --provider-type=None # to disable
+``` 
+
+Keycloak quick start [(more information here:)](https://apilogicserver.github.io/Docs/Security-Keycloak/)
+```bash
+cd devops/keycloak
+docker compose up
+als add-auth --provider-type=keycloak --db-url=localhost
+```
+
+For more on KeyCloak: https://apilogicserver.github.io/Docs/Security-Keycloak/
+
+Declaration:
+```python
+# Edit: security/declare_security.py
+Grant(on_entity=Customer, to_role=sales, filter=lambda: Customer.SalesRep == current_user())
+```
+
+### Adding Custom API Endpoints
+
+For simple endpoints:
+```python
+# Edit: api/customize_api.py
+@app.route('/api/custom-endpoint')
+def my_endpoint():
+    return {"message": "Custom endpoint"}
+```
+
+### Creating Advanced B2B Integration APIs with Natural Language
+
+Users can create sophisticated custom API endpoints for B2B integration using natural language. The system automatically generates and discovers:
+
+1. **Custom API Service** (`api/api_discovery/[service_name].py`) - automatically discovered by `api/api_discovery/auto_discovery.py`
+2. **Row Dict Mapper** (`integration/row_dict_maps/[MapperName].py`)
+
+**Example Implementation**: This project includes a working **OrderB2B API** that demonstrates the complete pattern:
+- **API**: `api/api_discovery/order_b2b_service.py`
+- **Mapper**: `integration/row_dict_maps/OrderB2BMapper.py`
+- **Test Cases**: `test_requests.http` and `test_b2b_order_api.py`
+
+**Pattern Recognition**: When users describe B2B integration scenarios involving:
+- External partner data formats (✅ Account → Customer lookup)
+- Field aliasing/renaming (✅ "Name" → Product.name, "QuantityOrdered" → Item.quantity)
+- Nested data structures (✅ Items array handling)
+- Lookups and joins (✅ Customer by name, Product by name)
+- Data transformation (✅ External format to internal models)
+
+Generate both the API service and corresponding Row Dict Mapper following these patterns:
+
+**API Service Template** (`api/api_discovery/[service_name].py`) - Keep it concise:
+```python
+from flask import request
+from safrs import jsonapi_rpc
+import safrs
+from integration.row_dict_maps.OrderB2BMapper import OrderB2BMapper
+import logging
+
+app_logger = logging.getLogger("api_logic_server_app")
+
+def add_service(app, api, project_dir, swagger_host: str, PORT: str, method_decorators = []):
+    api.expose_object(OrderB2BEndPoint)
+
+class OrderB2BEndPoint(safrs.JABase):
+    @classmethod
+    @jsonapi_rpc(http_methods=["POST"])
+    def OrderB2B(self, *args, **kwargs):  # yaml comment => swagger description
+        """ # yaml creates Swagger description
+            args :
+                data:
+                    Account: "Alice"
+                    Notes: "Rush order for Q4 promotion"
+                    Items :
+                    - Name: "Widget"
+                      QuantityOrdered: 5
+                    - Name: "Gadget"
+                      QuantityOrdered: 3
+            ---
+        
+        Creates B2B orders from external partner systems with automatic lookups and business logic.
+        Features automatic customer/product lookups by name, unit price copying, 
+        amount calculations, customer balance updates, and credit limit validation.
+        """
+        db = safrs.DB
+        session = db.session
+        
+        try:
+            mapper_def = OrderB2BMapper()
+            request_dict_data = request.json["meta"]["args"]["data"]
+            
+            app_logger.info(f"OrderB2B: Processing order for account: {request_dict_data.get('Account')}")
+            
+            sql_alchemy_row = mapper_def.dict_to_row(row_dict=request_dict_data, session=session)
+            
+            session.add(sql_alchemy_row)
+            session.flush()  # Ensures ID is generated before accessing it
+            
+            order_id = sql_alchemy_row.id
+            customer_name = sql_alchemy_row.customer.name if sql_alchemy_row.customer else "Unknown"
+            item_count = len(sql_alchemy_row.ItemList)
+            
+            return {
+                "message": "B2B Order created successfully", 
+                "order_id": order_id,
+                "customer": customer_name,
+                "items_count": item_count
+            }
+            
+        except Exception as e:
+            app_logger.error(f"OrderB2B: Error creating order: {str(e)}")
+            session.rollback()
+            return {"error": "Failed to create B2B order", "details": str(e)}, 400
+```
+
+**IMPORTANT**: The project includes a working B2B integration example:
+- **API Endpoint**: `OrderB2BEndPoint.OrderB2B` - Creates orders from external partner format
+- **Error Handling**: Proper exception handling with session rollback for failed operations
+- **Business Logic**: Automatic inheritance of all LogicBank rules (pricing, calculations, validation)
+- **Testing**: Comprehensive test suite demonstrating success and error scenarios
+- **Documentation**: Professional Swagger docs with YAML examples using real database data
+
+When creating new B2B APIs, follow this proven pattern:
+- Use `session.flush()` when you need generated IDs before commit
+- Include proper error handling with try/catch and session.rollback()
+- Provide meaningful success messages with key information (ID, customer, item count)
+- Use YAML format in docstrings for clean Swagger documentation
+- Always use actual database data in examples (check with sqlite3 queries)
+
+**AI Anti-Patterns to Avoid**:
+- **Don't assume CRUD operations**: If user asks for "create order API", only implement POST/insert (ask if they need GET/PUT/DELETE)
+- **Don't add "enterprise" features** unless specifically requested:
+  - Detailed logging/monitoring beyond basic debugging
+  - Complex response objects with metadata
+  - Extensive documentation/comments
+  - HTTP status code handling beyond defaults
+- **Don't import unused libraries**: Skip `logging`, `jsonify`, etc. unless actually needed
+- **Don't over-engineer**: Simple success messages beat complex response objects
+
+**Swagger Examples Must Use Real Data**: 
+When creating YAML docstring examples, use actual database data. Check first:
+```bash
+sqlite3 database/db.sqlite "SELECT name FROM customer LIMIT 3;"
+sqlite3 database/db.sqlite "SELECT name FROM product LIMIT 3;"
+```
+
+**Getting Sample Data for Tests**:
+```bash
+# Check actual customer names
+sqlite3 database/db.sqlite "SELECT name FROM customer LIMIT 5;"
+
+# Check actual product names  
+sqlite3 database/db.sqlite "SELECT name FROM product LIMIT 5;"
+```
+Never assume data from other databases (like Northwind's "ALFKI") - always use the current project's actual data.
+
+**Row Dict Mapper Template** (`integration/row_dict_maps/[MapperName].py`):
+```python
+from integration.system.RowDictMapper import RowDictMapper
+from database import models
+
+class OrderB2BMapper(RowDictMapper):
+    def __init__(self):
+        """
+        B2B Order API Mapper for external partner integration.
+        
+        Maps external B2B format to internal Order/Item structure:
+        - 'Account' field maps to Customer lookup by name
+        - 'Notes' field maps directly to Order notes
+        - 'Items' array with 'Name' and 'QuantityOrdered' maps to Item records
+        """
+        mapper = super(OrderB2BMapper, self).__init__(
+            model_class=models.Order,
+            alias="Order",
+            fields=[
+                (models.Order.notes, "Notes"),
+                # customer_id will be set via parent lookup
+                # amount_total will be calculated by business logic
+                # CreatedOn will be set by business logic
+            ],
+            parent_lookups=[
+                (models.Customer, [(models.Customer.name, 'Account')])
+            ],
+            related=[
+                ItemB2BMapper()
+            ]
+        )
+        return mapper
+
+class ItemB2BMapper(RowDictMapper):
+    def __init__(self):
+        """
+        B2B Item Mapper for order line items.
+        
+        Maps external item format to internal Item structure:
+        - 'Name' field maps to Product lookup by name
+        - 'QuantityOrdered' maps to Item quantity
+        """
+        mapper = super(ItemB2BMapper, self).__init__(
+            model_class=models.Item,
+            alias="Items",
+            fields=[
+                (models.Item.quantity, "QuantityOrdered"),
+                # unit_price will be copied from product by business logic
+                # amount will be calculated by business logic (quantity * unit_price)
+            ],
+            parent_lookups=[
+                (models.Product, [(models.Product.name, 'Name')])
+            ],
+            isParent=False
+        )
+        return mapper
+```
+
+**Key Components for Natural Language Processing**:
+- **Field Aliasing**: `(models.Table.field, "ExternalName")`
+- **Parent Lookups**: `(models.ParentTable, [(models.ParentTable.lookup_field, 'ExternalKey')])`
+- **Related Entities**: Nested RowDictMapper instances for child records
+- **Automatic Joins**: System handles foreign key relationships automatically
+
+**Business Logic Integration**: All generated APIs automatically inherit the full LogicBank rule engine through the discovery systems (`logic/logic_discovery/auto_discovery.py` and `api/api_discovery/auto_discovery.py`), ensuring data integrity, calculations, and constraints without additional code. Rules are automatically loaded from `logic/logic_discovery/use_case.py` and APIs from `api/api_discovery/[service_name].py` at startup.
+
+**Testing B2B APIs**: The project includes comprehensive testing infrastructure:
+- **REST Client Tests**: `test_requests.http` - Test directly in VS Code with REST Client extension
+- **Python Test Suite**: `test_b2b_order_api.py` - Automated testing with requests library
+- **Swagger UI**: `http://localhost:5656/api` - Interactive API testing and documentation
+- **Sample Requests**: `sample_b2b_request.json` - Copy-paste examples for testing
+
+**Working Example Results**: The OrderB2B API demonstrates:
+- ✅ External format mapping (Account → Customer, Name → Product)
+- ✅ Automatic lookups with error handling (missing customer/product detection)
+- ✅ Business logic inheritance (unit price copying, amount calculations, balance updates)
+- ✅ Professional Swagger documentation with YAML examples
+- ✅ Complete test coverage (success cases and error scenarios)
+
+### Customize Models - Add Tables, Attributes
+
+To add tables / columns to the database (highly impactful - request permission):
+
+1. Update `database/model.py`
+2. Use `database/alembic/alembic_run.py` to update the database.  This will generate a migration script and apply it to the database, so you do not have to run `alembic revision --autogenerate` manually. 
+3. Offer to update ui/admin/admin.yaml to add the new table or column to the Admin UI.
+
+NEVER start by  updating the database directly, since some platforms may not have database CLI tools, although you can present this as an option.
+
+If altering `database/models.py`, be sure to follow the patterns shown in the existing models.  Note they do not contain a `__bind_key__`.
+
+
+### Addressing `Missing Attributes` during logic loading at project startup
+
+First, check for misspelling (logic vs `database/models.py`), and repair.
+
+If there are no obvious misspellings, ask for permission to add attributes; if granted, proceed as above.
+
+### Customize Models - Add Derived attributes
+
+Here is a sample derived attribute, `proper_salary`:
+
+```python
+
+# add derived attribute: https://github.com/thomaxxl/safrs/blob/master/examples/demo_pythonanywhere_com.py
+@add_method(models.Employee)
+@jsonapi_attr
+def __proper_salary__(self):  # type: ignore [no-redef]
+    import database.models as models
+    import decimal
+    if isinstance(self, models.Employee):
+        rtn_value = self.Salary
+        if rtn_value is None:
+          rtn_value = decimal.Decimal('0')
+        rtn_value = decimal.Decimal('1.25') * rtn_value
+        self._proper_salary = int(rtn_value)
+        return self._proper_salary
+    else:
+        rtn_value = decimal.Decimal('0')
+        self._proper_salary = int(rtn_value)
+        return self._proper_salary
+
+@add_method(models.Employee)
+@__proper_salary__.setter
+def _proper_salary(self, value):  # type: ignore [no-redef]
+    self._proper_salary = value
+    print(f'_proper_salary={self._proper_salary}')
+    pass
+
+models.Employee.ProperSalary = __proper_salary__
+
+```
+
+When customizing SQLAlchemy models:
+
+* Don't use direct comparisons with database fields in computed properties
+* Convert to Python values first using float(), int(), str()
+* Use property() function instead of @jsonapi_attr for computed properties
+* Always add error handling for type conversions
+
+### Adding events
+LogicBank rules are the preferred approach to logic, but you will sometimes need to add events.  This is done in `logic/declare_logic.py` (important: the function MUST come first):
+
+```python
+# Example: Log email activity after SysEmail is committed
+
+def sys_email_after_commit(row: models.SysEmail, old_row: models.SysEmail, logic_row: LogicRow):
+    """
+    After SysEmail is committed, log 'email sent' 
+    unless the customer has opted out
+    """
+    if not row.customer.email_opt_out:
+        logic_row.log(f"📧 Email sent to {row.customer.name} - Subject: {row.subject}")
+    else:
+        logic_row.log(f"🚫 Email blocked for {row.customer.name} - Customer opted out")
+
+Rule.commit_row_event(on_class=SysEmail, calling=sys_email_after_commit)
+```
+
+LogicBank event types include:
+- `Rule.commit_row_event()` - fires after transaction commits
+- `Rule.after_insert()` - fires after row insert
+- `Rule.after_update()` - fires after row update  
+- `Rule.after_delete()` - fires after row delete
+
+All events receive `(row, old_row, logic_row)` parameters and should use `logic_row.log()` for logging.
+
+## 📁 Key Directories
+
+- `logic/` - Business rules (declarative)
+- `api/` - REST API customization
+- `security/` - Authentication/authorization
+- `database/` - Data models and schemas
+- `ui/admin/` - Admin interface configuration
+- `ui/app/` - Alternative Angular admin app
+
+## 💡 Helpful Context
+
+- This uses Flask + SQLAlchemy + SAFRS for JSON:API
+- Admin UI is React-based with automatic CRUD generation
+- Business logic uses LogicBank (declarative rule engine)
+- Everything is auto-generated from database introspection
+- Focus on CUSTOMIZATION, not re-creation
+- Use CoPilot to assist with logic translation and API generation