ApiLogicServer 14.4.0__py3-none-any.whl → 14.5.0__py3-none-any.whl

api_logic_server_cli/prototypes/basic_demo/customizations/api/api_discovery/proper_update_def.json

@@ -0,0 +1,71 @@
+{
+    "/Customer/{id}": {
+      "patch": {
+        "summary": "Update Customer by ID",
+        "operationId": "updateCustomer",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/vnd.api+json": {
+              "schema": {
+                "type": "object",
+                "required": ["data"],
+                "properties": {
+                  "data": {
+                    "type": "object",
+                    "required": ["type", "id", "attributes"],
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "enum": ["Customer"]
+                      },
+                      "id": {
+                        "type": "string"
+                      },
+                      "attributes": {
+                        "type": "object",
+                        "properties": {
+                          "name": {
+                            "type": "string"
+                          },
+                          "credit_limit": {
+                            "type": "number"
+                          },
+                          "balance": {
+                            "type": "number"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Customer updated",
+            "content": {
+              "application/vnd.api+json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  

api_logic_server_cli/prototypes/basic_demo/customizations/config/default.env

@@ -0,0 +1,13 @@
+SECRET_KEY = "whatnothow"
+SQLALCHEMY_TRACK_MODIFICATIONS = False
+SQLAlCHEMY_ECHO = False
+# AGGREGATE_DEFAULTS =  True
+# ALL_DEFAULTS = True
+# APILOGICPROJECT_KAFKA_PRODUCER = "{\"bootstrap.servers\": \"localhost:9092\"}"
+# SQLALCHEMY_DATABASE_URI=db.sqlite
+
+SECURITY_ENABLED = false
+
+# if using tunnel for mcp, function, or ai_plugin
+# eg, https://tunnel_url.ngrok-free.app
+API_LOGIC_SERVER_TUNNEL = "TUNNEL_URL"

api_logic_server_cli/prototypes/basic_demo/customizations/database/models.py

@@ -0,0 +1,131 @@
+# coding: utf-8
+from sqlalchemy import DECIMAL, DateTime  # API Logic Server GenAI assist
+from sqlalchemy import Boolean, Column, DECIMAL, Date, ForeignKey, Integer, String
+from sqlalchemy.orm import relationship
+from sqlalchemy.ext.declarative import declarative_base
+
+########################################################################################################################
+# Classes describing database for SqlAlchemy ORM, initially created by schema introspection.
+#
+# Alter this file per your database maintenance policy
+#    See https://apilogicserver.github.io/Docs/Project-Rebuild/#rebuilding
+#
+# Created:  May 14, 2025 10:47:47
+# Database: sqlite:////Users/val/dev/ApiLogicServer/ApiLogicServer-dev/servers/basic_demo/database/db.sqlite
+# Dialect:  sqlite
+#
+# mypy: ignore-errors
+########################################################################################################################
+ 
+from database.system.SAFRSBaseX import SAFRSBaseX, TestBase
+from flask_login import UserMixin
+import safrs, flask_sqlalchemy, os
+from safrs import jsonapi_attr
+from flask_sqlalchemy import SQLAlchemy
+from sqlalchemy.orm import relationship
+from sqlalchemy.orm import Mapped
+from sqlalchemy.sql.sqltypes import NullType
+from typing import List
+
+db = SQLAlchemy() 
+Base = declarative_base()  # type: flask_sqlalchemy.model.DefaultMeta
+metadata = Base.metadata
+
+#NullType = db.String  # datatype fixup
+#TIMESTAMP= db.TIMESTAMP
+
+from sqlalchemy.dialects.sqlite import *
+
+if os.getenv('APILOGICPROJECT_NO_FLASK') is None or os.getenv('APILOGICPROJECT_NO_FLASK') == 'None':
+    Base = SAFRSBaseX   # enables rules to be used outside of Flask, e.g., test data loading
+else:
+    Base = TestBase     # ensure proper types, so rules work for data loading
+    print('*** Models.py Using TestBase ***')
+
+
+
+class Customer(Base):  # type: ignore
+    __tablename__ = 'customer'
+    _s_collection_name = 'Customer'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+    balance : DECIMAL = Column(DECIMAL)
+    credit_limit : DECIMAL = Column(DECIMAL)
+    email = Column(String)
+    email_opt_out = Column(Boolean)
+
+    # parent relationships (access parent)
+
+    # child relationships (access children)
+    EmailList : Mapped[List["Email"]] = relationship(back_populates="customer")
+    OrderList : Mapped[List["Order"]] = relationship(back_populates="customer")
+
+
+
+class Product(Base):  # type: ignore
+    __tablename__ = 'product'
+    _s_collection_name = 'Product'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+    unit_price : DECIMAL = Column(DECIMAL)
+
+    # parent relationships (access parent)
+
+    # child relationships (access children)
+    ItemList : Mapped[List["Item"]] = relationship(back_populates="product")
+
+
+
+class Email(Base):  # type: ignore
+    __tablename__ = 'email'
+    _s_collection_name = 'Email'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    message = Column(String)
+    customer_id = Column(ForeignKey('customer.id'), nullable=False)
+    CreatedOn = Column(Date)
+
+    # parent relationships (access parent)
+    customer : Mapped["Customer"] = relationship(back_populates=("EmailList"))
+
+    # child relationships (access children)
+
+
+
+class Order(Base):  # type: ignore
+    __tablename__ = 'order'
+    _s_collection_name = 'Order'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    notes = Column(String)
+    customer_id = Column(ForeignKey('customer.id'), nullable=False)
+    CreatedOn = Column(Date)
+    date_shipped = Column(Date)
+    amount_total : DECIMAL = Column(DECIMAL)
+
+    # parent relationships (access parent)
+    customer : Mapped["Customer"] = relationship(back_populates=("OrderList"))
+
+    # child relationships (access children)
+    ItemList : Mapped[List["Item"]] = relationship(back_populates="order")
+
+
+
+class Item(Base):  # type: ignore
+    __tablename__ = 'item'
+    _s_collection_name = 'Item'  # type: ignore
+
+    id = Column(Integer, primary_key=True)
+    order_id = Column(ForeignKey('order.id'))
+    product_id = Column(ForeignKey('product.id'), nullable=False)
+    quantity = Column(Integer, nullable=False)
+    amount : DECIMAL = Column(DECIMAL)
+    unit_price : DECIMAL = Column(DECIMAL)
+
+    # parent relationships (access parent)
+    order : Mapped["Order"] = relationship(back_populates=("ItemList"))
+    product : Mapped["Product"] = relationship(back_populates=("ItemList"))
+
+    # child relationships (access children)

api_logic_server_cli/prototypes/basic_demo/customizations/integration/mcp/1_langchain_loader.py

@@ -0,0 +1,71 @@
+"""
+==========================================================================================
+ LangChain OpenAPI Loader – JSON:API Planner Tool (1_langchain_loader.py)
+==========================================================================================
+
+Alert:
+------
+This does not work - hours of import version madness.
+
+
+Purpose:
+--------
+This script loads an OpenAPI 3.0 specification (e.g., nw_swagger_3.yaml) using LangChain's
+OpenAPI tools to dynamically generate a structured LangChain Tool. It can be used as a 
+building block in an AI system that automatically interprets natural language goals and 
+calls API endpoints by mapping them to OpenAPI operations.
+
+How It's Used:
+--------------
+- Reads the OpenAPI schema and extracts available endpoints.
+- Instantiates a tool for a specific operation (e.g., getCustomer).
+- Allows GPT agents or scripts to call the tool using structured input.
+- Typically used in multi-agent or planner + executor systems (e.g., AutoGen, LangGraph).
+- It is *not* required to run integration/mcp/3_executor_test_agent.py 
+
+Limitations:
+------------
+- This script does not itself parse natural language input.
+- The operation_id must be known and match one in the OpenAPI spec.
+- Requires LangChain and OpenAPI tool support installed.
+
+Dependencies:
+-------------
+- langchain
+- openapi-spec-validator
+
+Recommended Next Step:
+----------------------
+Use this in conjunction with a GPT planner that:
+1. Converts natural language into structured intent.
+2. Selects the correct operation_id.
+3. Provides parameters as expected by the OpenAPI operation.
+
+"""
+
+from langchain.tools.openapi.utils.openapi_utils import OpenAPISpec
+from langchain.tools.openapi.tool import OpenAPITool
+
+# Load your OpenAPI spec
+spec = OpenAPISpec.from_file("resources/nw_swagger_3.yaml")
+spec = OpenAPISpec.from_file("resources/nw_swagger_2.yaml")
+
+# List available operation IDs (optional debugging)
+print("Available operation IDs:")
+for path, methods in spec.raw_spec["paths"].items():
+    for method, details in methods.items():
+        print(f"- {details.get('operationId')}")
+        
+# Create LangChain tool from a specific endpoint
+customer_tool = OpenAPITool.from_openapi_spec(
+    spec=spec,
+    operation_id="getCustomer",  # use actual operationId from your spec
+    verbose=True
+)
+
+# Run a test call
+result = customer_tool.run({
+    "filter[Country]": "USA",
+    "page[limit]": 3
+})
+print(result)

api_logic_server_cli/prototypes/basic_demo/customizations/integration/mcp/README_mcp.md

@@ -0,0 +1,13 @@
+Model Context Protocol is a way for:
+
+1. **Bus User ad hoc flows** using existing published mcp services (vs. hard-coding in IT as an endpoint; flows can be cached for repeated use)
+
+    * ***Natural Language access*** to corporate databases for improved user interfaces
+
+    * LLMs ***choreograph*** multiple MCP calls (to 1 or more MCP servers) in a chain of calls - an agentic workflow. MCPs support shared contexts and goals, enabling the LLM to use the result from 1 call to determine whether the goals has been reached, or which service is appropriate to call next
+
+3. Chat agents to ***discover*** and ***call*** external servers, be they databases, APIs, file systems, etc. MCPs support shared contexts and goals, enabling the LLM
+
+    * ***Corporate database participation*** in such flows, by making key functions available as MCP calls.
+
+This example is [explained here](https://apilogicserver.github.io/Docs/Integration-MCP/).

api_logic_server_cli/prototypes/basic_demo/customizations/integration/mcp/mcp_client_executor.py

@@ -0,0 +1,295 @@
+""" 
+This simulates the MCP Client Executor, 
+which takes a natural language query and converts it into a tool context block:
+
+1. Discovers MCP servers (from config)
+2. Queries OpenAI's GPT-4 model to obtain the tool context based on a provided schema and a natural language query
+3. Processes the tool context (calls the indicated MCP (als) endpoints)
+
+Notes:
+* See: integration/mcp/README_mcp.md
+* python api_logic_server_run.py
+
+ToDo - email example is incomplete:
+1. Add email event handler (ala nw_sample/logic/declare_logic.py#send_n8n_message())
+2. And, respect the customer email_opt_out
+3. Needs to use date range
+4. Data incomplete
+
+"""
+
+import json
+import os
+import openai
+import requests
+
+# Set your OpenAI API key
+openai.api_key = os.getenv("APILOGICSERVER_CHATGPT_APIKEY")
+
+server_url = os.getenv("APILOGICSERVER_URL", "http://localhost:5656/api")
+
+# debug settings
+test_type = 'orchestration'  # 'simple_get' or 'orchestration'
+create_tool_context_from_llm = True
+''' set to False to bypass LLM call and save 2-3 secs in testing '''
+use_test_schema = False
+''' True means bypass discovery, use hard-coded schedma file '''
+
+def discover_mcp_servers():
+    """ Discover the MCP servers by calling the /api/.well-known/mcp.json endpoint.
+    This function retrieves the list of available MCP servers and their capabilities.
+    """
+    global server_url, use_test_schema
+
+    # create schema_text (for prompt), by reading integration/mcp/mcp_schema.txt
+    if use_test_schema:
+        schema_file_path = os.path.join(os.path.dirname(__file__), "mcp_schema.txt")
+        try:
+            with open(schema_file_path, "r") as schema_file:
+                schema_text = schema_file.read()
+        except FileNotFoundError:
+                print(f"Schema file not found at {schema_file_path}.")
+                exit(1)
+        finally:
+            print(f"Schema file loaded from {schema_file_path}.")
+        return schema_text
+
+    # find the servers - read the mcp_server_discovery.json file
+    discovery_file_path = os.path.join(os.path.dirname(__file__), "mcp_server_discovery.json")
+    try:
+        with open(discovery_file_path, "r") as discovery_file:
+            discovery_data = json.load(discovery_file)
+            print(f"\nDiscovered MCP servers from config file: {discovery_file_path}:" + json.dumps(discovery_data, indent=4))
+    except FileNotFoundError:
+        print(f"Discovery file not found at {discovery_file_path}.")
+    except json.JSONDecodeError as e:
+        print(f"Error decoding JSON from {discovery_file_path}: {e}")
+    
+    for each_server in discovery_data["servers"]:
+        discovery_url = each_server["schema_url"]
+
+        # Call the discovery_url to get the MCP/API schema
+        try:
+            response = requests.get(discovery_url)
+            if response.status_code == 200:
+                api_schema = response.json()
+                print()
+                print(f"\n1. API Schema from discovery schema_url: {discovery_url}:\n" +json.dumps(api_schema, indent=4))
+            else:
+                print(f"Failed to retrieve API schema from {discovery_url}: {response.status_code}")
+        except requests.RequestException as e:
+            print(f"Error calling OpenAPI URL: {e}")
+    return json.dumps(api_schema)
+
+
+def get_user_nl_query():
+    """ Get the natural language query from the user. """
+
+    global test_type
+        # this doesn't work -- missing commands for mcp_server_executor....
+    default_request = "List the orders created more than 30 days ago, and post an email message to the order's customer offering a discount"
+
+    default_request = "List the orders created more than 30 days ago, and send a discount email to the customer for each one."
+    # date range?  curl -X GET "http://localhost:5656/api/Order?filter=[{\’name\'}: {\’CreatedOn\’}, {\’op\’}: {\’gt\’}, {\’val\’}: {\’2022-05-14\’}]”
+
+    default_request = "List the orders for customer 5, and send a discount email to the customer for each one."
+
+    if test_type != 'orchestration':
+        default_request = "List customers with credit over 1000"
+
+    query = sys.argv[1] if len(sys.argv) > 1 else default_request
+
+    query += """
+Respond with a JSON array of tool context blocks using:
+- tool: 'json-api'
+- JSON:API-compliant filtering (e.g., filter[CreatedOn][lt])
+- Use {{ order.customer_id }} as a placeholder in the second step.
+- Include method, url, query_params or body, headers, expected_output.
+"""
+    return query
+
+
+def query_llm_with_nl(nl_query):
+    """ 
+    Query the LLM with a natural language query and schema text to generate a tool context block.
+
+    It handles both orchestration and simple GET requests.
+    """
+
+    global test_type, create_tool_context_from_llm
+
+    messages = [
+        {
+            "role": "system",
+            "content": "You are an API planner that converts natural language queries into MCP Tool Context blocks using JSON:API. Return only the tool context as JSON."
+        },
+        {
+            "role": "user",
+            "content": f"Schema:\n{schema_text}\n\nNatural language query: '{nl_query}'"
+        }
+    ]
+
+    # setup default tool_context to bypass LLM call and save 2-3 secs in testing
+    if test_type == 'orchestration':     # orchestration: emails to pending orders
+        tool_context = \
+            [
+                {
+                    "tool": "json-api",
+                    "method": "GET",
+                    "url": "http://localhost:5656/api/Order",
+                    "query_params": {
+                        "filter[customer_id]": 5
+                    },
+                    "headers": {
+                        "Content-Type": "application/vnd.api+json"
+                    },
+                    "expected_output": "JSON array of orders for customer 5"
+                },
+                {
+                    "tool": "email",
+                    "method": "POST",
+                    "url": "http://localhost:5656/api/Email",
+                    "body": {
+                        "to": "{{ order.customer_id }}",
+                        "subject": "Discount Offer",
+                        "message": "Dear Customer, We are offering a discount on your recent orders. Please check your account for more details."
+                    },
+                    "headers": {
+                        "Content-Type": "application/json"
+                    },
+                    "expected_output": "Email sent confirmation"
+                }
+            ]
+    else:                                   # simple get request - list customers with credit over 4000 
+        tool_context = \
+            [
+                {
+                    "tool": "json-api",
+                    "method": "GET",
+                    "url": "http://localhost:5656/api/Customer",
+                    "query_params": {
+                        "filter[credit_limit][gt]": 1000
+                    },
+                    "headers": {
+                        "Content-Type": "application/vnd.api+json"
+                    },
+                    "expected_output": "JSON array of customers with credit limit over 1000"
+                }
+            ]
+
+    # Call the OpenAI API to generate the tool context        
+    if create_tool_context_from_llm:  # saves 2-3 seconds...
+      response = openai.chat.completions.create(
+          model="gpt-4",
+          messages=messages,
+          temperature=0.2
+      )
+
+      tool_context_str = response.choices[0].message.content
+      try:
+          tool_context = json.loads(tool_context_str)
+      except json.JSONDecodeError:
+          print("Failed to decode JSON from response:", tool_context_str)
+          return None
+
+    print("\n2. generated tool context from LLM:\n", json.dumps(tool_context, indent=4))
+    return tool_context
+
+
+def process_tool_context(tool_context):
+    """ Process the orchestration request by executing multiple tool context blocks.
+    This function simulates the MCP Client Executor by executing the tool context blocks
+    against a live JSON:API server. It handles both GET and POST requests, and it can
+    orchestrate multiple requests based on the provided tool context.
+
+    Note the orchestration is processed by the client executor (here), not the server executor.
+
+    Research: 
+
+    1. How is this a "USB", since the request was specific about JSON:API?
+    2. How is it clear to loop through the tool_context[0] and call tool_context[1]?
+    """
+    global server_url
+
+    def get_query_param_filter(query_params):
+        """ return json:api filter
+        
+        query_params might be:
+            "query_params": {
+                "filter[credit_limit][gt]": 1000 }
+        or:
+            "query_params": {
+                "filter[customer_id]": 5},
+
+        """
+        query_param_filter = ''
+        if isinstance(query_params, dict):
+            for each_key, each_value in query_params.items():
+                if isinstance(each_value, dict):
+                    for sub_key, sub_value in each_value.items():
+                        query_param_filter += f"&{each_key}[{sub_key}]={sub_value}"
+                else:
+                    query_param_filter += f"&{each_key}={each_value}"
+            # query_params = ''
+        elif isinstance(query_params, dict):
+            assert False, "Query Params dict tbd"
+        return query_param_filter
+
+
+    if isinstance(tool_context, dict):
+        query_params = tool_context["query_params"]
+        query_param_filter = get_query_param_filter(query_params) 
+        mcp_response = requests.get(
+            tool_context["url"],
+            headers=tool_context["headers"],
+            params=query_param_filter
+        )
+    elif isinstance(tool_context, list):
+        context_data = {}
+        added_rows = 0
+
+        for each_block in tool_context:
+            if each_block["tool"] in ["json-api", "email"]:
+                if each_block["method"] == "GET":
+                        query_param_filter = get_query_param_filter(each_block["query_params"])
+                        mcp_response = requests.get(
+                            url = each_block["url"],
+                            headers=each_block["headers"],
+                            params=query_param_filter
+                        )
+                        context_data = mcp_response.json()['data']  # result rows...
+                elif each_block["method"] in ["POST"]:
+                        add_rows = 0
+                        for each_order in context_data:
+                            url = each_block["url"]
+                            json_update_data =  { 'data': {"type": "Email", 'attributes': {} } }  
+                            json_update_data_attributes = json_update_data["data"]["attributes"]
+                            json_update_data_attributes["customer_id"] = context_data[0]['attributes']["customer_id"]
+                            json_update_data_attributes["message"] = each_block["body"]["message"] 
+                            # eg: POST http://localhost:5656/api/Email {'data': {'type': 'Email', 'attributes': {'customer_id': 5, 'message': {'to': '{{ order.customer_id }}', 'subject': 'Discount for your order', 'body': 'Dear customer, you have a discount for your recent order. Thank you for shopping with us.'}}}}
+                            mcp_response = requests.post(  
+                                url=url,
+                                headers=each_block["headers"],
+                                json=json_update_data
+                            )
+                            add_rows += 1
+            pass
+    else:
+        print("Invalid tool context format. Expected a dictionary or a list.")
+        return None
+    print("\n3. MCP Server (als) Response:\n", mcp_response.text)
+    return mcp_response 
+
+
+if __name__ == "__main__":
+    import sys
+
+    schema_text = discover_mcp_servers()                # see: 1-discovery-from-als
+
+    query = get_user_nl_query()
+
+    tool_context = query_llm_with_nl(query)             # see: 2-tool-context-from-LLM   
+
+    mcp_response = process_tool_context(tool_context)   # see: 3-MCP-server response
+
+    print("\nTest complete.\n")

api_logic_server_cli/prototypes/basic_demo/customizations/integration/mcp/mcp_schema.txt

@@ -0,0 +1,47 @@
+Customer:
+  - id (INTEGER)
+  - name (VARCHAR)
+  - balance (DECIMAL)
+  - credit_limit (DECIMAL)
+  * Filterable: name, balance, credit_limit
+  * Example: 'List customers with credit over 5000'
+
+Item:
+  - id (INTEGER)
+  - order_id (INTEGER)
+  - product_id (INTEGER)
+  - quantity (INTEGER)
+  - amount (DECIMAL)
+  - unit_price (DECIMAL)
+  * Filterable: order_id, product_id, unit_price
+  * Relationships:
+    ↪ relates to Order
+    ↪ relates to Product
+  * Example: 'Find all items for order 42'
+
+Email:
+  - id (INTEGER)
+  - message (VARCHAR)
+  - customer_id (INTEGER)
+  * Relationships:
+    ↪ relates to Customer
+  * Example: 'Post an message "text" for customer 2 means POST to this resource'
+
+Order:
+  - id (INTEGER)
+  - notes (VARCHAR)
+  - customer_id (INTEGER)
+  - CreatedOn (DATE)
+  - date_shipped (DATE)
+  - amount_total (DECIMAL)
+  * Filterable: notes, customer_id, date_shipped, amount_total
+  * Relationships:
+    ↪ relates to Customer
+  * Example: 'Get orders shipped in 2024'
+
+Product:
+  - id (INTEGER)
+  - name (VARCHAR)
+  - unit_price (DECIMAL)
+  * Filterable: name, unit_price
+  * Example: 'Show products with price over 100'

api_logic_server_cli/prototypes/basic_demo/customizations/integration/mcp/mcp_server_discovery.json

@@ -0,0 +1,9 @@
+{
+  "servers": [
+    {
+      "name": "API Logic Server: basic_demo",
+      "base_url": "http://localhost:5656",
+      "schema_url": "http://localhost:5656/.well-known/mcp.json"
+    }
+  ]
+}