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

api_logic_server_cli/prototypes/manager/system/ApiLogicServer-Internal-Dev/copilot-dev-context.md

@@ -1,3 +1,15 @@
+---
+title: Context Restoration for BLT Manager Workspace
+Description: Re-establishes AI assistant context after BLT regenerates workspace
+Source: ApiLogicServer-src/prototypes/manager/system/ApiLogicServer-Internal-Dev/copilot-dev-context.md
+Propagation: BLT process → Manager workspace
+Usage: AI assistants read this to understand project structure, development workflow, and recent additions
+version: 2.0
+changelog:
+  - 2.0 (Oct 2025) - Added AI-Guided Training section (tutor.md v2.0, OBX improvements, design philosophy)
+  - 1.0 (Initial) - Established workspace structure, GenAI prompt engineering, development workflow
+---
+
 # Context Restoration: BLT Manager Workspace
 
 **Purpose:** This file re-establishes AI assistant context after BLT runs regenerate this workspace.
@@ -83,7 +95,7 @@ This document contains **everything** you need to understand the system:
 
 ### For Working Within Created Projects:
 - **Project-level `.copilot-instructions.md`** - How to EXTEND/CUSTOMIZE projects (auto-generated in each project)
-  - **Location:** `prototypes/base/.github/.copilot-instructions.md` (template)
+  - **Location:** `prototypes/base/.github/.copilot-instructions.md` (template) and `prototypes/basic_demo/.github/.copilot-instructions.md` (tutorial version)
   - **Size:** ~740 lines
   - **Scope:** Complete architecture guide for EACH created project
   - **Purpose:** 13 Main Services (what AI can do in a project):
@@ -101,7 +113,12 @@ This document contains **everything** you need to understand the system:
     12. **Adding Events** - Row events for integrations (Kafka, webhooks, etc.)
     13. **Critical Patterns** - React component best practices, null-safe constraints, test repeatability
   - ⚠️ **CRITICAL:** These are TWO DIFFERENT FILES - never replace the per-project version with the manager version!
-  - 🚨 **PROPAGATION PROBLEM:** Changes to project-level instructions must be carefully copied to `prototypes/base/.github/.copilot-instructions.md`
+  - 🚨 **PROPAGATION PROBLEM:** Changes to project-level instructions must be carefully copied to both `prototypes/base/.github/.copilot-instructions.md` AND `prototypes/basic_demo/.github/.copilot-instructions.md`
+  - 📋 **OBX PATTERN (v2.3, Oct 2025):** Use **positive instructions** for AI behavior:
+    - ✅ **Works:** "When user asks to read instructions, respond with the Welcome section content below"
+    - ❌ **Fails:** "Do NOT add preamble" or relying on structure alone
+    - **Theory:** Tell AI what TO do, not what NOT to do
+    - **Result:** Clean welcome message without meta-commentary ("I've read the instructions...")
 - **`docs/training/logic_bank_api.prompt`** - LogicBank API reference (Rosetta Stone for rules)
 - **`docs/training/testing.md`** - Behave testing guide (1755 lines, read BEFORE creating tests)
 
@@ -110,6 +127,77 @@ This document contains **everything** you need to understand the system:
 - **[Installation Guide](https://apilogicserver.github.io/Docs/Install/)** - Setup procedures
 - **[Tutorial](https://apilogicserver.github.io/Docs/Tutorial/)** - Step-by-step learning
 
+### For AI-Guided Training (New Feature):
+- **`basic_demo/tutor.md`** - AI assistant guide for conducting 30-45 min hands-on tour
+  - **Version:** 2.0 (762 lines, October 2025)
+  - **Purpose:** "Message in a bottle" for AI assistants - enables guided discovery learning
+  - **Method:** Provocation-based (e.g., "how did it know ORDER has a foreign key to Customer?")
+  - **Philosophy:** Users learn by DOING (hands-on tour), not reading docs or taking quizzes (Versata approach)
+  - **Structure:** 9 sections with timing checkpoints (15 min, 35 min), concrete metrics (48 vs 200+ lines)
+  - **Key Additions in v2.0:** Spreadsheet analogy, procedural comparison (BUG FIX examples), context for schema commands, three ways to add logic (Discovery/IDE/Chat), MCP server integration
+  - **Location:** `prototypes/basic_demo/tutor.md` (template), propagates to created `basic_demo` projects
+  - **Invocation:** User says "Guide me through basic_demo" → AI reads tutor.md → conducts tour
+  
+- **Design Philosophy - Why Provocation Over Instruction:**
+  - **Problem with traditional training:** PowerPoint → quiz/assessment approach tests memorization, not understanding
+  - **Versata insight:** "Stop killing people with PowerPoint; identify critical skills, design lab to DO it"
+  - **Discovery learning:** Ask provocative questions that force pattern recognition ("How did it know ORDER references CUSTOMER?")
+  - **"Aha moments" over rote learning:** User discovers foreign keys exist, then learns they're essential for multi-table logic
+  - **Spreadsheet analogy:** Excel user understands formulas → multi-table database is "Excel for related tables"
+  - **AI as training partner DURING the lab:** Not quiz after, not docs before - real-time guidance while doing
+  - **Result:** 30-45 min hands-on experience creates deeper understanding than hours of documentation reading
+
+- **v1.0 → v2.0 Evolution (Battle-Tested Refinements):**
+  - **v1.0 (595 lines):** Initial design based on architecture understanding
+  - **Live testing:** User spent "several hours with your cousin testing and revising" actual tours
+  - **v2.0 (+506 net lines):** Added based on what users actually needed during tours:
+    - **Spreadsheet analogy** - Non-technical users needed familiar mental model
+    - **Procedural comparison** - Show 48 vs 200+ lines WITH concrete BUG FIX examples (not just line counts)
+    - **Context for commands** - Why `add-cust` exists (schema variability, new users discover structure)
+    - **Three ways to add logic** - Discovery file (recommended), IDE autocomplete, or Chat
+    - **Timing checkpoints** - 15 min at Security, 35 min at Q&A (helps pace the tour)
+    - **MCP server mention** - Claude Desktop integration for external AI access
+    - **Best practices** - `logic/logic_discovery/` organization pattern
+    - **Short response guidance** - "One idea per interaction" prevents overwhelming new users
+  - **Key learning:** Initial version was too instruction-heavy, v2.0 adds more context and concrete examples
+
+- **`add-cust` Mechanism for Tutor** - Progressive feature addition during guided tour:
+  - **Purpose:** Add pre-built customizations progressively during tour (avoids GenAI unpredictability, ensures working examples)
+  - **Battle scars:** Also serves as **error recovery** - if users make mistakes during tour, `add-cust` restores database integrity and gets them back on track
+  - **Usage in tutor:** Two `add-cust` commands progressively add features:
+    1. **First `add-cust`** (from `customizations/` folder) → adds security (RBAC filters) + check credit logic (5 rules), **restores database to known-good state**
+       - `logic/declare_logic.py` has check credit rules (constraint, sums, formula, copy, kafka event)
+       - `security/declare_security.py` has role-based filters
+       - `database/db.sqlite` restored with clean data
+    2. **Second `add-cust`** (from `iteration/` folder) → adds schema change (Product.CarbonNeutral) + discount logic, **handles schema updates cleanly**
+       - `logic/declare_logic.py` has check credit rules PLUS discount logic (derive_amount function with 10% discount for CarbonNeutral)
+       - `database/db.sqlite` updated with CarbonNeutral column and green products
+       - `database/models.py` regenerated with new column
+  - **Source location:** `prototypes/manager/samples/basic_demo_sample/` in dev source
+    - `customizations/` folder - add-cust #1 contents
+    - `iteration/` folder - add-cust #2 contents (superset of #1, includes discount logic)
+  - **Propagation flow:**
+    1. Dev source: `org_git/ApiLogicServer-src/api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/`
+    2. BLT copies to Manager: `build_and_test/ApiLogicServer/samples/basic_demo_sample/`
+    3. BLT installs to venv: `venv/.../api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/`
+    4. During tutor: `add-cust` executes from venv, copies to user's `basic_demo/` project
+  - **Key insight:** `add-cust` is a tutor utility, not a production feature - copies pre-built working examples to demonstrate patterns reliably AND recovers from user errors
+  - **Maintenance:** When updating add-cust content:
+    - Update `customizations/` for add-cust #1 changes
+    - Update `iteration/` for add-cust #2 changes (must include everything from #1 plus new content)
+    - Both folders in `prototypes/manager/samples/basic_demo_sample/` (dev source)
+    - BLT propagates to venv
+
+- **OBX (Out-of-Box Experience) Design** - Manager → Project flow optimization (October 2025):
+  - **Manager README:** "🚀 First Time Here? Start with basic_demo" section (clear default path)
+  - **Manager .copilot-instructions.md:** "CRITICAL: ALWAYS start" directive (no choices, single path)
+  - **Project README:** "🤖 Ready to Explore? Recommended: Guide me through" (guided tour as primary option)
+  - **Project .copilot-instructions.md:** "🎯 Most Common Next Steps" (5 succinct items at top)
+  - **Goal:** Eliminate friction/choice paralysis, make basic_demo → guided tour the clear default
+  - **Problem addressed:** Users didn't automatically know to start with basic_demo, didn't default to guided tour
+  - **Solution:** Strengthen every touch point in the journey to push toward the optimal path
+  - **Flow:** Install → Open Manager → Create basic_demo → Auto-opens → "Guide me through" → 30-45 min tour
+
  
 
 ## 👤 Current Maintainer
@@ -159,6 +247,186 @@ This document contains **everything** you need to understand the system:
 
  
 
+## 🤖 GenAI Prompt Engineering Architecture
+
+### Overview: ChatGPT Project Creation Pipeline
+
+The `genai-logic create` command uses **fine-tuned ChatGPT** to translate natural language requirements into complete working projects. The system uses **prompt engineering** to surround user input with structured instructions.
+
+### Key Locations
+
+**Prompt Templates:** `system/genai/prompt_inserts/`
+```
+├── sqlite_inserts.prompt                    # Main orchestrator for DB creation
+├── sqlite_inserts_model_test_hints.prompt   # SQLAlchemy class generation rules
+├── logic_inserts.prompt                     # LogicBank rule generation
+├── logic_translate.prompt                   # NL → LogicBank translation (existing DB)
+├── graphics.prompt                          # Dashboard chart generation
+├── response_format.prompt                   # WGResult Pydantic schema
+└── web_genai.prompt                         # WebGenAI-specific (15+ tables)
+```
+
+**Training Examples:** `org_git/ApiLogicServer-src/tests/genai_tests/logic_training/`
+```
+├── genai_demo.prompt                        # Check Credit + No Empty Orders
+├── ready_flag.prompt                        # Ready Flag pattern (3 use cases)
+├── emp_depts.prompt                         # Chain Up: sum salaries, constrain budget
+├── graduate.prompt                          # Cardinality: counts with thresholds
+├── products.prompt                          # Qualified Any: severity checks
+├── honor_society.prompt                     # Complex cardinality with qualified counts
+└── *.txt / *_corrected_prompt.txt           # Expected outputs and corrections
+```
+
+**Test Examples:** `system/genai/examples/`
+```
+├── genai_demo/                              # Complete example with iterations
+├── airport/                                 # Complex 10+ table system
+├── emp_depts/                               # Simple aggregation pattern
+└── time_tracking_billing/                   # Real-world scenario
+```
+
+### The Prompt Assembly Process
+
+**User Input:**
+```
+Create a system with customers, orders, items and products.
+
+Use case: Check Credit
+1. Customer.balance <= credit_limit
+2. Customer.balance = Sum(Order.amount_total where date_shipped is null)
+3. Order.amount_total = Sum(Item.amount)
+4. Item.amount = quantity * unit_price
+5. Item.unit_price = copy from Product.unit_price
+```
+
+**System Surrounds With:**
+
+1. **Model Generation Instructions** (`sqlite_inserts_model_test_hints.prompt`):
+   - Use autonum keys for ALL tables (including junction tables)
+   - Create classes, never tables (Class names singular, capitalized)
+   - **CRITICAL:** "If you create sum, count or formula Logic Bank rules, then you MUST create a corresponding column in the data model"
+   - No check constraints (logic uses rules instead)
+   - Foreign key columns (not relationship names) for test data
+
+2. **Logic Generation Instructions** (`logic_inserts.prompt`):
+   - "Use LogicBank to enforce these requirements (do not generate check constraints)"
+   - "be sure to update the data model and *all* test data with any attributes used in the logic"
+
+3. **Response Structure** (`response_format.prompt`):
+   ```python
+   class WGResult(BaseModel):
+       models: List[Model]              # SQLAlchemy classes
+       rules: List[Rule]                # LogicBank declarations
+       test_data: str                   # Python test data creation
+       test_data_rows: List[TestDataRow]
+       test_data_sqlite: str            # INSERT statements
+       graphics: List[Graphic]          # Dashboard queries
+       name: str                        # Suggested project name
+   ```
+
+**Result:** ChatGPT returns structured JSON with models, rules, and test data that:
+- Has `Customer.balance`, `Order.amount_total`, `Order.item_count` columns created automatically
+- Contains LogicBank rules for all derivations
+- Includes test data with derived attributes pre-initialized
+
+### Key Insight: Model + Logic Co-Generation
+
+**Unlike existing database projects**, GenAI creation can **modify the data model** to support logic:
+
+- **Derived attributes materialize:** `Customer.balance`, `Order.amount_total`, `Product.total_ordered`
+- **Count columns appear:** `Order.item_count` for existence checks
+- **Qualified counts split:** `Product.notice_count` + `Product.severity_five_count`
+
+This is why the training examples emphasize:
+> "If you create sum, count or formula Logic Bank rules, then you MUST create a corresponding column in the data model."
+
+### Training Pattern Categories
+
+The `logic_training/` examples teach ChatGPT these patterns:
+
+1. **Chain Up (Aggregation → Constraint)**
+   - `emp_depts`: Department.total_salary = sum(Employee.salary); salary <= budget
+   - `genai_demo`: Customer.balance = sum(orders); balance <= credit_limit
+
+2. **Counts as Existence Checks**
+   - `genai_demo`: Order.item_count = count(Items); can't ship if == 0
+   - Creates both derivation AND validation
+
+3. **Cardinality Patterns (Qualified Any)**
+   - `products`: Total notices + severity 5 notices; constraint if orderable
+   - `graduate`: Probation count + sick days; constraint for graduation
+   - Pattern: Multiple counts (total + qualified) with complex conditions
+
+4. **Ready Flag**
+   - `ready_flag`: Multi-use-case with conditional aggregations
+   - Customer.balance only sums orders where `ready == True AND date_shipped is None`
+   - Product.total_ordered only sums items where `ready == True`
+
+5. **Chain Down (Copy/Formula)**
+   - Item.unit_price = copy(Product.unit_price)
+   - Item.ready = Order.ready (formula propagation)
+
+### CLI Commands Using This System
+
+**Create from natural language:**
+```bash
+genai-logic create --project-name=my_system --using="<natural language>"
+# Internally: assembles prompts → ChatGPT → parses WGResult → generates project
+```
+
+**Translate logic (existing DB):**
+```bash
+genai-logic logic-translate --project-name=. --using-file=docs/logic
+# Uses logic_translate.prompt to convert NL in docs/logic → rules in logic/logic_discovery/
+```
+
+### Fine-Tuning Files
+
+**Training Data:** `logic_training/ft.jsonl`
+- JSONL format for ChatGPT fine-tuning
+- Generated from prompt/response pairs
+- ~374KB with all pattern examples
+
+**Script:** `logic_training/create_json_l.py`
+- Converts `*.prompt` + `*.txt` → JSONL entries
+- Format: system message, user message (prompt), assistant message (response)
+
+### Common Pitfalls (Why Corrections Exist)
+
+Several `*_corrected_prompt.txt` files show typical AI mistakes:
+
+1. **Wrong cardinality:**
+   - `airport.prompt`: Asked for "airplane's passengers" but meant "flight's passengers"
+   - AI can't count passengers on an Airplane (no direct relationship)
+   - Correction: Count passengers on Flight, constrain by Airplane.seating_capacity
+
+2. **Constraint depends on derived flag:**
+   - `products.prompt` initially: "product is orderable IF no severity 5 notices"
+   - Problem: Makes orderable a derived value, then uses it in constraint
+   - Correction: "RAISE ERROR if orderable == True AND has severity 5 notices"
+   - Pattern: Flag is input, constraint uses it (not derived from constraint conditions)
+
+3. **Negative condition logic:**
+   - Must use: `not(row.flag and bad_condition)`
+   - Not: `row.flag → requires good_condition` (harder for AI to translate)
+
+### Why This Architecture?
+
+**Traditional GenAI code generation problems:**
+- Generates 200+ lines of procedural code
+- Misses corner cases (foreign key changes, cascading updates)
+- Creates technical debt (unmaintainable spaghetti)
+
+**Declarative GenAI solution:**
+- Generates **specifications** (5 rules), not code (200 lines)
+- Rules executed by proven engine (40+ years, 6,000+ deployments)
+- Engine handles ALL change paths automatically (no corner cases missed)
+- Natural language → DSL → Runtime engine (not NL → procedural code)
+
+**Critical difference:** The AI doesn't need to "think through" all possible change paths. It translates requirements to rules, and the engine provides correctness guarantee through automatic dependency analysis and chaining.
+
+&nbsp;
+
 ## 🔄 Development Workflow
 
 **Source Repository:** https://github.com/ApiLogicServer/ApiLogicServer-src

{apilogicserver-15.2.3.dist-info → apilogicserver-15.2.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ApiLogicServer
-Version: 15.2.3
+Version: 15.2.10
 Author-email: Val Huber <apilogicserver@gmail.com>
 License-Expression: BSD-3-Clause
 Project-URL: Homepage, https://www.genai-logic.com
@@ -104,10 +104,10 @@ source venv/bin/activate                 # windows: venv\Scripts\activate
 python -m pip install ApiLogicServer
 
 # Start the Manager (opens readme with instructions)
-ApiLogicServer start
+genai-logic start
 
 # Create project from your database (or use sample)
-ApiLogicServer create --project_name=my_app --db_url=
+genai-logic create --project_name=my_app --db_url=
 
 # Run it
 cd my_app
@@ -116,11 +116,14 @@ python api_logic_server_run.py
 
 **What you get in 5 seconds:**
 - 🚀 **JSON:API** - Endpoints for every table with filtering, pagination, related data
-- 📱 **Admin App** - Multi-page React app with automatic joins
+- 📱 **Instant Admin App UI** - Multi-page React app with automatic joins (runs immediately)
+- 🎨 **Custom Apps via API** - Use the API with your favorite vibe tools (Cursor, Bolt, Lovable, etc.) OR leverage GenAI-Logic training for Copilot to build custom UIs ([see this article](https://medium.com/@valjhuber/enterprise-vibe-automation-b40c8f750a1d))
 - 🧠 **Logic Engine** - Spreadsheet-like rules (40X more concise than code)
 - 🔐 **Security** - Row-level authorization, JWT authentication
 - 🐳 **Docker-ready** - Pre-configured containers for deployment
 
+**Mix and match:** Use the instant Admin App for backoffice tasks AND build custom UIs with vibe tools for advanced features like cards and maps - all powered by the same logic-enabled API.
+
 **[📖 8-minute video demo](https://www.youtube.com/watch?v=Z4_NJIm5rFs&t=323s)** | **[📚 Full Documentation](https://apilogicserver.github.io/Docs/)** | **[🏠 Home](https://www.genai-logic.com)**
 
 ---
@@ -137,8 +140,8 @@ python api_logic_server_run.py
 | Traditional Approach | API Logic Server |
 |---------------------|------------------|
 | Weeks to create API endpoints | **5 seconds** (automated) |
-| 200+ lines of update logic code | **5 rules** (40X reduction) |
-| Manual screen painting | **Automated** from data model |
+| 200+ lines of update logic code | **5 rules** (40X reduction - to see an A/B Comparision, [click here](https://github.com/ApiLogicServer/basic_demo/blob/main/logic/procedural/declarative-vs-procedural-comparison.md) |
+| Manual screen painting | **Automated** from data model, plus vibe-enabled custom UIs |
 | Hard to integrate systems | **MCP-enabled** APIs |
 | Opaque procedural code | **Declarative** living documentation |
 
@@ -240,22 +243,28 @@ A: Join our **[Discord community](https://discord.gg/fNRTTVFT)** for real-time h
 
 ```
 my_app/
-├── api/                    # JSON:API endpoints
+├── api/                    # JSON:API endpoints (for Admin App AND custom UIs)
 │   ├── expose_api_models.py
 │   └── customize_api.py    # Add custom endpoints
-├── ui/admin/              # Admin App
+├── ui/admin/              # Instant Admin App (ready to run)
 │   └── admin.yaml         # Declare UI behavior
-├── logic/                 # Business Logic
+├── logic/                 # Business Logic (enforced on ALL API calls)
 │   └── declare_logic.py   # Spreadsheet-like rules
 ├── security/              # Authentication & Authorization
 │   └── declare_security.py
 ├── database/              # SQLAlchemy models
 │   └── models.py
 ├── tests/                 # BDD tests (Behave)
+├── docs/
+│   └── training/          # GenAI-Logic training for Copilot
 └── devops/
     └── docker/            # Deployment configs
 ```
 
+**Two UI approaches (use both!):**
+1. **Instant Admin App** - Runs immediately for backoffice/internal users
+2. **Custom UIs** - Build with vibe tools (Cursor, Bolt, etc.) OR use GenAI-Logic Copilot training to create React/Vue/Angular apps that consume the API
+
 ---
 
 ## 🚀 Key Features
@@ -310,7 +319,7 @@ GET /api/Customer?filter[Balance][$gt]=1000&sort=-Balance&page[size]=10
 
 #### Create from Natural Language
 ```bash
-ApiLogicServer genai --using=prompt.txt
+genai-logic genai --using=prompt.txt
 ```
 
 **Example prompt:**
@@ -324,24 +333,24 @@ Constraint: customer balance cannot exceed credit limit.
 ```
 
 **Result:** Working microservice with logic in 10 seconds!
-
 #### AI-Assisted Development
-Every created project includes:
-- 🤖 **Copilot instructions** (`.copilot-instructions.md`)
-- 📚 **Training materials** (`docs/training/`)
+
+Every created project includes **AI tutoring** to help you get oriented and productive quickly:
+
+- 🤖 **Copilot instructions** (`.copilot-instructions.md`) - When you open a project, Copilot presents a friendly welcome message explaining what's already built and what you can do next. Ask Copilot to "read instructions" anytime for guidance.
+- 📚 **Training materials** (`docs/training/`) - Comprehensive guides for all features
 - 🔍 **Logic from natural language** (translate English → rules)
 
 ```python
 # Paste into Copilot: "Create logic for check credit"
 # Copilot generates the 5 rules above!
 ```
-
 ### 4️⃣ Living Documentation
 
 **Automated test generation** from your rules:
 ```bash
 # Generate Behave tests from declared logic
-ApiLogicServer add-tests
+genai-logic add-tests
 
 # Run tests
 behave