From a6514d0c7850408ef42f178064fc58d91f159050 Mon Sep 17 00:00:00 2001 From: Cody Date: Tue, 5 Mar 2024 12:19:24 -0500 Subject: [PATCH] docs updates --- .../_freeze/install/execute-results/html.json | 12 +++++++ .../python/execute-results/html.json | 4 +-- docs/install.qmd | 33 +++++++++---------- docs/tutorials/cli.qmd | 15 +++++++++ docs/tutorials/python.qmd | 4 +-- 5 files changed, 46 insertions(+), 22 deletions(-) create mode 100644 docs/_freeze/install/execute-results/html.json diff --git a/docs/_freeze/install/execute-results/html.json b/docs/_freeze/install/execute-results/html.json new file mode 100644 index 0000000..3363729 --- /dev/null +++ b/docs/_freeze/install/execute-results/html.json @@ -0,0 +1,12 @@ +{ + "hash": "5d2f1ac330c63e71709868d483412e5f", + "result": { + "engine": "jupyter", + "markdown": "---\ntitle: Installation and setup\n---\n\n\n\nThis page describes how to install and setup Ibis Birdbrain.\n\n## Install from PyPI\n\n```bash\npip install ibis-birdbrain\n```\n\n## Data platform setup\n\nCreate an Ibis connection:\n\n:::{.callout-warning}\nOnly DuckDB is installed by default. For now, you need to install other backends\nmanually with Ibis.\n:::\n\n\n::: {#9af055c5 .cell execution_count=1}\n``` {.python .cell-code}\nimport ibis\n\nbackend = \"duckdb\"\nbackend_uri = \"\"\n\ncon = ibis.connect(f\"{backend}://{backend_uri}\")\ncon\n```\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n\n```\n:::\n:::\n\n\n## AI platform setup\n\nSee [Marvin documentation for\nsetup](https://www.askmarvin.ai/docs/configuration/settings/).\n\n:::{.callout-warning}\nOnly OpenAI and Azure OpenAI are supported for now.\n:::\n\n## Next steps\n\n[Learn how get started with Ibis Birdbrain's CLI](tutorials/cli.qmd).\n\n", + "supporting": [ + "install_files" + ], + "filters": [], + "includes": {} + } +} \ No newline at end of file diff --git a/docs/_freeze/tutorials/python/execute-results/html.json b/docs/_freeze/tutorials/python/execute-results/html.json index 5a610a4..48f95b6 100644 --- a/docs/_freeze/tutorials/python/execute-results/html.json +++ b/docs/_freeze/tutorials/python/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "b6c909ffef0460a28fe202709082308e", + "hash": "5473aeb233c43d87b1bfa8acc656ed98", "result": { "engine": "jupyter", - "markdown": "---\ntitle: 'Tutorial: Python'\n---\n\n\n\n## Prerequisites\n\n1. [Install Ibis Birdbrain](/install.qmd)\n\n## Overview\n\nYou can use Ibis Birdbrain as a Python library, but it is often used through an\ninteractive Python session. You can [see how to start one with the `birdbrain`\nCLI with Ibis Birdbrain ready to use](/tutorials/cli.qmd).\n\n## Setup the bot\n\nFirst, import relevant modules:\n\n\n::: {#713fdb0b .cell execution_count=1}\n``` {.python .cell-code}\nimport ibis\n\nfrom ibis_birdbrain import Bot\n```\n:::\n\n\nSet Ibis interactive mode:\n\n::: {#dd1db426 .cell execution_count=2}\n``` {.python .cell-code}\nibis.options.interactive = True\n```\n:::\n\n\n### Create an Ibis connection\n\nCreate an Ibis connection to your database:\n\n::: {.callout-warning}\nWe'll create a demo database for this tutorial.\n:::\n\n::: {#23220e86 .cell execution_count=3}\n``` {.python .cell-code}\ncon = ibis.connect(\"duckdb://penguins.ddb\")\ncon.create_table(\n \"penguins\", ibis.examples.penguins.fetch().to_pyarrow(), overwrite=True\n)\ncon = ibis.connect(\"duckdb://penguins.ddb\")\ncon.list_tables()\n```\n\n::: {.cell-output .cell-output-stderr}\n```\nINFO:pins.cache:cache file: /Users/cody/Library/Caches/pins-py/gcs_332a30997e141da0e08f15fbfae8b3c3ec90463922d117a96fa3b1bef85a2a4c/penguins/20230905T090411Z-9aae2/data.txt\nINFO:pins.cache:cache file: /Users/cody/Library/Caches/pins-py/gcs_332a30997e141da0e08f15fbfae8b3c3ec90463922d117a96fa3b1bef85a2a4c/penguins/20230905T090411Z-9aae2/penguins.csv.gz\n```\n:::\n\n::: {.cell-output .cell-output-display execution_count=3}\n```\n['penguins']\n```\n:::\n:::\n\n\n### Create the bot\n\nYou'll create the bot by passing in the connection:\n\n::: {.callout-tip}\nFor increased accuracy, you should also pass in a `data_description` containing\ninformation about the dataset. This could be fetched from the database itself,\nmanually created, or otherwise obtained.\n\nYou should not include table names and schemas -- this will be inferred\nautomatically.\n:::\n\n::: {#d1a29af2 .cell execution_count=4}\n``` {.python .cell-code}\nbot = Bot(con=con, data_description=\"the Palmer Penguins dataset\")\nbot\n```\n\n::: {.cell-output .cell-output-stderr}\n```\nINFO:root:Bot birdbrain initialized...\n```\n:::\n\n::: {.cell-output .cell-output-display execution_count=4}\n```\n\n```\n:::\n:::\n\n\n### Test the bot\n\nYou can ask the bot questions:\n\n::: {#ac5bbc96 .cell execution_count=5}\n``` {.python .cell-code}\nres = bot(\"\"\"give me the counts of penguins by species and island from highest\nto lowest\"\"\")\nres\n```\n\n::: {.cell-output .cell-output-stderr}\n```\nINFO:root:Bot birdbrain called with text: give me the counts of penguins by species and island from highest\nto lowest\nINFO:root:Selected flow: data\nINFO:root:Executing the data flow\nINFO:root:Text to SQL task\nINFO:httpx:HTTP Request: POST https://birdbrain-eh.openai.azure.com/openai/deployments/gpt-4-turbo/chat/completions?api-version=2023-12-01-preview \"HTTP/1.1 200 OK\"\nINFO:root:Executing the SQL task\n```\n:::\n\n::: {.cell-output .cell-output-display}\n```{=html}\n
\n```\n:::\n\n::: {.cell-output .cell-output-display}\n```{=html}\n
\n```\n:::\n\n::: {.cell-output .cell-output-display execution_count=5}\n\n::: {.ansi-escaped-output}\n```{=html}\n
To: user\nFrom: birdbrain\nSubject: give me the counts of pengu...\nSent at: 2024-03-05 11:31:58.342810\nMessage: 0da2fb4c-30f7-4c2d-a646-ed500e3f99a6\nIbis Birdbrain has attached the results.\nAttachments:\nCodeAttachment\n    **guid**: 14125164-2a86-479b-ba97-9847e894d7a7\n    **time**: 2024-03-05 11:31:58.340826\n    **name**: None\n    **desc**: None\n    **language**: sql\n    **code**:\nSELECT species, island, COUNT(*) AS count \nFROM penguins \nGROUP BY species, island \nORDER BY count DESC\nTableAttachment\n    **guid**: 537a8847-568d-45c8-b306-4f5363ad5ca1\n    **time**: 2024-03-05 11:31:58.342725\n    **name**: None\n    **desc**: \nibis.Schema {\n  species  string\n  island   string\n  count    int64\n}\n                **table**:\n┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓\n┃ species   ┃ island    ┃ count ┃\n┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩\n│ string    │ string    │ int64 │\n├───────────┼───────────┼───────┤\n│ Gentoo    │ Biscoe    │   124 │\n│ Chinstrap │ Dream     │    68 │\n│ Adelie    │ Dream     │    56 │\n│ Adelie    │ Torgersen │    52 │\n│ Adelie    │ Biscoe    │    44 │\n└───────────┴───────────┴───────┘
\n```\n:::\n\n:::\n:::\n\n\n### Get attachments\n\nYou can get the table from the attachment:\n\n::: {#d6a24b26 .cell execution_count=6}\n``` {.python .cell-code}\nt = res.attachments[-1].open()\nt\n```\n\n::: {.cell-output .cell-output-display execution_count=6}\n```{=html}\n
┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓\n┃ species   ┃ island    ┃ count ┃\n┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩\n│ string    │ string    │ int64 │\n├───────────┼───────────┼───────┤\n│ Gentoo    │ Biscoe    │   124 │\n│ Chinstrap │ Dream     │    68 │\n│ Adelie    │ Dream     │    56 │\n│ Adelie    │ Torgersen │    52 │\n│ Adelie    │ Biscoe    │    44 │\n└───────────┴───────────┴───────┘\n
\n```\n:::\n:::\n\n\nAnd do whatever you want with it:\n\n::: {#4895d869 .cell execution_count=7}\n``` {.python .cell-code}\nt.order_by(ibis._[\"count\"].asc())\n```\n\n::: {.cell-output .cell-output-display execution_count=7}\n```{=html}\n
┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓\n┃ species   ┃ island    ┃ count ┃\n┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩\n│ string    │ string    │ int64 │\n├───────────┼───────────┼───────┤\n│ Adelie    │ Biscoe    │    44 │\n│ Adelie    │ Torgersen │    52 │\n│ Adelie    │ Dream     │    56 │\n│ Chinstrap │ Dream     │    68 │\n│ Gentoo    │ Biscoe    │   124 │\n└───────────┴───────────┴───────┘\n
\n```\n:::\n:::\n\n\n## Next steps\n\nExplore some data with Ibis Birdbrain and [let us know how it\ngoes!](https://github.com/ibis-project/ibis-birdbrain/issues/new)\n\n",
+    "markdown": "---\ntitle: 'Tutorial: Python'\n---\n\n\n\n## Prerequisites\n\n1. [Install Ibis Birdbrain](/install.qmd)\n\n## Overview\n\nYou can use Ibis Birdbrain in Python.\n\n## Setup the bot\n\nFirst, import relevant modules:\n\n\n::: {#935cf68c .cell execution_count=1}\n``` {.python .cell-code}\nimport ibis\n\nfrom ibis_birdbrain import Bot\n```\n:::\n\n\nSet Ibis interactive mode:\n\n::: {#9ee1c955 .cell execution_count=2}\n``` {.python .cell-code}\nibis.options.interactive = True\n```\n:::\n\n\n### Create an Ibis connection\n\nCreate an Ibis connection to your database:\n\n::: {.callout-warning}\nWe'll create a demo database for this tutorial.\n:::\n\n::: {#1b36ceee .cell execution_count=3}\n``` {.python .cell-code}\ncon = ibis.connect(\"duckdb://penguins.ddb\")\ncon.create_table(\n    \"penguins\", ibis.examples.penguins.fetch().to_pyarrow(), overwrite=True\n)\ncon = ibis.connect(\"duckdb://penguins.ddb\")\ncon.list_tables()\n```\n\n::: {.cell-output .cell-output-stderr}\n```\nINFO:pins.cache:cache file: /Users/cody/Library/Caches/pins-py/gcs_332a30997e141da0e08f15fbfae8b3c3ec90463922d117a96fa3b1bef85a2a4c/penguins/20230905T090411Z-9aae2/data.txt\nINFO:pins.cache:cache file: /Users/cody/Library/Caches/pins-py/gcs_332a30997e141da0e08f15fbfae8b3c3ec90463922d117a96fa3b1bef85a2a4c/penguins/20230905T090411Z-9aae2/penguins.csv.gz\n```\n:::\n\n::: {.cell-output .cell-output-display execution_count=3}\n```\n['penguins']\n```\n:::\n:::\n\n\n### Create the bot\n\nYou'll create the bot by passing in the connection:\n\n::: {.callout-tip}\nFor increased accuracy, you should also pass in a `data_description` containing\ninformation about the dataset. This could be fetched from the database itself,\nmanually created, or otherwise obtained.\n\nYou should not include table names and schemas -- this will be inferred\nautomatically.\n:::\n\n::: {#f4eab662 .cell execution_count=4}\n``` {.python .cell-code}\nbot = Bot(con=con, data_description=\"the Palmer Penguins dataset\")\nbot\n```\n\n::: {.cell-output .cell-output-stderr}\n```\nINFO:root:Bot birdbrain initialized...\n```\n:::\n\n::: {.cell-output .cell-output-display execution_count=4}\n```\n\n```\n:::\n:::\n\n\n### Test the bot\n\nYou can ask the bot questions:\n\n::: {#fe023103 .cell execution_count=5}\n``` {.python .cell-code}\nres = bot(\"\"\"give me the counts of penguins by species and island from highest\nto lowest\"\"\")\nres\n```\n\n::: {.cell-output .cell-output-stderr}\n```\nINFO:root:Bot birdbrain called with text: give me the counts of penguins by species and island from highest\nto lowest\nINFO:root:Selected flow: data\nINFO:root:Executing the data flow\nINFO:root:Text to SQL task\nINFO:httpx:HTTP Request: POST https://birdbrain-eh.openai.azure.com/openai/deployments/gpt-4-turbo/chat/completions?api-version=2023-12-01-preview \"HTTP/1.1 200 OK\"\nINFO:root:Executing the SQL task\n```\n:::\n\n::: {.cell-output .cell-output-display}\n```{=html}\n
\n```\n:::\n\n::: {.cell-output .cell-output-display}\n```{=html}\n
\n```\n:::\n\n::: {.cell-output .cell-output-display execution_count=5}\n\n::: {.ansi-escaped-output}\n```{=html}\n
To: user\nFrom: birdbrain\nSubject: give me the counts of pengu...\nSent at: 2024-03-05 12:18:51.951695\nMessage: 67c02541-9406-4de5-b99e-21cc5dc8d3c5\nIbis Birdbrain has attached the results.\nAttachments:\nCodeAttachment\n    **guid**: e2152990-296e-4b92-a159-05af61b5334a\n    **time**: 2024-03-05 12:18:51.949484\n    **name**: None\n    **desc**: None\n    **language**: sql\n    **code**:\nSELECT species, island, COUNT(*) AS count\nFROM penguins\nGROUP BY species, island\nORDER BY COUNT(*) DESC\nTableAttachment\n    **guid**: e6acb87c-b4ca-4fa7-8292-638d3fc0b6e8\n    **time**: 2024-03-05 12:18:51.951600\n    **name**: None\n    **desc**: \nibis.Schema {\n  species  string\n  island   string\n  count    int64\n}\n                **table**:\n┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓\n┃ species   ┃ island    ┃ count ┃\n┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩\n│ string    │ string    │ int64 │\n├───────────┼───────────┼───────┤\n│ Gentoo    │ Biscoe    │   124 │\n│ Chinstrap │ Dream     │    68 │\n│ Adelie    │ Dream     │    56 │\n│ Adelie    │ Torgersen │    52 │\n│ Adelie    │ Biscoe    │    44 │\n└───────────┴───────────┴───────┘
\n```\n:::\n\n:::\n:::\n\n\n### Get attachments\n\nYou can get the table from the attachment:\n\n::: {#822b287e .cell execution_count=6}\n``` {.python .cell-code}\nt = res.attachments[-1].open()\nt\n```\n\n::: {.cell-output .cell-output-display execution_count=6}\n```{=html}\n
┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓\n┃ species   ┃ island    ┃ count ┃\n┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩\n│ string    │ string    │ int64 │\n├───────────┼───────────┼───────┤\n│ Gentoo    │ Biscoe    │   124 │\n│ Chinstrap │ Dream     │    68 │\n│ Adelie    │ Dream     │    56 │\n│ Adelie    │ Torgersen │    52 │\n│ Adelie    │ Biscoe    │    44 │\n└───────────┴───────────┴───────┘\n
\n```\n:::\n:::\n\n\nAnd do whatever you want with it:\n\n::: {#f616ff8d .cell execution_count=7}\n``` {.python .cell-code}\nt.order_by(ibis._[\"count\"].asc())\n```\n\n::: {.cell-output .cell-output-display execution_count=7}\n```{=html}\n
┏━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┓\n┃ species   ┃ island    ┃ count ┃\n┡━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━┩\n│ string    │ string    │ int64 │\n├───────────┼───────────┼───────┤\n│ Adelie    │ Biscoe    │    44 │\n│ Adelie    │ Torgersen │    52 │\n│ Adelie    │ Dream     │    56 │\n│ Chinstrap │ Dream     │    68 │\n│ Gentoo    │ Biscoe    │   124 │\n└───────────┴───────────┴───────┘\n
\n```\n:::\n:::\n\n\n## Next steps\n\nExplore some data with Ibis Birdbrain and [let us know how it\ngoes!](https://github.com/ibis-project/ibis-birdbrain/issues/new)\n\n",
     "supporting": [
       "python_files/figure-html"
     ],
diff --git a/docs/install.qmd b/docs/install.qmd
index 82cca07..4b000e4 100644
--- a/docs/install.qmd
+++ b/docs/install.qmd
@@ -10,33 +10,32 @@ pip install ibis-birdbrain
 
 ## Data platform setup
 
-:::{.callout-warning}
-Documentation coming soon!
-:::
+Create an Ibis connection:
 
 :::{.callout-warning}
-Only DuckDB supported for now. All 18+ Ibis backends coming soon.
+Only DuckDB is installed by default. For now, you need to install other backends
+manually with Ibis.
 :::
 
+```{python}
+import ibis
+
+backend = "duckdb"
+backend_uri = ""
+
+con = ibis.connect(f"{backend}://{backend_uri}")
+con
+```
+
 ## AI platform setup
 
-:::{.callout-warning}
-Documentation coming soon!
-:::
+See [Marvin documentation for
+setup](https://www.askmarvin.ai/docs/configuration/settings/).
 
 :::{.callout-warning}
-Only Azure OpenAI is supported for now. All Marvin providers coming soon.
+Only OpenAI and Azure OpenAI are supported for now.
 :::
 
-Create the `~/.birdbrain/.env` file:
-
-```txt
-MARVIN_AZURE_OPENAI_API_KEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
-MARVIN_AZURE_OPENAI_API_BASE="https://birdbrain.openai.azure.com"
-MARVIN_AZURE_OPENAI_DEPLOYMENT_NAME="birdbrain-4-32k"
-MARVIN_AZURE_OPENAI_API_TYPE="azure"
-```
-
 ## Next steps
 
 [Learn how get started with Ibis Birdbrain's CLI](tutorials/cli.qmd).
diff --git a/docs/tutorials/cli.qmd b/docs/tutorials/cli.qmd
index a8a0dc6..a8267ea 100644
--- a/docs/tutorials/cli.qmd
+++ b/docs/tutorials/cli.qmd
@@ -13,6 +13,21 @@ interface (CLI):
 $ birdbrain
 ```
 
+```html
+ Usage: birdbrain [OPTIONS] COMMAND [ARGS]...                                                                                                                                                             
+                                                                                                                                                                                                          
+╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --install-completion          Install completion for the current shell.                                                                                                                                │
+│ --show-completion             Show completion for the current shell, to copy it or customize the installation.                                                                                         │
+│ --help                        Show this message and exit.                                                                                                                                              │
+╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ ipy                                                                                                 ipy                                                                                                │
+│ test                                                                                                test                                                                                               │
+╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+```
+
 ## Next steps
 
 [Learn how to work with Ibis Birdbrain in Python](/tutorials/python.qmd).
diff --git a/docs/tutorials/python.qmd b/docs/tutorials/python.qmd
index c9830d5..1ca4a97 100644
--- a/docs/tutorials/python.qmd
+++ b/docs/tutorials/python.qmd
@@ -6,9 +6,7 @@
 
 ## Overview
 
-You can use Ibis Birdbrain as a Python library, but it is often used through an
-interactive Python session. You can [see how to start one with the `birdbrain`
-CLI with Ibis Birdbrain ready to use](/tutorials/cli.qmd).
+You can use Ibis Birdbrain in Python.
 
 ## Setup the bot