ApiLogicServer 15.3.2__py3-none-any.whl → 15.4.0__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__ = "15.03.02"  # last public release: 15.03.00
+__version__ = "15.04.00"  # last public release: 15.03.02
 recent_changes = \
     f'\n\nRecent Changes:\n' +\
-    "\t11/04/2025 - 15.03.02: Fix Manager/Copilot startup \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"\
     "\t10/26/2025 - 15.02.07: Clarify order created for ship test, security fixes [105], tutor 2.1 \n"\
     "\t10/22/2025 - 15.02.03: Copilot test creation from rules and custom APIs with issues [103, 104] \n"\
@@ -402,6 +402,7 @@ def create_project_and_overlay_prototypes(project: 'ProjectRun', msg: str) -> st
             os.rename(project.project_directory_path / 'readme.md', project.project_directory_path / 'readme_standard.md')
             create_utils.copy_md(project = project, from_doc_file = "Sample-Basic-Demo.md", to_project_file = "readme.md")
             create_utils.copy_md(project = project, from_doc_file = "Sample-Basic-Demo-Vibe.md", to_project_file="readme_vibe.md")
+            create_utils.copy_md(project = project, from_doc_file = "Integration-MCP-AI-Example.md", to_project_file="readme_ai_mcp.md")
 
 
         if project.db_url == "mysql+pymysql://root:p@localhost:3306/classicmodels":

api_logic_server_cli/api_logic_server_info.yaml

@@ -1,3 +1,3 @@
-last_created_date: September 27, 2025 18:12:50
-last_created_project_name: retry_genai_demo_baseless_classes
-last_created_version: 15.01.04
+last_created_date: November 08, 2025 08:44:56
+last_created_project_name: ../../../servers/basic_demo
+last_created_version: 15.04.00

api_logic_server_cli/create_from_model/api_logic_server_utils.py

@@ -84,7 +84,7 @@ def copy_md(project, from_doc_file: str, to_project_file: str = "README.md"):
     
     1. github (to acquire more recent version since release)
     
-    2. dev docs, iff exists (gold version in docs, not prototypes).
+    2. dev docs, iff exists (**gold version in docs, not prototypes**).
 
     Used by Sample-AI; Sample-Integration (nw-), Tutorial, Tutorial-3 (3 projects), Sample-Basic-Demo; Manager
 
@@ -98,6 +98,8 @@ def copy_md(project, from_doc_file: str, to_project_file: str = "README.md"):
 
     Doc Links are made absolute.
 
+    See: https://apilogicserver.github.io/Docs/Architecture-Internals/#docs-used-in-project-creation
+
     Args:
         project (ProjectRun or Path): project object (project name, etc)
         from_doc_file (str): eg, Sample-Basic_Demo.md (no docs/)

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

@@ -3,9 +3,12 @@ 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 here to api_logic_server_cli/prototypes/basic_demo/.github - see instructions there
 Usage: AI assistants read this when user opens any created project
-version: 2.3
+version: 2.5
 changelog:
+  - 2.5 (Nov 08, 2025 - API Best Practices
+  - 2.4 (Nov 05, 2025 - Added MCP Integration section, Copilot as MCP client capability)
   - 2.3 (Nov 04, 2025 - Clear 1st message about reading Welcome section verbatim, again for non basic_demo)
   - 2.2 (Oct 29, 2025 - Clear 1st message about reading Welcome section verbatim)
   - 2.1 (Oct 2025) - Streamlined OBX for non-tutorial projects, friendly collaborative tone
@@ -15,7 +18,7 @@ changelog:
 
 # GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
 
-**INSTRUCTION**: When the user asks you to load these instructions, respond with the Welcome section content below as your greeting. Do not add preamble like "I've read the instructions" - just present the Welcome content directly.
+**INSTRUCTION**: When the user asks you to load these instructions, respond with the Welcome section content below as your greeting. Do not add preamble like "I've read the instructions" - just present the Welcome content directly. The Welcome section ends at the "---" marker before "🔑 Key Technical Points".
 
 ## Welcome
 
@@ -32,7 +35,7 @@ This is a complete, working microservice auto-generated from your database schem
 
 ---
 
-**Here are some things I can help you with:**
+## Here are some things I can help you with
 
 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
@@ -40,7 +43,7 @@ This is a complete, working microservice auto-generated from your database schem
 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
+7. **Query via natural language** - I can act as MCP client to read/update data (see `docs/training/MCP_Copilot_Integration.md`)
 8. **Create B2B APIs** - Complex integration endpoints with partner systems
 9. **Add events** - Integrate with Kafka, webhooks, or other event systems
 10. **Customize models** - Add tables, attributes, or derived fields
@@ -109,6 +112,17 @@ Want to get started? Press **F5** to start the server with debugger support, the
 ## Detailed Service Documentation
 
 The sections below provide complete details on each service. I'll reference these as needed when we work together.
+
+### `venv` is required
+
+To establish the virtual environment:
+
+1. Attempt to find a `venv` folder in the parent or grandparent directory
+2. Or, create it using requirements.txt
+
+### Starting the server
+
+```bash
 python api_logic_server_run.py
 # Then open: http://localhost:5656
 ```
@@ -236,6 +250,135 @@ When users provide natural language with multiple use cases like:
 
 **NEVER put everything in `use_case.py`** - that defeats the discovery system purpose.
 
+### MCP Integration - Acting as Database Client
+
+**You (GitHub Copilot) can serve as an MCP client** to read and update database entities using natural language queries!
+
+**Architecture**: This project implements **MCP Server Executor** - a business logic microservice that AI assistants interact with via authenticated REST API calls. See `docs/training/MCP_Copilot_Integration.md` for complete details.
+
+**When users request database operations** (e.g., "list customers", "update credit limit", "what's the balance?"):
+
+1. **Authenticate first** - Login to obtain JWT token:
+```bash
+curl -X POST http://localhost:5656/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"p"}'
+```
+
+2. **Execute operations** - Use Bearer token for API calls:
+```bash
+# Read: List entities
+curl -X GET http://localhost:5656/api/Customer/ \
+  -H "Authorization: Bearer {token}"
+
+# Update: Change attributes (JSON:API format)
+curl -X PATCH http://localhost:5656/api/Customer/ALFKI/ \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/vnd.api+json" \
+  -d '{"data": {"type": "Customer", "id": "ALFKI", "attributes": {"CreditLimit": 5000}}}'
+```
+
+3. **Handle constraint violations correctly** - Error code 2001 is SUCCESS!
+   - When LogicBank prevents invalid updates, report as: "✅ Business logic working - constraint prevented invalid operation"
+   - Example: "balance (2102.00) exceeds credit (1000.00)" = logic is protecting data integrity
+
+**Natural Language Translation Examples**:
+- "List customers" → `GET /api/Customer/`
+- "Show customer ALFKI" → `GET /api/Customer/ALFKI/`
+- "Set ALFKI credit to 5000" → `PATCH /api/Customer/ALFKI/` with CreditLimit
+- "What's ALFKI's balance?" → `GET /api/Customer/ALFKI/` then extract Balance attribute
+
+**Key Principle**: Constraint violations (code 2001) demonstrate that declarative business logic is working correctly - celebrate these as successes, not failures!
+
+See `docs/training/MCP_Copilot_Integration.md` for comprehensive guide including JSON:API payload formats, authentication workflows, and architecture details.
+
+### API Interaction Best Practices
+
+**CRITICAL: Always Use API, Not Direct Database Access**
+
+When users request data operations (read, update, create, delete), **ALWAYS use the REST API** instead of direct database queries:
+
+✅ **Correct Approach - Use API:**
+```bash
+# Simple, readable commands that trigger business logic
+curl 'http://localhost:5656/api/Customer/?page[limit]=100'
+curl -X PATCH 'http://localhost:5656/api/Item/2/' \
+  -H 'Content-Type: application/vnd.api+json' \
+  -d '{"data": {"type": "Item", "id": "2", "attributes": {"quantity": 100}}}'
+```
+
+❌ **Wrong Approach - Direct Database:**
+```bash
+# DON'T use sqlite3 commands for data operations
+sqlite3 database/db.sqlite "UPDATE item SET quantity=100 WHERE id=2"
+```
+
+**Why API is Required:**
+1. **Business Logic Execution** - Rules automatically fire (calculations, validations, constraints)
+2. **Data Integrity** - Cascading updates handled correctly
+3. **Audit Trail** - Operations logged through proper channels
+4. **Security** - Authentication/authorization enforced
+5. **Testing Reality** - Tests actual system behavior
+
+**Server Startup for API Operations:**
+
+When server needs to be started for API operations:
+
+```bash
+# Option 1: Background process (for interactive testing)
+python api_logic_server_run.py &
+sleep 5  # Wait for full startup (not 3 seconds - too short!)
+
+# Option 2: Use existing terminal/process
+# Check if already running: lsof -i :5656
+```
+
+**Common Mistakes to Avoid:**
+
+1. ❌ **Insufficient startup wait**: `sleep 3` often fails
+   - ✅ Use: `sleep 5` or check with `curl` in retry loop
+
+2. ❌ **Complex inline Python**: Piping JSON to `python3 -c` with complex list comprehensions
+   - ✅ Use: Simple `curl` commands, pipe to `jq` for filtering, or save to file first
+
+3. ❌ **Database queries for CRUD**: Using `sqlite3` commands
+   - ✅ Use: API endpoints that trigger business logic
+
+**Simple API Query Patterns:**
+
+```bash
+# Get all records (simple, reliable)
+curl 'http://localhost:5656/api/Customer/'
+
+# Get specific record by ID
+curl 'http://localhost:5656/api/Customer/1/'
+
+# Get related records (follow relationships)
+curl 'http://localhost:5656/api/Customer/1/OrderList'
+
+# Filter results (use bracket notation)
+curl 'http://localhost:5656/api/Customer/?filter[name]=Alice'
+
+# Limit results
+curl 'http://localhost:5656/api/Customer/?page[limit]=10'
+```
+
+**Parsing JSON Responses:**
+
+```bash
+# Simple: Pipe to python -m json.tool for pretty printing
+curl 'http://localhost:5656/api/Customer/' | python3 -m json.tool
+
+# Better: Use jq if available
+curl 'http://localhost:5656/api/Customer/' | jq '.data[] | {id, name: .attributes.name}'
+
+# Alternative: Save to file first, then parse
+curl 'http://localhost:5656/api/Customer/' > customers.json
+python3 -c "import json; data=json.load(open('customers.json')); print(data['data'][0])"
+```
+
+**Key Principle**: The API is not just a convenience - it's the **only correct way** to interact with data because it ensures business logic executes properly.
+
 ### Automated Testing
 
 **CRITICAL WORKFLOW - When User Says "Create Tests":**

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

@@ -0,0 +1,295 @@
+# MCP Integration Guide for Copilot
+
+## Overview
+
+This GenAI-Logic project implements **MCP Server Executor** architecture - providing business logic services that AI assistants (like GitHub Copilot) can invoke to read and update database entities using natural language.
+
+**Key Distinction**: GenAI-Logic is NOT a standard "MCP Protocol Server" (JSON-RPC over stdio). Instead, it's a **business logic microservice** that AI assistants interact with via authenticated REST API calls. This architecture is more scalable and enterprise-ready than stdio-based MCP servers.
+
+## Architecture
+
+```
+┌─────────────────────────────────┐
+│  GitHub Copilot / Claude        │  Natural language interface
+│  (MCP Client / AI Assistant)    │
+└────────────┬────────────────────┘
+             │ HTTP REST API (JSON:API format)
+             │ JWT Authentication
+┌────────────▼────────────────────┐
+│  GenAI-Logic Server             │  MCP Server Executor
+│  (Flask + LogicBank)            │  - Business logic enforcement
+│                                 │  - Constraint validation
+│  Endpoints:                     │  - Declarative rules (44X reduction)
+│  - /api/auth/login              │  - Schema metadata
+│  - /api/{Entity}                │
+│  - /.well-known/mcp.json        │
+│  - /mcp                         │
+└────────────┬────────────────────┘
+             │
+┌────────────▼────────────────────┐
+│  Database (SQLAlchemy ORM)      │
+└─────────────────────────────────┘
+```
+
+## How Copilot Acts as MCP Client
+
+GitHub Copilot can serve as an interactive MCP client by:
+
+1. **Authenticating** - Login to obtain JWT token
+2. **Translating** - Convert natural language to API operations
+3. **Executing** - Make authenticated HTTP calls
+4. **Reporting** - Present results or explain constraint violations
+
+## Copilot Usage Pattern
+
+### Step 1: Authentication
+
+When user requests database operations, Copilot should first authenticate:
+
+```bash
+curl -X POST http://localhost:5656/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"p"}'
+```
+
+Response contains JWT token:
+```json
+{
+  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
+  "token_type": "Bearer"
+}
+```
+
+### Step 2: Execute Operations
+
+Use token for authenticated requests:
+
+#### Read Operations (GET)
+```bash
+# List customers
+curl -X GET http://localhost:5656/api/Customer/ \
+  -H "Authorization: Bearer {token}"
+
+# Get specific customer
+curl -X GET http://localhost:5656/api/Customer/ALFKI/ \
+  -H "Authorization: Bearer {token}"
+```
+
+#### Update Operations (PATCH)
+```bash
+# Update customer credit limit
+curl -X PATCH http://localhost:5656/api/Customer/ALFKI/ \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/vnd.api+json" \
+  -d '{
+    "data": {
+      "type": "Customer",
+      "id": "ALFKI",
+      "attributes": {
+        "CreditLimit": 5000
+      }
+    }
+  }'
+```
+
+#### Create Operations (POST)
+```bash
+# Create new customer
+curl -X POST http://localhost:5656/api/Customer/ \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/vnd.api+json" \
+  -d '{
+    "data": {
+      "type": "Customer",
+      "attributes": {
+        "Id": "NEWCO",
+        "CompanyName": "New Company Inc",
+        "ContactName": "John Doe",
+        "CreditLimit": 1000
+      }
+    }
+  }'
+```
+
+### Step 3: Handle Constraint Violations
+
+**CRITICAL**: Constraint violations are SUCCESS demonstrations of business logic!
+
+When an update violates business rules, the server returns error code 2001:
+
+```json
+{
+  "error": {
+    "code": 2001,
+    "message": "balance (2102.00) exceeds credit (1000.00)"
+  }
+}
+```
+
+**Copilot should report this as**: "✅ Business logic working correctly - constraint prevented invalid update: balance exceeds credit limit"
+
+Common constraint codes:
+- **2001** - Business rule violation (the valuable demonstration!)
+- **401** - Unauthorized (need to authenticate)
+- **404** - Entity not found
+- **422** - Validation error
+
+## Natural Language → API Translation Examples
+
+| User Request | Copilot Action | API Call |
+|--------------|----------------|----------|
+| "List all customers" | GET collection | `GET /api/Customer/` |
+| "Show customer ALFKI" | GET single entity | `GET /api/Customer/ALFKI/` |
+| "Update ALFKI credit to 5000" | PATCH entity | `PATCH /api/Customer/ALFKI/` with CreditLimit |
+| "What's ALFKI's balance?" | GET entity, extract attribute | `GET /api/Customer/ALFKI/` → read Balance |
+| "Increase ALFKI credit by 1000" | GET then PATCH | GET current → calculate → PATCH new value |
+| "Create customer NEWCO" | POST entity | `POST /api/Customer/` with attributes |
+
+## MCP Discovery Endpoints
+
+The server exposes schema metadata for AI assistants:
+
+### Well-Known Endpoint
+```bash
+curl http://localhost:5656/.well-known/mcp.json
+```
+
+Returns full schema including:
+- Available entities (tables)
+- Attributes and types
+- Relationships
+- Business rules documentation
+
+### MCP Endpoint
+```bash
+curl http://localhost:5656/mcp
+```
+
+Same schema as well-known endpoint, alternate path for compatibility.
+
+## Key Implementation Files
+
+- **`api/api_discovery/mcp_discovery.py`** - MCP discovery endpoints
+- **`integration/mcp/mcp_client_executor.py`** - Example MCP client script
+- **`docs/mcp_learning/mcp_schema.json`** - Schema metadata
+- **`logic/declare_logic.py`** - Declarative business rules (LogicBank)
+- **`config/default.env`** - Server configuration (SECURITY_ENABLED)
+
+## Testing Workflow for Copilot
+
+When user says: "Can you query the database for me?"
+
+1. **Acknowledge**: "I'll act as MCP client and query the server"
+2. **Authenticate**: Login via `/api/auth/login` to get JWT token
+3. **Execute**: Make appropriate GET/PATCH/POST call with Bearer token
+4. **Present**: Format results or explain constraint violations as logic success
+5. **Iterate**: Accept follow-up natural language requests
+
+Example interaction:
+```
+User: "List customers with balance over 1000"
+Copilot: 
+  1. Login to get token
+  2. GET /api/Customer/?filter[Balance]=>1000
+  3. Present: "Found 3 customers: ALFKI (2102.00), ANATR (1500.50), ..."
+
+User: "Try to set ALFKI credit to 500"
+Copilot:
+  1. PATCH /api/Customer/ALFKI/ with CreditLimit=500
+  2. Receive error 2001: "balance (2102.00) exceeds credit (500.00)"
+  3. Present: "✅ Business logic prevented this - ALFKI's balance of 2102.00 
+     exceeds the proposed credit limit of 500.00. The system is correctly 
+     enforcing the constraint that credit must be >= balance."
+```
+
+## Business Logic Layer (LogicBank)
+
+The real power is in declarative business rules that auto-execute on all API operations:
+
+```python
+# From logic/declare_logic.py
+
+# Constraint: Customer balance cannot exceed credit limit
+Rule.constraint(validate=models.Customer,
+    as_condition=lambda row: row.Balance <= row.CreditLimit,
+    error_msg="balance ({row.Balance}) exceeds credit ({row.CreditLimit})")
+
+# Sum rule: Customer balance = sum of unpaid order amounts
+Rule.sum(derive=models.Customer.Balance, 
+    as_sum_of=models.Order.AmountTotal,
+    where=lambda row: row.ShippedDate is None)
+
+# Formula: Order amount = sum of items
+Rule.sum(derive=models.Order.AmountTotal,
+    as_sum_of=models.OrderDetail.Amount)
+```
+
+These rules:
+- Execute automatically on INSERT/UPDATE/DELETE
+- Provide **44X code reduction** vs. traditional procedural code
+- Enforce multi-table constraints
+- Chain automatically (Order → Customer balance)
+
+## Why This Architecture?
+
+**GenAI-Logic's HTTP-based approach** vs **stdio-based MCP servers**:
+
+| Aspect | GenAI-Logic (HTTP) | Stdio MCP |
+|--------|-------------------|-----------|
+| Transport | HTTP REST API | JSON-RPC over stdin/stdout |
+| Authentication | JWT Bearer tokens | Process isolation |
+| Scalability | Horizontal scaling | One process per client |
+| Network | Works across machines | Same machine only |
+| Protocol | JSON:API standard | Custom JSON-RPC |
+| Enterprise Ready | ✅ Yes | ⚠️ Limited |
+
+For Microsoft demo: Position GenAI-Logic as the **business logic layer** that any MCP client can invoke, rather than trying to fit into stdio-based protocol constraints.
+
+## Optional: JSON-RPC Wrapper
+
+If standard MCP protocol compatibility is desired, you could add a thin JSON-RPC wrapper:
+
+```python
+# Optional enhancement - not required for Copilot usage
+@app.route('/mcp/jsonrpc', methods=['POST'])
+def mcp_jsonrpc():
+    """Translate JSON-RPC 2.0 to internal API calls"""
+    request_data = request.json
+    method = request_data.get('method')
+    params = request_data.get('params', {})
+    
+    if method == 'customers/list':
+        # Translate to GET /api/Customer/
+        response = internal_api_call('GET', '/api/Customer/', params)
+        return jsonify({'jsonrpc': '2.0', 'result': response, 'id': request_data['id']})
+    # ... more method translations
+```
+
+**Effort estimate**: Half-day for experienced developer. But this is optional - Copilot can work directly with REST API.
+
+## Demo Strategy
+
+For Microsoft presentation:
+
+1. **Position correctly**: "GenAI-Logic implements MCP Server Executor - the valuable business logic layer"
+2. **Show constraint violations**: "Error 2001 is the success - logic is working!"
+3. **Demonstrate declarative rules**: "44X code reduction with automatic multi-table chaining"
+4. **Use Copilot as client**: "AI assistant translates natural language to authenticated API calls"
+5. **Highlight enterprise architecture**: "HTTP-based, JWT auth, horizontally scalable"
+
+The MCP discovery endpoints (`/.well-known/mcp.json` and `/mcp`) allow AI assistants to understand the schema and available operations, but the real innovation is the declarative business logic layer that enforces rules automatically.
+
+## Quick Reference for Copilot
+
+**Authentication**:
+```bash
+curl -X POST http://localhost:5656/api/auth/login -d '{"username":"admin","password":"p"}'
+```
+
+**Common operations**:
+- List: `GET /api/{Entity}/` with Bearer token
+- Read: `GET /api/{Entity}/{id}/` with Bearer token  
+- Update: `PATCH /api/{Entity}/{id}/` with JSON:API payload and Bearer token
+- Create: `POST /api/{Entity}/` with JSON:API payload and Bearer token
+
+**Remember**: Constraint violations (code 2001) = business logic success! Report them positively.