ApiLogicServer 15.0.52__py3-none-any.whl → 15.0.54__py3-none-any.whl

api_logic_server_cli/api_logic_server.py

@@ -12,9 +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.00.52"  # last public release: 15.00.47 (15.00.12)
+__version__ = "15.00.54"  # last public release: 15.00.52 (15.00.12)
 recent_changes = \
     f'\n\nRecent Changes:\n' +\
+    "\t07/23/2024 - 15.00.54: system vibe support \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"\
@@ -390,6 +391,7 @@ def create_project_and_overlay_prototypes(project: 'ProjectRun', msg: str) -> st
                 joinpath('prototypes/basic_demo')
             recursive_overwrite(nw_dir, project.project_directory)
             create_utils.copy_md(project = project, from_doc_file = "Sample-Basic-Demo.md")
+            create_utils.copy_md(project = project, from_doc_file = "Sample-Basic-Demo-Vibe.md", to_project_file="README-VIBE.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: July 20, 2025 08:02:02
-last_created_project_name: samples/nw_sample_nocust
-last_created_version: 15.00.52
+last_created_date: July 23, 2025 12:12:14
+last_created_project_name: ../../../servers/basic_demo
+last_created_version: 15.00.53

api_logic_server_cli/create_from_model/api_logic_server_utils.py

@@ -197,6 +197,12 @@ def copy_md(project, from_doc_file: str, to_project_file: str = "README.md"):
                     else:
                         each_line = each_line.replace('.md', '')  # hmm... todo: find out why this exists
                     pass
+                if from_doc_file == 'Sample-Basic-Demo-Vibe.md' and 'title=' in each_line:
+                    # extract the quoted text after 'title=' into title
+                    match = re.search(r'title\s*=\s*["\']([^"\']+)["\']', each_line)
+                    if match:
+                        title = match.group(1)
+                    readme_lines_md.append('**' + title + ':**\n')
                 readme_lines_md.append(each_line)
         with open(str(to_file), "w") as readme_file:
             readme_file.writelines(readme_lines_md)

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

@@ -37,11 +37,14 @@ python api_logic_server_run.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 CoPilotP
+Here's the natural language logic to provide to CoPilot:
 
 ```text
 Use case: Check Credit    
@@ -126,6 +129,8 @@ 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`.
 
 ### Security - Role-Based Access Control
@@ -164,9 +169,13 @@ def my_endpoint():
     return {"message": "Custom endpoint"}
 ```
 
-### Customize Models - Add Attributes
+### Customize Models - Add Tables, Attributes
+
+Update `database/model.py`, and use `database/alembic` to update the database (highly impactful - request permission).  This is *generally* preferrable to updating the database directly, since some platforms may not have database CLI tools.
 
-Update the model, and use `database/alembic` to update the database (highly impactful - request permission).
+If altering `database/models.py`, be sure to follow the patterns shown in the existing models.  Note they not typically contain a `__bind_key__`.
+
+```python
 
 ### Addressing `Missing Attributes` during logic loading at project startup
 
@@ -216,6 +225,33 @@ 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_logic_server_cli/prototypes/base/database/alembic/alembic_run.py

@@ -0,0 +1,98 @@
+import os
+import subprocess
+import sys
+
+'''
+Pushes the current database/models.py to the database.
+python database/alembic/alembic_run.py [--non-interactive]
+'''
+
+def prompt(msg, non_interactive=False):
+    if non_interactive:
+        print(f"{msg}")
+        print("Running in non-interactive mode...")
+        return
+    try:
+        input(f"{msg}\nPress Enter to continue or Ctrl+C to abort...")
+    except EOFError:
+        print("Running in non-interactive mode (no stdin available)...")
+        return
+
+def run(cmd, env=None):
+    print(f"Running: {cmd}")
+    result = subprocess.run(cmd, shell=True, env=env)
+    if result.returncode != 0:
+        print(f"Command failed: {cmd}")
+        sys.exit(result.returncode)
+
+def main():
+    # Check for non-interactive mode more safely
+    non_interactive = "--non-interactive" in sys.argv
+    if not non_interactive:
+        try:
+            non_interactive = not sys.stdin.isatty()
+        except:
+            # If we can't check stdin, assume non-interactive
+            non_interactive = True
+    
+    orig_dir = os.getcwd()
+    # Change to the database directory (parent of alembic directory) where alembic.ini is located
+    db_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    print(f"Changing directory to {db_dir}")
+    os.chdir(db_dir)
+
+    env = os.environ.copy()
+    env["APILOGICPROJECT_NO_FLASK"] = "True"  # ~ export APILOGICPROJECT_NO_FLASK=True
+
+    print("\n\nThis script will update your database schema to match models.py using Alembic.")
+    print("Steps:")
+    print("1. Set APILOGICPROJECT_NO_FLASK=True -- eg, export APILOGICPROJECT_NO_FLASK=True")
+    print("2. Run: alembic upgrade head")
+    print("3. Run: alembic revision --autogenerate -m \"message\"")
+    prompt("Ready to proceed?", non_interactive)
+
+    run("alembic upgrade head", env=env)
+    print("Database schema updated to latest migration.")
+
+    prompt("Now, a new migration will be generated to match models.py.", non_interactive)
+    if non_interactive:
+        msg = "autogenerated"
+    else:
+        try:
+            msg = input("Enter a message for the migration (default: 'autogenerated'): ") or "autogenerated"
+        except EOFError:
+            msg = "autogenerated"
+    run(f'alembic revision --autogenerate -m "{msg}"', env=env)
+
+    # Find the latest migration file
+    versions_dir = os.path.join(db_dir, "alembic", "versions")
+    migration_files = sorted(
+        [f for f in os.listdir(versions_dir) if f.endswith(".py")],
+        key=lambda x: os.path.getmtime(os.path.join(versions_dir, x)),
+        reverse=True
+    )
+    if migration_files:
+        latest_file = os.path.join(versions_dir, migration_files[0])
+        with open(latest_file, "r") as f:
+            lines = f.readlines()
+        with open(latest_file, "w") as f:
+            for line in lines:
+                f.write(line)
+                if line.strip().startswith("def downgrade"):
+                    f.write("    return\n")
+                    break
+    else:
+        print("No migration file found.")
+        sys.exit(1)
+
+    # Apply the newly generated migration after modifying the migration file
+    prompt(f"Migration file generated: {latest_file}\nIt is recommended to review this migration file before proceeding.", non_interactive)
+    run("alembic upgrade head", env=env)
+
+    print("Migration file updated: downgrade will do nothing.")
+    print("Consider updating ui/admin/admin.yaml to reflect schema changes.")
+    os.chdir(orig_dir)
+    print("\nSuccess! Database schema and migrations are up to date.\n\n")
+
+if __name__ == "__main__":
+    main()

api_logic_server_cli/prototypes/base/database/alembic/readme_alembic.md

@@ -0,0 +1,36 @@
+You can push changes to `database/models.py' to your database automatically, or manually.
+
+<br>
+
+## Automatic
+
+Use:
+
+```bash
+python database/alembic/alembic_run.py [--non-interactive]
+```
+
+<br>
+
+## Manual
+
+The diagram below illustrates a path for enacting changes to the data model, and using [Alembic](https://alembic.sqlalchemy.org/en/latest/index.html) to automate the database changes:
+
+1. Update `database/models.py` (e.g., add columns, tables)
+2. Use alembic to compute the revisions
+```bash
+cd database
+export APILOGICPROJECT_NO_FLASK=True
+alembic revision --autogenerate -m "Added Tables and Columns"
+```
+3. **Edit the revision file** to signify your understanding (see below)
+4. Activate the change
+```bash
+alembic upgrade head 
+unset APILOGICPROJECT_NO_FLASK
+```
+
+![alembic example](https://github.com/ApiLogicServer/Docs/blob/main/docs/images/database/alembic/alembic-overview.png?raw=true)
+
+
+To update your admin app, run `rebuild-from-model`.  For more information, see [Database Design Changes](https://apilogicserver.github.io/Docs/Database-Changes/).

api_logic_server_cli/prototypes/base/docs/training/admin_app_1_context.prompt.md

@@ -1,3 +1,43 @@
 
 Generate a full React Admin application using the following instructions.  
 The result must be a runnable React app (`npm start`) that connects to the supplied JSON:API, with fully implemented components (no placeholders or empty files).
+
+## Critical Data Access Provider Configuration
+
+This project uses a **pre-configured JSON:API data provider** that was built when the project was created. 
+
+### Key Requirements:
+
+1. **Data Provider**: Use the existing `jsonapiClient` from `./rav4-jsonapi-client/ra-jsonapi-client`
+2. **Record Context**: For custom components (like cards), ALWAYS wrap with `<RecordContextProvider value={record}>` 
+3. **List Data Access**: Use `useListContext()` to get data and loading state
+4. **Individual Records**: Use `useRecordContext()` to access record data within providers
+5. **API Root**: The data provider connects to `conf.api_root` (typically `http://localhost:5656/api`)
+
+### Example Pattern for Custom List Views:
+```javascript
+import { useListContext, RecordContextProvider, useRecordContext } from 'react-admin';
+
+const CustomGrid = () => {
+    const { data, isLoading } = useListContext();
+    
+    return (
+        <Grid container>
+            {data?.map(record => (
+                <Grid item key={record.id}>
+                    <RecordContextProvider value={record}>
+                        <CustomCard />
+                    </RecordContextProvider>
+                </Grid>
+            ))}
+        </Grid>
+    );
+};
+
+const CustomCard = () => {
+    const record = useRecordContext();
+    return <Card>{record.name}</Card>;
+};
+```
+
+### CRITICAL: Do NOT create new data providers or modify the existing JSON:API client configuration. The project's data flow depends on the pre-built provider.

api_logic_server_cli/prototypes/base/integration/mcp/mcp_client_executor.py

@@ -147,12 +147,12 @@ def query_llm_with_nl(learnings_and_schema: str, nl_query: str):
     else:
         # read integration/mcp/mcp_tool_context.json
         tool_context_file_path = os.path.join(os.path.dirname(__file__), "../../integration/mcp/examples/mcp_tool_context_response_get.json")
-        if nl_query == default_query_email:
+        if 'send email' in nl_query:
             tool_context_file_path = os.path.join(os.path.dirname(__file__), "../../integration/mcp/examples/mcp_tool_context_response.json")
         try:    
             with open(tool_context_file_path, "r") as tool_context_file:
                 tool_context_str = tool_context_file.read()
-                # log.info(f"\n\n2c. Tool context from file {tool_context_file_path}:\n" + tool_context_str)
+                log.info(f"\n\n2c. Tool context from file {tool_context_file_path}:\n" + tool_context_str)
         except FileNotFoundError:
             raise ConstraintException(f"Tool context file not found at {tool_context_file_path}.")
 

api_logic_server_cli/prototypes/basic_demo/_config.yml

@@ -0,0 +1,8 @@
+# GitHub Pages / Jekyll Configuration
+# Enable processing of markdown files
+markdown: kramdown
+highlighter: rouge
+
+# Include the _layouts directory
+include:
+  - _layouts

api_logic_server_cli/prototypes/basic_demo/_layouts/redirect.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="refresh" content="1;url={{ page.redirect }}" />
+    <link rel="canonical" href="{{ page.redirect }}" />
+    <script type="text/javascript">
+      window.location.href = "{{ page.redirect }}"
+    </script>
+    <title>Page Redirection</title>
+  </head>
+  <body>
+    If you are not redirected automatically, follow <a href='{{ page.redirect }}'>this link</a>.
+  </body>
+</html>

api_logic_server_cli/prototypes/basic_demo/docs/system-creation-vibe.md

@@ -0,0 +1,161 @@
+---
+title: Vibe MCP / Microservice
+version: 0.23 from docsite 7/11/2025
+---
+<style>
+  .md-typeset h1,
+  .md-content__button {
+    display: none;
+  }
+</style>
+
+<< Under Construction >>
+
+# Vibe an MCP Microservice
+
+See the Readme for detailed walk through.
+
+Scenario: we have an existing database (customers, order, items and product), and we require:
+
+* An MCP-enabled API, for integration
+* MCP client support to send emails for overdue orders
+* Business Logic to check credit by rolling up Items and Orders.
+
+This is a record of how we created the system using CoPilot Chat (*Vibe*).
+
+<br>
+
+## Initialize CoPilot
+
+```
+Please find and read `.github/.copilot-instructions.md`.
+```
+
+<br>
+
+## Create the System
+
+```bash title="Create a project from an existing database"
+# in the GenAI-Logic Manager:
+Create a database project from samples/dbs/basic_demo.sqlite
+```
+
+<br>
+
+## Verify the API and Admin App
+
+The project should automatically open a new window in VSCode.  Again, open CoPilot and bootstrap it with: <br>
+
+```bash title="Initialize CoPilot"
+Please find and read `.github/.copilot-instructions.md`**.
+```
+
+Verify it as follows:
+
+* **Click F5** to start server, open app at http://localhost:5656/
+* **Verify API:** filtering, sorting, pagination, optimistic locking and related data access - see the Swagger
+* **Verify Admin App:** multi-page, multi-table, automatic joins, lookups, cascade add - collaboration-ready
+
+<br>
+
+## Create a Custom React App
+
+**Create Start App**
+```bash title="Create a custom react app"
+Create a react app.
+```
+
+<br>
+
+**Customize - add cards**
+```txt title='Customize using Natural Language'
+In the ui/react app, update the Product list to provide users an option to see results in a list,
+or in cards.
+```
+<br>
+
+todo - diagram 
+
+**Test: verify option for cards on `http://localhost:3000`**
+
+<br>
+
+## MCP Client - Overdue Orders
+
+**Stop the Server**
+
+<br>
+
+**Create MCP Executor: process request - invokes the LLM to obtain a series of API calls to run, and runs them**
+``` bash title="Create an MCP Client Executor"
+Create the mcp client executor
+```
+<br>
+
+**Add a Table to Track Sent Emails**
+``` bash title="Add a Table to Track Sent Emails"
+Create a table SysEmail in `database/db.sqlite` as a child of customer, 
+with columns id, message, subject, customer_id and CreatedOn.
+```
+Follow the suggestions to update the admin app.
+
+<br>
+
+**Create the email service stub using SysEmail as a Request Table**
+``` bash title="Create the email service using SysEmail as a Request Table"
+Add an after_flush event on SysEmail to produce a log message "email sent",
+unless the customer has opted out.
+```
+
+<br>
+
+**Business Logic to Honor Email Opt-out**
+```bash title="Business Logic to Honor Email Opt-out"
+Add an after_flush event on SysEmail to produce a log message "email sent",
+unless the customer has opted out.
+```
+
+<br>
+
+**Test: restart the server/admin app - Click SysMCP >> Create New, and enter:**
+```text title="Test the MCP Client: Click SysMCP >> Create New, and enter"
+List the orders date_shipped is null and CreatedOn before 2023-07-14, 
+and send a discount email (subject: 'Discount Offer') to the customer for each one.
+```
+
+<br>
+todo - diagram 
+
+**Use the Admin App to Verify the first customer has an email**
+
+<br>
+
+## Check Credit Business Logic
+
+**1. Stop the Server** (Red Stop button, or Shift-F5 -- see Appendix)
+
+**2. Add Business Logic**
+
+```bash title="Check Credit Logic (instead of 220 lines of code)"
+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.
+```
+
+To test the logic:
+
+**1. Use the Admin App to access the first order for `Customer Alice`**
+
+**2. Edit its first item to a very high quantity**
+
+todo - diagram 
+
+The update is properly rejected because it exceeds the credit limit.  Observe the rules firing in the console log - see Logic In Action, below.
+
+<br>

api_logic_server_cli/prototypes/basic_demo/logic/declarative-vs-procedural-comparison.html

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>Page Moved - Declarative vs Procedural Comparison</title>
+    <meta http-equiv="refresh" content="3; url=https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html">
+    <link rel="canonical" href="https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html">
+    <style>
+        body { 
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif; 
+            max-width: 600px; 
+            margin: 50px auto; 
+            padding: 20px;
+            line-height: 1.6;
+        }
+        .redirect-box { 
+            border: 2px solid #007acc; 
+            padding: 30px; 
+            border-radius: 8px; 
+            background: linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%);
+            box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+        }
+        .countdown { 
+            font-weight: bold; 
+            color: #007acc; 
+            font-size: 1.2em;
+        }
+        .manual-link {
+            display: inline-block;
+            background: #007acc;
+            color: white;
+            padding: 12px 24px;
+            text-decoration: none;
+            border-radius: 5px;
+            margin: 10px 0;
+            font-weight: bold;
+        }
+        .manual-link:hover {
+            background: #005c99;
+        }
+        h1 { color: #333; margin-top: 0; }
+        .progress-bar {
+            width: 100%;
+            height: 6px;
+            background: #ddd;
+            border-radius: 3px;
+            margin: 15px 0;
+            overflow: hidden;
+        }
+        .progress-fill {
+            height: 100%;
+            background: #007acc;
+            width: 100%;
+            transition: width 1s linear;
+        }
+    </style>
+    <script>
+        let seconds = 3;
+        function redirect() {
+            window.location.href = "https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html";
+        }
+        function updateCountdown() {
+            const countdownElement = document.getElementById('countdown');
+            const progressElement = document.getElementById('progress-fill');
+            
+            if (countdownElement) {
+                countdownElement.textContent = seconds;
+            }
+            if (progressElement) {
+                progressElement.style.width = ((3-seconds)/3 * 100) + '%';
+            }
+            
+            if (seconds <= 0) {
+                redirect();
+            } else {
+                seconds--;
+                setTimeout(updateCountdown, 1000);
+            }
+        }
+        window.onload = function() {
+            updateCountdown();
+            // Fallback redirect in case JavaScript fails
+            setTimeout(redirect, 3100);
+        }
+    </script>
+</head>
+<body>
+    <div class="redirect-box">
+        <h1>📄 Page Moved</h1>
+        <p>The <strong>Declarative vs Procedural Logic Comparison</strong> has moved to a new location.</p>
+        
+        <div class="progress-bar">
+            <div id="progress-fill" class="progress-fill" style="width: 0%;"></div>
+        </div>
+        
+        <p>Redirecting automatically in <span id="countdown" class="countdown">3</span> seconds...</p>
+        
+        <p><strong>If you are not redirected automatically:</strong></p>
+        <a href="https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html" class="manual-link">
+            👉 Go to New Location
+        </a>
+        
+        <hr style="margin: 25px 0; border: none; border-top: 1px solid #ddd;">
+        <p><small>
+            <strong>New URL:</strong><br>
+            <code>https://apilogicserver.github.io/basic_demo/logic/procedural/declarative-vs-procedural-comparison.html</code>
+        </small></p>
+    </div>
+</body>
+</html>