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

api_logic_server_cli/api_logic_server.py

@@ -8,14 +8,15 @@ ApiLogicServer CLI: given a database url, create [and run] customizable ApiLogic
         * api/expose_api_models.py for a safrs api  - using introspected models.py
     * Special provisions for NW Sample, to show customizations.
     * See end for key_module_map() quick links
-
+;
 Called from api_logic_server_cli.py, by instantiating the ProjectRun object.
 '''
 
-__version__ = "15.00.61"  # last public release: 15.00.52 (15.00.12)
+__version__ = "15.01.00"  # last public release: 15.00.65
 recent_changes = \
     f'\n\nRecent Changes:\n' +\
-    "\t07/27/2024 - 15.00.61: no mgr fix, confluent-kafka==2.6.0 for 3.13, system vibe support -- initial testing \n"\
+    "\t08/09/2024 - 15.01.00: improved vibe instructions \n"\
+    "\t08/06/2024 - 15.00.65: instructions for custom API endpoints, behave testing \n"\
     "\t07/20/2024 - 15.00.52: Python 3.13 compatibility fixes - psycopg2→psycopg3, SQLAlchemy 2.0+, pkg_resources→importlib.metadata.  mgr dbs \n"\
     "\t07/17/2024 - 15.00.49: venv fix+, ext bldr * fix, copilot vibe tweaks - creation, mcp logic, basic_demo autonums \n"\
     "\t07/10/2024 - 15.00.41: copilot vibe support for logic, UI, MCP,  bug[98] \n"\

api_logic_server_cli/api_logic_server_info.yaml

@@ -1,3 +1,3 @@
-last_created_date: July 24, 2025 19:58:07
+last_created_date: August 06, 2025 17:34:43
 last_created_project_name: ../../../servers/basic_demo
-last_created_version: 15.00.57
+last_created_version: 15.00.65

api_logic_server_cli/cli.py

@@ -823,8 +823,8 @@ def genai_add_app(ctx, app_name: str, vibe: click.BOOL, retries: int, schema: st
         log.info(f'... Error - does not appear to be a project: {str(project.project_directory_path)}')
         log.info(f'... Typical usage - cd into project, use --project_name=. \n')
         exit (1)
-    from api_logic_server_cli.genai.genai_admin_app import GenAIAdminApp
-    genai_admin = GenAIAdminApp(project=project, app_name=app_name, vibe=vibe, schema=schema, retries=retries, genai_version=genai_version)
+    from api_logic_server_cli.genai.genai_react_app import GenAIReactApp
+    genai_react = GenAIReactApp(project=project, app_name=app_name, vibe=vibe, schema=schema, retries=retries, genai_version=genai_version)
     pass
     log.info("")
 

api_logic_server_cli/genai/{genai_admin_app.py → genai_react_app.py}

@@ -37,7 +37,15 @@ class JSResponseFormat(BaseModel):  # must match system/genai/prompt_inserts/res
     code : str # generated javascript code (only)
 
 
-class GenAIAdminApp:
+class GenAIReactApp:
+    """Create a react app:
+    1. Clones <mgr>/system/genai/app_templates/react-admin-template
+    2. For each data model class, uses creates page with list and show
+        * Uses ChatGpt with system/genai/app_templates/app_learning/Admin-App-Resource-Learning-Prompt.md
+        * Regrettably, repairs imports
+    3. Creates Admin.js
+        * Uses ChatGpt with system/genai/app_templates/app_learning/Admin-App-js-Learning-Prompt.md
+    """
 
     def __init__(self, project: Project, app_name: str, vibe: bool, schema: str, genai_version: str, retries: int):
         self.start_time = time.time()
@@ -135,7 +143,7 @@ class GenAIAdminApp:
 
     def a_generate_resource_files(self):
 
-        def fix_resource(genai_app: GenAIAdminApp, raw_source: str) -> str:
+        def fix_resource(genai_app: GenAIReactApp, raw_source: str) -> str:
             ''' Remove occasional begin/end code markers <br>
             And horrific override of ChatGPT refusal to generate imports AS DIRECTED!<br>
             '''

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

@@ -4,6 +4,25 @@
 
 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:**
@@ -14,6 +33,8 @@ This is a **GenAI-Logic (aka API Logic Server) project** - a complete, working m
 4. **Authentication System** - JWT-based auth framework
 5. **Business Logic Engine** - Declarative rules system
 
+> **📋 Testing:** For comprehensive testing conventions, patterns, and examples, see `test/readme_test.md`
+
 ## 🎯 Common Tasks
 
 If the user asks "what do I do now?", these subsections are good suggestions.
@@ -80,14 +101,68 @@ Use case: App Integration
 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.
+
 ### Adding MCP
 
-The API is automatically MCP-enabled.  This adds the MCP Client:
+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.
@@ -105,7 +180,10 @@ resources:
 
 ### Create and Customize React Apps
 
-Complete customization is provided by generating a React Application (requires OpenAI key, Node):
+**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
@@ -120,6 +198,39 @@ Temporary restriction: security must be disabled.
 
 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>;
+   ```
+
+**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:
@@ -149,6 +260,8 @@ Grant(on_entity=Customer, to_role=sales, filter=lambda: Customer.SalesRep == cur
 ```
 
 ### Adding Custom API Endpoints
+
+For simple endpoints:
 ```python
 # Edit: api/customize_api.py
 @app.route('/api/custom-endpoint')
@@ -156,6 +269,211 @@ 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):
@@ -260,3 +578,4 @@ All events receive `(row, old_row, logic_row)` parameters and should use `logic_
 - 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

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

@@ -8,6 +8,8 @@ If you create sum, count or formula LogicBank rules, you MUST create a correspon
 
 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.
+
 
 class Rule:
     """ Invoke these functions to declare rules """
@@ -131,6 +133,11 @@ class Rule:
                               if_condition: any = None,
                               when_condition: any = None,
                               with_args: dict = None):
+        """
+        Events are triggered after database flush for integration (Kafka, etc.)
+        
+        IMPORTANT: Use this simple pattern - do NOT create custom functions unless absolutely necessary.
+        Use if_condition parameter for conditional logic instead of writing custom event handlers.
 
         Example:
             Prompt:
@@ -146,6 +153,13 @@ class Rule:
                                if_condition=lambda row: row.is_complete is True,
                                with_args={"topic": "ready_to_ship"})
 
+        Args:
+            on_class: The model class to watch for changes
+            calling: Use kafka_producer.send_row_to_kafka for Kafka integration
+            if_condition: Lambda function to specify when the event should trigger
+            with_args: Dictionary with parameters like {"topic": "topic_name"}
+        """
+
 
 Expanded example:
 
@@ -310,5 +324,18 @@ Required (must-have) related parent constraints require an update to the data mo
     Prompt: Each Item must have a valid entry in the Product table.
     Response: product_id = Column(ForeignKey('product.id'), nullable=False)
 
+CRITICAL: For event handling (Kafka integration, etc.), do NOT create custom event functions.
+Use Rule.after_flush_row_event with if_condition parameter instead.
+
+WRONG (do not do this):
+    def my_custom_kafka_function(row, old_row, logic_row):
+        # custom logic here
+    Rule.commit_row_event(on_class=Order, calling=my_custom_kafka_function)
+
+RIGHT (do this instead):
+    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"})
+
 logic should create python files in logic/logic_discovery, 
 and cross-check/use attribute names in database/models.py

api_logic_server_cli/prototypes/base/logic/logic_discovery/use_case.py

@@ -1,5 +1,6 @@
 import datetime
 from decimal import Decimal
+from integration.kafka import kafka_producer
 from logic_bank.exec_row_logic.logic_row import LogicRow
 from logic_bank.extensions.rule_extensions import RuleExtension
 from logic_bank.logic_bank import Rule
@@ -10,7 +11,10 @@ import logging
 from flask import jsonify
 
 
-""" Best practice: create logic files for each use case """
+""" 
+Best practice: create logic files for each use case, 
+named for the use case (eg, check_credit.py) 
+"""
 
 app_logger = logging.getLogger(__name__)