Update documentation and readme file

docs/api.add_descriptions.rst

@@ -7,7 +7,7 @@ To return an accurate response set descriptions per table and column.
 
 Request this ``PATCH`` endpoint::
 
-   /api/v1/scanned-db/{db_name}/{table_name}
+   /api/v1/table-descriptions/{table_description_id}
 
 
 **Parameters**
@@ -16,8 +16,7 @@ Request this ``PATCH`` endpoint::
    :header: "Name", "Type", "Description"
    :widths: 20, 20, 60
 
-   "db_name", "String", "Database name, ``Required``"
-   "table_name", "String", "Table name, ``Required``"
+   "table_description_id", "String", "Table description id, ``Required``"
 
 **Request body**
 
@@ -39,7 +38,30 @@ HTTP 200 code response
 
 .. code-block:: rst
 
-    true
+    {
+      "id": "string",
+      "db_connection_id": "string",
+      "table_name": "string",
+      "description": "string",
+      "table_schema": "string",
+      "columns": [
+        {
+          "name": "string",
+          "is_primary_key": false,
+          "data_type": "str",
+          "description": "string",
+          "low_cardinality": false,
+          "categories": [
+            "string"
+          ],
+          "foreign_key": {
+            "field_name": "string",
+            "reference_table": "string"
+          }
+        }
+      ],
+      "examples": []
+    }
 
 **Example 1**
 
@@ -48,7 +70,7 @@ Only set a table description
 .. code-block:: rst
 
    curl -X 'PATCH' \
-  '<host>/api/v1/scanned-db/foo_db/foo_table' \
+  '<host>/api/v1/table-descriptions/64fa09446cec0b4ff60d3ae3' \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -62,7 +84,7 @@ Only set columns descriptions
 .. code-block:: rst
 
    curl -X 'PATCH' \
-  '<host>/api/v1/scanned-db/foo_db/foo_table' \
+  '<host>/api/v1/table-descriptions/64fa09446cec0b4ff60d3ae3' \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -d '{

docs/api.database.rst → docs/api.create_database_connection.rst

@@ -11,7 +11,7 @@ You can find additional details on how to connect to each of the supported data
 
 **Request this POST endpoint**::
 
-   /api/v1/database
+   /api/v1/database-connections
 
 **Request body**
 
@@ -69,7 +69,7 @@ Without a SSH connection
 .. code-block:: rst
 
    curl -X 'POST' \
-      '<host>/api/v1/database' \
+      '<host>/api/v1/database-connections' \
       -H 'accept: application/json' \
       -H 'Content-Type: application/json' \
       -d '{
@@ -85,7 +85,7 @@ With a SSH connection
 .. code-block:: rst
 
     curl -X 'POST' \
-      'http://localhost/api/v1/database' \
+      '<host>/api/v1/database-connections' \
       -H 'accept: application/json' \
       -H 'Content-Type: application/json' \
       -d '{

docs/api.list_database_connections.rst

@@ -0,0 +1,55 @@
+List Database connections
+=============================
+
+This endpoint list all the existing db connections
+
+**Request this GET endpoint**::
+
+   /api/v1/database-connections
+
+
+**Responses**
+
+HTTP 200 code response
+
+.. code-block:: rst
+
+    [
+      {
+        "id": "64dfa0e103f5134086f7090c",
+        "alias": "databricks",
+        "use_ssh": false,
+        "uri": "foooAABk91Q4wjoR2h07GR7_72BdQnxi8Rm6i_EjyS-mzz_o2c3RAWaEqnlUvkK5eGD5kUfE5xheyivl1Wfbk_EM7CgV4SvdLmOOt7FJV-3kG4zAbar=",
+        "path_to_credentials_file": null,
+        "ssh_settings": null
+      },
+      {
+        "id": "64e52c5f7d6dc4bc510d6d28",
+        "alias": "postgres",
+        "use_ssh": true,
+        "uri": null,
+        "path_to_credentials_file": null,
+        "ssh_settings": {
+          "db_name": "string",
+          "host": "string",
+          "username": "string",
+          "password": "foo-LWx6c1h6V0KkPRm9O148Pm9scvoO-wnasdasd1dQjf0ZQuFYI07uCjPiMcZ6uC19mUkiiYiHcKyok1NaLaGDAabkwg==",
+          "remote_host": "string",
+          "remote_db_name": "string",
+          "remote_db_password": "bar-LWxpBkRDuasdOwU__Sk4bdzruiYYqiyl8gBEEzCyFYCaCOcbQqOa_OwsS-asdasdsad==",
+          "private_key_path": "string",
+          "private_key_password": "fooo-LWxPdFcjQw9lU7CeK_2ELR3jGBq0G_uQ7E2rfPLk2RcFR4aDO9e2HmeAQtVpdvtrsQ_0zjsy9q7asdsadXExYJ0g==",
+          "db_driver": "string"
+        }
+      }
+    ]
+
+**Example 1**
+
+.. code-block:: rst
+
+   curl -X 'GET' \
+      '<host>/api/v1/database-connections' \
+      -H 'accept: application/json' \
+      -H 'Content-Type: application/json'
+    '

docs/api.list_table_description.rst

@@ -0,0 +1,60 @@
+.. api.scan_database:
+
+List table descriptions
+=======================
+
+Once you have scanned a db connection you can list the table descriptions by requesting this endpoint.
+
+Request this ``GET`` endpoint::
+
+   /api/v1/table-descriptions
+
+**Parameters**
+
+.. csv-table::
+   :header: "Name", "Type", "Description"
+   :widths: 20, 20, 60
+
+   "db_connection_id", "string", "Filter by connection id, ``Optional``"
+   "table_name", "string", "Filter by table name, ``Optional``"
+
+**Responses**
+
+HTTP 200 code response
+
+.. code-block:: rst
+
+    [
+      {
+        "id": "string",
+        "db_connection_id": "string",
+        "table_name": "string",
+        "description": "string",
+        "table_schema": "string",
+        "columns": [
+          {
+            "name": "string",
+            "is_primary_key": false,
+            "data_type": "str",
+            "description": "string",
+            "low_cardinality": false,
+            "categories": [
+              "string"
+            ],
+            "foreign_key": {
+              "field_name": "string",
+              "reference_table": "string"
+            }
+          }
+        ],
+        "examples": []
+      }
+    ]
+
+**Request example**
+
+.. code-block:: rst
+
+    curl -X 'GET' \
+      '<localhost>/api/v1/table-descriptions?db_connection_id=64fa09446cec0b4ff60d3ae3&table_name=foo' \
+      -H 'accept: application/json'

docs/api.process_nl_query_response.rst

@@ -0,0 +1,107 @@
+Process a NL query response
+=======================
+
+Once you made a question you can try sending a new sql query to improve the response, this is not stored
+
+Request this ``POST`` endpoint::
+
+   /api/v1/nl-query-responses
+
+**Request body**
+
+.. code-block:: rst
+
+    {
+      "query_id": "string", # required
+      "sql_query": "string" # required
+    }
+
+**Responses**
+
+HTTP 200 code response
+
+.. code-block:: rst
+
+    {
+      "id": "string",
+      "nl_question_id": "string",
+      "nl_response": "string",
+      "intermediate_steps": [
+        "string"
+      ],
+      "sql_query": "string",
+      "sql_query_result": {
+        "columns": [
+          "string"
+        ],
+        "rows": [
+          {}
+        ]
+      },
+      "sql_generation_status": "NONE",
+      "error_message": "string",
+      "exec_time": 0,
+      "total_tokens": 0,
+      "total_cost": 0,
+      "confidence_score": 0
+    }
+
+**Request example**
+
+
+.. code-block:: rst
+
+   curl -X 'POST' \
+  '<localhost>/api/v1/nl-query-responses' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+      "sql_query": "SELECT "dh_zip_code", MAX("metric_value") as max_rent
+        FROM db_table
+        WHERE "dh_county_name" = 'Los Angeles' AND "period_start" = '2022-05-01' AND "period_end" = '2022-05-31'
+        GROUP BY "zip_code"
+        ORDER BY max_rent DESC
+        LIMIT 1;",
+      "query_id": "64c424fa3f4036441e882352"
+    }'
+
+**Response example**
+
+.. code-block:: rst
+
+   {
+      "id": {
+        "$oid": "64c424fa3f4036441e882352"
+      },
+      "nl_question_id": {
+        "$oid": "64dbd8cf944f867b3c450467"
+      },
+      "nl_response": "The most expensive zip to rent in Los Angeles city is 90210",
+      "intermediate_steps": [
+        "",
+      ],
+      "sql_query": "SELECT "zip_code", MAX("metric_value") as max_rent
+        FROM db_table
+        WHERE "dh_county_name" = 'Los Angeles' AND "period_start" = '2022-05-01' AND "period_end" = '2022-05-31'
+        GROUP BY "zip_code"
+        ORDER BY max_rent DESC
+        LIMIT 1;",
+      "sql_query_result": {
+        "columns": [
+          "zip_code",
+          "max_rent"
+        ],
+        "rows": [
+          {
+            "zip_code": "90210",
+            "max_rent": 58279.6479072398192
+          }
+        ]
+      },
+      "sql_generation_status": "VALID",
+      "error_message": null,
+      "exec_time": 37.183526277542114,
+      "total_tokens": 17816,
+      "total_cost": 1.1087399999999998
+      "confidence_score": 0.95
+    }