From d252d9e2dbb6a4fd162a9498e7e542b306ebaad7 Mon Sep 17 00:00:00 2001 From: Cody Date: Tue, 5 Mar 2024 11:24:29 -0500 Subject: [PATCH] some docs --- .../attachments/execute-results/html.json | 16 +++++ .../concepts/bots/execute-results/html.json | 12 ++++ .../concepts/flows/execute-results/html.json | 12 ++++ .../messages/execute-results/html.json | 12 ++++ .../concepts/tasks/execute-results/html.json | 12 ++++ .../python/execute-results/html.json | 16 +++++ docs/_quarto.yml | 3 + docs/tutorials/python.qmd | 70 +++++++++++++++++++ pyproject.toml | 3 +- 9 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 docs/_freeze/concepts/attachments/execute-results/html.json create mode 100644 docs/_freeze/concepts/bots/execute-results/html.json create mode 100644 docs/_freeze/concepts/flows/execute-results/html.json create mode 100644 docs/_freeze/concepts/messages/execute-results/html.json create mode 100644 docs/_freeze/concepts/tasks/execute-results/html.json create mode 100644 docs/_freeze/tutorials/python/execute-results/html.json diff --git a/docs/_freeze/concepts/attachments/execute-results/html.json b/docs/_freeze/concepts/attachments/execute-results/html.json new file mode 100644 index 0000000..2e67a77 --- /dev/null +++ b/docs/_freeze/concepts/attachments/execute-results/html.json @@ -0,0 +1,16 @@ +{ + "hash": "e1d529a819e9e68cc7f0a9043ae41cbb", + "result": { + "engine": "jupyter", + "markdown": "---\ntitle: Attachments\n---\n\n\n\nIbis Birdbrain passes Python objects as `Attachments` to [`Messages`](./messages.qmd). This allows the user, itself, and (eventually) other bots to interact with data, code, and more.\n\n\n## Usage\n\n\n::: {#77a9f256 .cell execution_count=1}\n``` {.python .cell-code}\nfrom ibis_birdbrain.attachments import Attachment, Attachments\n\na1 = Attachment(content=\"Hello, world!\")\na1\n```\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\nAttachment\n **guid**: aefa7dd8-1504-466e-afa8-fa0053ef087e\n **time**: 2024-03-05 11:22:38.343515\n **name**: None\n **desc**: None\n```\n:::\n:::\n\n\n## TableAttachment\n\nA `TableAttachment` contains an Ibis table:\n\n::: {#9a87d9f6 .cell execution_count=2}\n``` {.python .cell-code}\nimport ibis\n\nfrom ibis_birdbrain.attachments import TableAttachment\n\nibis.options.interactive = True\n\nt = ibis.examples.penguins.fetch()\n\na2 = TableAttachment(content=t)\na2\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}\n```{=html}\n
\n```\n:::\n\n::: {.cell-output .cell-output-display execution_count=2}\n\n::: {.ansi-escaped-output}\n```{=html}\n
TableAttachment\n    **guid**: 5992ed9a-8a14-46c6-9da8-afdb3644a23d\n    **time**: 2024-03-05 11:22:40.051587\n    **name**: penguins\n    **desc**: \nibis.Schema {\n  species            string\n  island             string\n  bill_length_mm     float64\n  bill_depth_mm      float64\n  flipper_length_mm  int64\n  body_mass_g        int64\n  sex                string\n  year               int64\n}\n                **table**:\n┏━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓\n┃ species ┃ island    ┃ bill_length_mm ┃ bill_depth_mm ┃ flipper_length_mm ┃ body_mass_g ┃ sex    ┃ year  ┃\n┡━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩\n│ string  │ string    │ float64        │ float64       │ int64             │ int64       │ string │ int64 │\n├─────────┼───────────┼────────────────┼───────────────┼───────────────────┼─────────────┼────────┼───────┤\n│ Adelie  │ Torgersen │           39.1 │          18.7 │               181 │        3750 │ male   │  2007 │\n│ Adelie  │ Torgersen │           39.5 │          17.4 │               186 │        3800 │ female │  2007 │\n│ Adelie  │ Torgersen │           40.3 │          18.0 │               195 │        3250 │ female │  2007 │\n│ Adelie  │ Torgersen │           NULL │          NULL │              NULL │        NULL │ NULL   │  2007 │\n│ Adelie  │ Torgersen │           36.7 │          19.3 │               193 │        3450 │ female │  2007 │\n│ Adelie  │ Torgersen │           39.3 │          20.6 │               190 │        3650 │ male   │  2007 │\n│ Adelie  │ Torgersen │           38.9 │          17.8 │               181 │        3625 │ female │  2007 │\n│ Adelie  │ Torgersen │           39.2 │          19.6 │               195 │        4675 │ male   │  2007 │\n│ Adelie  │ Torgersen │           34.1 │          18.1 │               193 │        3475 │ NULL   │  2007 │\n│ Adelie  │ Torgersen │           42.0 │          20.2 │               190 │        4250 │ NULL   │  2007 │\n│ …       │ …         │              … │             … │                 … │           … │ …      │     … │\n└─────────┴───────────┴────────────────┴───────────────┴───────────────────┴─────────────┴────────┴───────┘
\n```\n:::\n\n:::\n:::\n\n\nNotice the name, description (schema), and preview are automatically populated.\n\n## CodeAttachment\n\nA `CodeAttachment` contains code -- typically Python or SQL:\n\n::: {#89ecfbf6 .cell execution_count=3}\n``` {.python .cell-code}\nfrom ibis_birdbrain.attachments import CodeAttachment\n\na3 = CodeAttachment(content=\"select 1 as id\", language=\"sql\")\na3\n```\n\n::: {.cell-output .cell-output-display execution_count=3}\n```\nCodeAttachment\n    **guid**: 8138742b-dcef-4735-b452-8481468e12da\n    **time**: 2024-03-05 11:22:40.087917\n    **name**: None\n    **desc**: None\n    **language**: sql\n    **code**:\nselect 1 as id\n```\n:::\n:::\n\n\n",
+    "supporting": [
+      "attachments_files"
+    ],
+    "filters": [],
+    "includes": {
+      "include-in-header": [
+        "\n\n\n"
+      ]
+    }
+  }
+}
\ No newline at end of file
diff --git a/docs/_freeze/concepts/bots/execute-results/html.json b/docs/_freeze/concepts/bots/execute-results/html.json
new file mode 100644
index 0000000..f2eaa85
--- /dev/null
+++ b/docs/_freeze/concepts/bots/execute-results/html.json
@@ -0,0 +1,12 @@
+{
+  "hash": "bd2906497289e9de4361517b57031090",
+  "result": {
+    "engine": "jupyter",
+    "markdown": "---\ntitle: Bots\n---\n\n\n\nIbis Birdbrain implements a `Bot` calss that can be used to instantiate one or more bots that automate various tasks.\n\n## Usage\n\n\n::: {#a5d8d0d4 .cell execution_count=1}\n``` {.python .cell-code}\nfrom ibis_birdbrain import Bot\nBot\n```\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\nibis_birdbrain.bot.Bot\n```\n:::\n:::\n\n\n",
+    "supporting": [
+      "bots_files"
+    ],
+    "filters": [],
+    "includes": {}
+  }
+}
\ No newline at end of file
diff --git a/docs/_freeze/concepts/flows/execute-results/html.json b/docs/_freeze/concepts/flows/execute-results/html.json
new file mode 100644
index 0000000..7efee18
--- /dev/null
+++ b/docs/_freeze/concepts/flows/execute-results/html.json
@@ -0,0 +1,12 @@
+{
+  "hash": "5ca217bfa5ee488df2c050375105b2a1",
+  "result": {
+    "engine": "jupyter",
+    "markdown": "---\ntitle: Flows\n---\n\n\n\nIbis Birdbrain's [`Bot`](./bot.qmd) chooses a `Flow` to execute based on [`Messages`](./messages.qmd).\n\nA Flow takes Messages as input and returns Messages as output. The details of a given Flow are specific to itself, running a series of [`Tasks`](./tasks.qmd) to accomplish its goal.\n\n## Usage\n\n\n::: {#254b2753 .cell execution_count=1}\n``` {.python .cell-code}\nfrom ibis_birdbrain.flows import Flow, Flows\n\nflow = Flow()\nflow\n```\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n\n```\n:::\n:::\n\n\n",
+    "supporting": [
+      "flows_files"
+    ],
+    "filters": [],
+    "includes": {}
+  }
+}
\ No newline at end of file
diff --git a/docs/_freeze/concepts/messages/execute-results/html.json b/docs/_freeze/concepts/messages/execute-results/html.json
new file mode 100644
index 0000000..0281880
--- /dev/null
+++ b/docs/_freeze/concepts/messages/execute-results/html.json
@@ -0,0 +1,12 @@
+{
+  "hash": "a1999ce28adcecc054b19196cb9fa5fb",
+  "result": {
+    "engine": "jupyter",
+    "markdown": "---\ntitle: Messages\n---\n\n\n\nIbis Birdbrain communicates with the user, itself, and (eventually) other bots through `Messages`. A `Message` is a simple wrapper around text with metadata and optional [`Attachments`](./attachments.qmd).\n\n\n## Usage\n\n\n::: {#9c0146d7 .cell execution_count=1}\n``` {.python .cell-code}\nfrom ibis_birdbrain.messages import Message, Messages, Email\n\nm1 = Message(\"Hello, world!\")\nm1\n```\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\nMessage(5956d627-9038-4bb4-b827-1d9ed646c75e)\n```\n:::\n:::\n\n\n## Emails\n\nCurrently, the only implementation of `Message` that is viewable as a proper string is `Email`.\n\n::: {#2e43c663 .cell execution_count=2}\n``` {.python .cell-code}\ne1 = Email(\"Hello\")\ne2 = Email(\", world!\")\n\nmessages = Messages([e1, e2])\nmessages\n```\n\n::: {.cell-output .cell-output-display execution_count=2}\n```\nTo: \nFrom: \nSubject: \nSent at: 2024-03-05 11:22:52.258182\nMessage: e855820a-eedd-4229-96d1-7ae525800995\n\nHello\n\nAttachments:\n\n\n---\nTo: \nFrom: \nSubject: \nSent at: 2024-03-05 11:22:52.258207\nMessage: 50a43477-12d3-4138-b5ff-38fd5b2b7704\n\n, world!\n\nAttachments:\n\n```\n:::\n:::\n\n\n",
+    "supporting": [
+      "messages_files"
+    ],
+    "filters": [],
+    "includes": {}
+  }
+}
\ No newline at end of file
diff --git a/docs/_freeze/concepts/tasks/execute-results/html.json b/docs/_freeze/concepts/tasks/execute-results/html.json
new file mode 100644
index 0000000..8685211
--- /dev/null
+++ b/docs/_freeze/concepts/tasks/execute-results/html.json
@@ -0,0 +1,12 @@
+{
+  "hash": "ea522272a8d0a666dacb53873801a1aa",
+  "result": {
+    "engine": "jupyter",
+    "markdown": "---\ntitle: Tasks\n---\n\n\n\nIbis Birdbrain's [`Flow`](./flow.qmd) executes one or more `Tasks` to accomplish its goal. A `Task` is a single unit of work that takes a [`Message`](./message.qmd) as input and returns a `Message` as output.\n\n## Usage\n\n\n::: {#ef7b5518 .cell execution_count=1}\n``` {.python .cell-code}\nfrom ibis_birdbrain.tasks import Task, Tasks\n\ntask = Task()\ntask\n```\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n\n```\n:::\n:::\n\n\n",
+    "supporting": [
+      "tasks_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
new file mode 100644
index 0000000..66d29b6
--- /dev/null
+++ b/docs/_freeze/tutorials/python/execute-results/html.json
@@ -0,0 +1,16 @@
+{
+  "hash": "3e43b66284c7c7f4120c5c1002cdf3c2",
+  "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::: {#c610da97 .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::: {#da2b0df7 .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::: {#08ede976 .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::: {#19399376 .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::: {#b3a365db .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:23:48.370476\nMessage: a6dff0f1-8fa5-4fe6-a14d-7576736d88e3\nIbis Birdbrain has attached the results.\nAttachments:\nCodeAttachment\n    **guid**: 3a358f68-357b-44a2-800e-4d96fb3b9a10\n    **time**: 2024-03-05 11:23:48.368303\n    **name**: None\n    **desc**: None\n    **language**: sql\n    **code**:\nSELECT species, island, COUNT(*) AS count FROM penguins GROUP BY species, island ORDER BY count DESC\nTableAttachment\n    **guid**: d1345277-18aa-46d7-ab71-f026d71cfb19\n    **time**: 2024-03-05 11:23:48.370386\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 attachment back:\n\n::: {#ad930927 .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\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"
+    ],
+    "filters": [],
+    "includes": {
+      "include-in-header": [
+        "\n\n\n"
+      ]
+    }
+  }
+}
\ No newline at end of file
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
index 9ea2c05..34392bf 100644
--- a/docs/_quarto.yml
+++ b/docs/_quarto.yml
@@ -2,6 +2,9 @@
 project:
   type: website
 
+execute:
+  freeze: auto  # re-render only when source changes
+
 # website
 website:
 
diff --git a/docs/tutorials/python.qmd b/docs/tutorials/python.qmd
index 0a5e4c5..81273e6 100644
--- a/docs/tutorials/python.qmd
+++ b/docs/tutorials/python.qmd
@@ -10,6 +10,76 @@ 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).
 
+## Setup the bot
+
+First, import relevant modules:
+
+```{python}
+import ibis
+
+from ibis_birdbrain import Bot
+```
+
+Set Ibis interactive mode:
+
+```{python}
+ibis.options.interactive = True
+```
+
+### Create an Ibis connection
+
+Create an Ibis connection to your database:
+
+::: {.callout-warning}
+We'll create a demo database for this tutorial.
+:::
+
+```{python}
+con = ibis.connect("duckdb://penguins.ddb")
+con.create_table(
+    "penguins", ibis.examples.penguins.fetch().to_pyarrow(), overwrite=True
+)
+con = ibis.connect("duckdb://penguins.ddb")
+con.list_tables()
+```
+
+### Create the bot
+
+You'll create the bot by passing in the connection:
+
+::: {.callout-tip}
+For increased accuracy, you should also pass in a `data_description` containing
+information about the dataset. This could be fetched from the database itself,
+manually created, or otherwise obtained.
+
+You should not include table names and schemas -- this will be inferred
+automatically.
+:::
+
+```{python}
+bot = Bot(con=con, data_description="the Palmer Penguins dataset")
+bot
+```
+
+### Test the bot
+
+You can ask the bot questions:
+
+```{python}
+res = bot("""give me the counts of penguins by species and island from highest
+to lowest""")
+res
+```
+
+### Get attachments
+
+You can get the table attachment back:
+
+```{python}
+t = res.attachments[-1].open()
+t
+```
+
 ## Next steps
 
 Explore some data with Ibis Birdbrain and [let us know how it
diff --git a/pyproject.toml b/pyproject.toml
index 8831195..28193fa 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -11,7 +11,7 @@ version = "0.1.0"
 authors = [
   { name="Cody", email="cody@dkdc.dev" },
 ]
-description = "the portable Python ML-powered data bot"
+description = "the portable Python LM-powered data bot"
 readme = "README.md"
 requires-python = ">=3.11"
 classifiers = [
@@ -41,4 +41,3 @@ dependencies = [
 
 [project.scripts]
 birdbrain = "ibis_birdbrain.cli:app"
-