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

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

@@ -0,0 +1,350 @@
+""" 
+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 re
+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
+
+    default_request = "List the orders created more than 30 days ago, and send a discount email to the customer for each one."
+    # eg, curl -qg 'http://localhost:5656/api/Order?filter=[{"name":"date_shipped","op":"gt","val":"2023-07-14"}]'
+    # eg, curl -qg 'http://localhost:5656/api/Order?filter=[{"name":"date_shipped","op":"eq","val":null}]'
+    # eg, curl -qg 'http://localhost:5656/api/Order?filter=[{"name":"date_shipped","op":"eq","val":null},{"name":"CreatedOn","op":"lt","val":"2023-07-14"}]'
+    # eg, curl -qg 'http://localhost:5656/api/Customer?filter=[{"name":"credit_limit","op":"gt","val":"1000"}]'
+
+    # curl -qg 'http://localhost:5656/api/Order?filter=[{"name":%20"date_shipped",%20"op":%20"eq",%20"val":%20null},%20{"name":%20"CreatedOn",%20"op":%20"lt",%20"val":%20"2023-07-14"}]'
+
+    default_request = "List the orders for customer 5, and send a discount email to the customer for each one."
+    default_request = "List the unshipped orders created before 2023-07-14, 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 custom filtering (e.g., filter=[{"name":"date_shipped","op":"gt","val":"2023-07-14"}])
+- 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": [
+                            {
+                                "name": "date_shipped",
+                                "op": "eq",
+                                "val": None
+                            },
+                            {
+                                "name": "date_created",
+                                "op": "lt",
+                                "val": "2023-07-14"
+                            }
+                        ]
+                    },
+                    "headers": {
+                        "Content-Type": "application/json"
+                    },
+                    "expected_output": "JSON array of unshipped orders created before 2023-07-14"
+                },
+                {
+                    "tool": "email",
+                    "method": "POST",
+                    "url": "http://localhost:5656/api/sendEmail",
+                    "body": {
+                        "customer_id": "{{ order.customer_id }}",
+                        "subject": "Discount Offer",
+                        "message": "You have a new discount offer for your unshipped order."
+                    },
+                    "headers": {
+                        "Content-Type": "application/json"
+                    },
+                    "expected_output": "Confirmation of email sent"
+                }
+            ]
+    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
+
+        see api_logic_server_cli/prototypes/base/api/system/expression_parser.py (doc?)
+
+        eg
+            curl -qg 'http://localhost:5656/api/Order?filter=[{"name":"date_shipped","op":"eq","val":null},{"name":"CreatedOn","op":"gt","val":"2023-07-14"}]'
+        
+        query_params might be simple:
+            "query_params": {
+                "filter[credit_limit][gt]": 1000 }
+            ==> ?filter=[{"name":"credit_limit","op":"gt","val":"1000"}]
+        or a list:
+            "query_params": {
+                        "filter": [
+                            {
+                                "name": "date_shipped",
+                                "op": "eq",
+                                "val": null
+                            },
+                            {
+                                "name": "date_created",
+                                "op": "lt",
+                                "val": "2023-07-14"
+                            }
+                        ]
+                    },
+        """
+
+        added_rows = 0
+
+        query_param_filter = ''
+        if isinstance(query_params, dict):
+            if "filter" not in query_params:    # simple - "query_params": {"filter[credit_limit][gt]": 1000 }
+                for each_key, each_value in query_params.items():
+                    assert not isinstance(each_value, dict), "Unexpected dict in simple query_params"
+                    # convert {"filter[credit_limit][gt]": 1000 } to ?filter=[{"name":"credit_limit","op":"gt","val":"1000"}]
+                    match = re.match(r"filter\[(\w+)\]\[(\w+)\]", each_key)
+                    if match:
+                        name, op = match.groups()
+                        filter_json = json.dumps([{"name": name, "op": op, "val": str(each_value)}])
+                        query_param_filter += f"&filter={filter_json}"
+                    else:
+                        query_param_filter += f"&{each_key}={each_value}"
+                    
+            else:                               # complex - "query_params": {"filter": ...
+                assert isinstance(query_params["filter"], list), "Query Params filter expected to be a list"
+                query_param_filter = 'filter=' + str(query_params["filter"])
+                # use urlencode to convert to JSON:API format...
+                # val urllib.parse.quote() or urllib.parse.urlencode()
+                # tool instructions... filtering, email etc
+                query_param_filter = query_param_filter.replace("'", '"')  # convert single quotes to double quotes
+                query_param_filter = query_param_filter.replace("None", 'null')
+                query_param_filter = query_param_filter.replace("date_created", 'CreatedOn')  # TODO - why this name?
+            # query_params = ''
+        else:
+            assert False, "Query Params not a dict"
+        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"]:
+                        for each_order in context_data:
+                            url = each_block["url"]
+                            url = url.replace("sendEmail", "Email")  # TODO name fix
+                            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"]  # TODO - fix
+                            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
+                            )
+                            added_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)
+    if added_rows > 0:
+        print(f"...Added {added_rows} rows to the database; last row (only) shown above.")
+    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"
+    }
+  ]
+}

api_logic_server_cli/prototypes/{nw_no_cust/integration/mcp → basic_demo/customizations/integration/openai_function}/3_executor_test_agent.py

@@ -1,7 +1,7 @@
-import requests
+import requests, json
 
 # MCP-style tool_context
-'''
+# does not like this pagination
 tool_context = {
     "method": "GET",
     "url": "http://localhost:5656/api/Customer",
@@ -13,8 +13,8 @@ tool_context = {
         "Accept": "application/vnd.api+json"
     }
 }
-'''
-tool_context = {
+
+tool_context = {  # use this for nw
     "method": "GET",
     "url": "http://localhost:5656/api/Customer",
     "query_params": {
@@ -22,12 +22,24 @@ tool_context = {
     },
     "headers": {
         "Accept": "application/vnd.api+json"
+        , "Authorization": "Bearer your_token"
     }
 }
 
+tool_context = {  # use this for genai_demo
+    "method": "GET",
+    "url": "http://localhost:5656/api/Customer",
+    "query_params": {
+        "filter[name]": "Alice"
+    },
+    "headers": {
+        "Accept": "application/vnd.api+json"
+        , "Authorization": "Bearer your_token"
+    }
+}
 
 # Execute as a simulated MCP executor
-response = requests.get(
+response = requests.get(  # use this for genai_demo
     tool_context["url"],
     headers=tool_context["headers"],
     params=tool_context["query_params"]
@@ -35,4 +47,6 @@ response = requests.get(
 
 # Display result
 print(response.status_code)
-print(response.json())
+# Print the response, format it as JSON with indent
+print(json.dumps(response.json(), indent=4))
+

api_logic_server_cli/prototypes/basic_demo/customizations/integration/openai_function/README_functon.md

@@ -0,0 +1,201 @@
+**OpenAI functions** are tools that extend the capabilities of ChatGPT by allowing it to access real-time data, perform actions, or connect with external services via APIs. .
+
+Instead of being limited to its pre-trained knowledge, ChatGPT can use plugins to retrieve up-to-date information (like live weather, stock prices, or databases) or perform tasks (like booking a flight or running a query). 
+
+The goal is to turn ChatGPT into a more useful, interactive assistant that can bridge AI language understanding with real-world actions and live data.   
+
+>For example, in large companies, it can be remarkably hard to find corporate systems via an Intranet, and use different user interfaces.  ChatGPT can simplify finding these, and interacting with Natural Language.
+
+This is to explore:
+
+| Explore                                    | Status               |
+| ------------------------------------------ | -------------------- |
+| Nat Lang ALS Access using OpenAI Functions | Initial Test Running |
+|                                            |                      |
+
+A value prop might be summarized: *instantly expose legacy DBs to Natural Language, including critical business logic and security, to simplify user discovery and operation.*
+
+<br>
+
+## Status: Technology Exploration
+
+This is an initial experiment, without automation.  Many substantive issues need to be addressed, including but not limited to security, update, etc.
+
+We welcome participation in this exploration.  Please contact us via [discord](https://discord.gg/HcGxbBsgRF).
+
+This exploration is changing rapidly.  For updates, replace `integration/mcp` from [integration/msp](https://github.com/ApiLogicServer/ApiLogicServer-src/tree/main/api_logic_server_cli/prototypes/nw_no_cust/integration/openai_plugin)
+
+<br>
+
+## Nat Lang ALS Access using OpenAI Plugin
+
+Requires tunnel to local host such as [ngrok](https://ngrok.com/downloads/mac-os?tab=download), then
+
+```
+ngrok config add-authtoken <obtain from https://dashboard.ngrok.com/get-started/setup/macos>
+```
+
+then start the tunnel
+
+```
+ngrok http 5656
+```
+
+You should see:
+
+![ngrok](https://github.com/ApiLogicServer/Docs/blob/main/docs/images/integration/mcp/ngrok.png?raw=true)
+
+and note the url like: `https://42da-2601-644-4900-etc.ngrok-free.app -> http://localhost:5656`
+
+We'll call it `tunnel_url`
+
+Enter this into `config/default.env`
+
+<br>
+
+### Use GenAI_Demo
+
+See `mcp/README_mcp.md`
+
+<br>
+
+### Obtain swagger_3
+
+This has already been done using the procedure described below.
+
+Obtain swagger 2 from API Logic Server, eg, http://localhost:5656/api/swagger.json) 
+
+Convert to 3: https://converter.swagger.io or other.
+
+<br>
+
+#### Reduce to 30 Operations
+
+Reduce down to 30 operations (genai_demo has 69).
+
+For testing, you can copy `integration/openai_plugin/swagger_3_genai_demo.json` or `integration/openai_plugin/nw-swagger_3.json` over `integration/openai_plugin/swagger_3.json`.
+
+This was obtained using ChatGPT with prompts like:
+
+1. Optionally collapse GET by ID and GET collection into a single endpoint using query params
+2. remove POST from relationship endpoints
+3. remove delete
+4. collapse relationship endpoints further
+
+then fix the result:
+
+1. ensure servers and paths is retained (got deleted for me), and includes https:
+2. version 3.1.0
+
+Still seeing (fix with Chat):
+
+```
+In path /Customer, method get is missing operationId; skipping
+In path /Customer, method post is missing operationId; skipping
+In path /Order, method get is missing operationId; skipping
+In path /Order, method post is missing operationId; skipping
+In path /Item, method get is missing operationId; skipping
+In path /Item, method post is missing operationId; skipping
+In path /Product, method get is missing operationId; skipping
+In path /Product, method post is missing operationId; skipping
+```
+
+<br>
+
+### Custom endpoint for openapi
+
+OpenAI requires a openai document, so observe the custom endpoint - `api/api_discovery/openapi` - eg, to test locally: `http://localhost:5656/api/openai.json`
+
+Note: the url for use in ChatGPT is the tunnelled version, from the env variable.
+
+<br>
+
+### Configure in ChatGPT
+
+Then, upload it to the **Web** version of ChatGPT: 
+
+1. Explore GPTs
+2. Create
+3. Configure
+4. Create New Action
+
+Provide the url of the openai endpoint:
+
+https://tunnel_url.ngrok-free.app/api/openapi.json
+
+<br>
+
+### Retrieval worked:
+
+- list customers
+- list the items of order 1 with their product names
+
+<br>
+
+### Update: Resoved, pending verification
+
+We also experimented with update, using `integration/openai_plugin/swagger_3.json`.
+
+> It initially failed to load, which we repaired as noted in Appendix 2.
+
+> It then failed to generate proper update API, evidently due to bad OpenAPI spec as noted in Appendix 3.
+
+<br>
+
+## Appendices
+
+<br>
+
+### Appendix 1: Create ai_plug_in.json
+
+We also looked at openai plugins.  These appear to be discontinued.
+
+Prepare `ai_plug_in.json` as shown in this directory.  Observe that it It identifies the url for finding the openapi through the tunnel.
+
+Note: both ALS and and `ai_plug_in.json` presume the swagger and api are consistent:
+
+- swagger is at `http://localhost:5656/api/swagger.json`, 
+- typical API at `http://localhost:5656/api/Category`
+
+Not required for function - **Settings / Beta / Plugins > Plugin install → expects the ai-plugin.json manifest URL**
+
+This appears to be unavailable for ChatGPT 4o
+
+<br>
+
+### Appendix 2: Updateable openapi
+
+It initially failed to load with
+
+```
+In context=('paths', '/Customer/{CustomerId}/', 'patch', 'requestBody', 'content', 'application/json', 'schema'), reference to unknown component Customer_inst; using empty schema
+
+In path /Customer/{CustomerId}/, method patch, operationId UpdateCustomer_0, request body schema is not an object schema; skipping
+
+In path /Customer/{CustomerId}/, method patch, operationId UpdateCustomer_0, skipping function due to errors
+```
+
+We requested a revised jasonapi from ChatGPT to clear these errors, which loaded.  
+
+<br>
+
+### Appendix 3: Invalid Data Object
+
+ This appears to be caused by improper JSON:API openAPI spec, which caused ChatGPT to generate an improper json PATCH payload:
+
+```python
+            chatgpt_request_json = {
+                        "credit_limit": 25000,
+            }
+            standard_request_json = {
+                "data": {
+                    "type": "Customer",
+                    "id": "ALFKI",
+                    "attributes": {
+                        "name": "Alice",
+                        "credit_limit": 25000,
+                        "balance": 12345
+                    }
+                }
+            }
+```

api_logic_server_cli/prototypes/basic_demo/customizations/integration/openai_function/ai_plugin.json

@@ -0,0 +1,17 @@
+{
+    "schema_version": "v1",
+    "name_for_human": "ALS NW-",
+    "name_for_model": "ALS NW",
+    "description_for_human": "Access and manage categories, customers, and more.",
+    "description_for_model": "Plugin for interacting with the API Logic Server.",
+    "auth": {
+      "type": "none"
+    },
+    "api": {
+      "type": "openapi",
+      "url": "https://tunnel_url.ngrok-free.app/api/openapi"
+    },
+    "logo_url": "https://your-logo-url/logo.png",
+    "contact_email": "support@yourdomain.com",
+    "legal_info_url": "https://yourdomain.com/legal"
+  }