Merge pull request #36 from TransposeData/dev

 ✨ feat: AI Assistant & Schema endpoints & tests for Transpose::SQL

Author: Jon-Becker

docs/sql.md

@@ -4,6 +4,8 @@ The **SQL API** provides direct SQL access to our entire ecosystem of indexed bl
 
 ## Usage
 
+### Calling a SQL Query
+
 You may use the SQL API within your python project as follows:
 
 ```python
@@ -19,16 +21,99 @@ parameters = {
     'limit': 10,
 }
 
-response = api.endpoint.query("SELECT * FROM ethereum.logs LIMIT {{limit}}", parameters)
+response = api.sql.query("SELECT * FROM ethereum.logs LIMIT {{limit}}", parameters)
 ```
 
-## Parameters
+#### Parameters
 
 | Parameter | Type | Description |
 | - | - | - |
 | `sql_query` | `string` | The SQL query to call. |
 | `parameters` | `dict` | The optional parameters for this call. |
 
+### Getting the SQL Schema
+
+You may fetch our internal SQL schema as a dictionary with the following method:
+
+```python
+api.sql.schema() -> dict
+```
+
+For example:
+
+```python
+api = Transpose(api_key)
+
+response = api.sql.schema()
+
+print(response)
+
+# {
+#     "schema": {
+#         "ethereum": {
+#             "settlement_layer": [
+#                 {
+#                     "accounts": {
+#                         "meta": {
+#                             "table": "accounts",
+#                             "description": "The `ethereum.accounts` table provides indexed views of all accounts, including both externally-owned accounts (colloquially referred to as wallets) and contracts.",
+#                             "indexes": [
+#                                 [
+#                                     "created_timestamp",
+#                                     "address"
+#                                 ],
+#                                 ...
+#                             ]
+#                         },
+#                         "schema": [
+#                             {
+#                                 "column": "address",
+#                                 "type": "text",
+#                                 "description": "The address of the account."
+#                             },
+#                             ...
+#                         ]
+#                     }
+#                 },
+#                 ...
+#             ]
+#         },
+#         ...
+#     }
+# }
+```
+
+### Generating queries with the AI Query Assistant
+
+You may generate SQL queries with the AI Query Assistant as follows:
+
+```python
+api.sql.generate_query(self, text: str, chain: str='ethereum') -> dict:
+```
+
+For example:
+
+```python
+api = Transpose(api_key)
+
+response = api.sql.generate_query('Give me the most recently updated ENS name that is 3 characters long. Since all ens names end in ".eth", you\'ll need to add 4 to the search length. Optimize this query as much as possible.')
+
+print(response)
+
+# {
+#    "options": [
+#        "SELECT\n    ens_name, last_refreshed\nFROM\n    ethereum.ens_names\nWHERE\n    LENGTH(ens_name) = 7 AND ens_name LIKE '%.eth'\nORDER BY\n    last_refreshed DESC\nLIMIT 1;"
+#    ]
+# }
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+| - | - | - |
+| `text` | `string` | The text to generate a query from. Explain to the AI what you want to do, and it will generate a query for you. |
+| `chain` | `string` | The optional chain to generate a query for. Defaults to `ethereum`. Valid chains are `ethereum`, `goerli`, `arbitrum`, `canto`, `scroll`, or `polygon`. |
+
 ## More Information
 
-You can find more information about the Custom Endpoint API in our [documentation](https://docs.transpose.io/sql/overview/).
+You can find more information about the SQL API in our [documentation](https://docs.transpose.io/sql/overview/).

tests/test_ai_assistant_generate.py

@@ -0,0 +1,20 @@
+import json
+from transpose import Transpose, api_key
+from transpose.src.base import TransposeBadRequest
+
+def test_basic():
+    try:
+        api = Transpose(api_key)
+
+        response = api.sql.generate_query("Give me the most recently updated ENS name that is 3 characters long. Since all ens names end in \".eth\", you'll need to add 4 to the search length. Optimize this query as much as possible.", "ethereum")
+        
+        # ensure resp is dict
+        assert type(response) is dict
+        assert 'options' in response
+        assert type(response['options']) is list
+        
+        for option in response['options']:
+            assert 'SELECT' in option
+                
+    except Exception:
+        assert False

tests/test_get_schema.py

@@ -0,0 +1,27 @@
+import json
+from transpose import Transpose, api_key
+from transpose.src.base import TransposeBadRequest
+
+def test_basic():
+    try:
+        api = Transpose(api_key)
+
+        response = api.sql.schema()
+        
+        # ensure resp is dict
+        assert type(response) is dict
+        
+        # ensure resp exists
+        assert 'schema' in response
+        assert len(response['schema']) > 0
+        
+        # ensure all chains are present
+        assert 'ethereum' in response['schema']
+        assert 'polygon' in response['schema']
+        assert 'goerli' in response['schema']
+        assert 'arbitrum' in response['schema']
+        assert 'canto' in response['schema']
+        assert 'scroll' in response['schema']
+        
+    except Exception:
+        assert False

transpose/src/api/sql/base.py

@@ -20,7 +20,7 @@ def query(self,
             'Accept': 'application/json',
         }
 
-        # buold body
+        # build body
         body = {
             'sql': sql_query,
             'parameters': parameters
@@ -34,6 +34,64 @@ def query(self,
             json=body
         )
 
+        # check for a successful response
+        if request.status_code == 200:
+            
+            response = request.json()
+            return response
+        else:
+            raise_custom_error(request.status_code, request.json()['message'])
+            
+            
+    # Gets the schema from the Transpose API
+    def schema(self) -> dict:
+        
+        # build headers
+        request_headers = {
+            'x-api-key': self.super.api_key,
+            'Accept': 'application/json',
+        }
+
+        # if in verbose mode, log the endpoint
+        request = requests.get(
+            "https://api.transpose.io/get-schema",
+            headers=request_headers,
+        )
+        
+        # check for a successful response
+        if request.status_code == 200:
+            
+            response = request.json()
+            return response
+        else:
+            raise_custom_error(request.status_code, request.json()['message'])
+            
+            
+    # Calls the AI query assistant
+    def generate_query(self, text: str, chain: str='ethereum') -> dict:
+        
+        # build headers
+        request_headers = {
+            'x-api-key': self.super.api_key,
+            'Accept': 'application/json',
+        }
+        
+        # build body
+        body = {
+            'text': text,
+            'chain': chain
+        }
+
+        # if in verbose mode, log the endpoint
+        print("\n{}\n  {}\n".format("https://api.transpose.io/text-to-sql", json.dumps(body, indent=4))) if self.super.verbose else None
+        
+        # make request
+        request = requests.post(
+            "https://api.transpose.io/text-to-sql",
+            headers=request_headers,
+            json=body,
+        )
+        
         # check for a successful response
         if request.status_code == 200: