rework docs (#43)

* rework docs

* more justfile

docs/_quarto.yml

@@ -53,8 +53,8 @@ website:
       #- sidebar:how-to
       #- sidebar:reference
 
-    right:
-      - posts.qmd
+    # right:
+      #- posts.qmd
       #- release_notes.md # TODO: release notes
       #- sidebar:contribute
 
@@ -74,7 +74,11 @@ website:
       collapse-level: 2
       contents:
         - why.qmd
-        - auto: concepts/*.qmd
+        - concepts/bots.qmd
+        - concepts/messages.qmd
+        - concepts/attachments.qmd
+        - concepts/flows.qmd
+        - concepts/tasks.qmd
     - id: how-to
       title: "How-to"
       style: "docked"

docs/concepts/attachments.qmd

@@ -0,0 +1,43 @@
+# Attachments
+
+Ibis 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.
+
+
+## Usage
+
+```{python}
+from ibis_birdbrain.attachments import Attachment, Attachments
+
+a1 = Attachment(content="Hello, world!")
+a1
+```
+
+## TableAttachment
+
+A `TableAttachment` contains an Ibis table:
+
+```{python}
+import ibis
+
+from ibis_birdbrain.attachments import TableAttachment
+
+ibis.options.interactive = True
+
+t = ibis.examples.penguins.fetch()
+
+a2 = TableAttachment(content=t)
+a2
+```
+
+Notice the name, description (schema), and preview are automatically populated.
+
+## CodeAttachment
+
+A `CodeAttachment` contains code -- typically Python or SQL:
+
+```{python}
+from ibis_birdbrain.attachments import CodeAttachment
+
+a3 = CodeAttachment(content="select 1 as id", language="sql")
+a3
+```

docs/concepts/bots.qmd

@@ -0,0 +1,10 @@
+# Bots
+
+Ibis Birdbrain implements a `Bot` calss that can be used to instantiate one or more bots that automate various tasks.
+
+## Usage
+
+```{python}
+from ibis_birdbrain import Bot
+Bot
+```

docs/concepts/flows.qmd

@@ -0,0 +1,14 @@
+# Flows
+
+Ibis Birdbrain's [`Bot`](./bot.qmd) chooses a `Flow` to execute based on [`Messages`](./messages.qmd).
+
+A 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.
+
+## Usage
+
+```{python}
+from ibis_birdbrain.flows import Flow, Flows
+
+flow = Flow()
+flow
+```

docs/concepts/messages.qmd

@@ -0,0 +1,25 @@
+# Messages
+
+Ibis 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).
+
+
+## Usage
+
+```{python}
+from ibis_birdbrain.messages import Message, Messages, Email
+
+m1 = Message("Hello, world!")
+m1
+```
+
+## Emails
+
+Currently, the only implementation of `Message` that is viewable as a proper string is `Email`.
+
+```{python}
+e1 = Email("Hello")
+e2 = Email(", world!")
+
+messages = Messages([e1, e2])
+messages
+```

docs/concepts/tasks.qmd

@@ -0,0 +1,12 @@
+# Tasks
+
+Ibis 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.
+
+## Usage
+
+```{python}
+from ibis_birdbrain.tasks import Task, Tasks
+
+task = Task()
+task
+```

docs/index.qmd

@@ -1,6 +1,6 @@
 ---
 title: "Ibis Birdbrain"
-description: "the portable Python AI-powered data bot"
+description: "the portable Python LM-powered data bot"
 repo-actions: false
 code-annotations: hover
 format:
@@ -13,22 +13,22 @@ about:
   links:
     - icon: info-circle
       text: Why Ibis Birdbrain?
-      href: /ibis-birdbrain/why
+      href: why.qmd
     - icon: download
       text: Installation
-      href: /ibis-birdbrain/install
+      href: install.qmd
     - icon: book
       text: "Tutorial: getting started"
-      href: /ibis-birdbrain/tutorials/cli
+      href: tutorials/python.qmd
     - icon: github
       text: GitHub
       href: https://github.com/ibis-project/ibis-birdbrain
     - icon: slack
       text: Chat
       href: https://ibis-project.zulipchat.com
-    - icon: rss
-      text: RSS
-      href: https://ibis-project.github.io/ibis-birdbrain/posts.xml
+    # - icon: rss
+    #   text: RSS
+    #   href: https://ibis-project.github.io/ibis-birdbrain/posts.xml
 ---
 
 ::: {#about}

docs/tutorials/cli.qmd

@@ -2,53 +2,17 @@
 
 ## Prerequisites
 
-- [Install Ibis Birdbrain](/install.qmd)
+1. [Install Ibis Birdbrain](/install.qmd)
 
 ## Overview
 
-With Ibis Birdbrain installed, you can use the `birdbrain` command-line interface (CLI):
+With Ibis Birdbrain installed, you can use the `birdbrain` command-line
+interface (CLI):
 
 ```bash
 $ birdbrain
 ```
 
-```html
- Usage: birdbrain [OPTIONS] COMMAND [ARGS]...
-
-╭─ Options ──────────────────────────────────────────────────────────────────────╮
-│ --version                     Show version.                                    │
-│ --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                                   │
-╰────────────────────────────────────────────────────────────────────────────────╯
-```
-
-## Starting an interactive Python session
-
-You can use the `ipy` subcommand to start an interactive Python session with Ibis Birdbrain ready to use:
-
-```bash
-$ birdbrain ipy
-```
-
-```html
-access to: birdbrain
-model: azure_openai/gpt-4-32k
-Python 3.11.5 (main, Sep 14 2023, 13:17:51) [Clang 14.0.3 (clang-1403.0.22.14.1)]
-Type 'copyright', 'credits' or 'license' for more information
-IPython 8.16.0 -- An enhanced Interactive Python. Type '?' for help.
-
-[ins] In [1]: birdbrain
-Out[1]: <Bot: birdbrain>
-
-[ins] In [2]:
-```
-
 ## Next steps
 
 [Learn how to work with Ibis Birdbrain in Python](/tutorials/python.qmd).