+ `msg_payload`:
diff --git a/docs/contexts_context.md b/docs/contexts_context.md index a1759b57..ad342143 100644 --- a/docs/contexts_context.md +++ b/docs/contexts_context.md @@ -1,17 +1,39 @@ --- layout: default -title: Context class +title: Creating a New Context parent: Contexts nav_order: 1 has_toc: true --- -# Context class +# Creating a New Context -The context class is the main +We've tried to make creating a new context as easy as possible by providing some helper utilities in the Beaker CLI for context management. First, you can list the available contexts with `beaker context list`. You should see the default context that comes pre-installed with Beaker. +Next, ensure you have [`hatchling`](https://hatch.pypa.io/latest/). You can do this with `pip install hatch`. Now you're ready to create your `hatch` project with `hatch new customcontext` where `customcontext` is the name of your new context. This will create a new directory with the name of your context and a basic template to get you started. +From there, navigate to this new directory with `cd customcontext` and you'll see a few files and directories created for you. You are ready to use Beaker's context builder to create a context template. To do this, simply run `beaker context new`. This will step you through a few prompts to help build out your context. +
+ 
+
+Once that is completed, you'll notice a new `src` directory. Overall, your project should have the following structure:
-## Coming soon
+```
+customcontext/
+├── LICENSE.txt
+├── README.md
+├── pyproject.toml
+├── src/
+│ ├── customcontext/
+│ │ ├── __init__.py
+│ │ ├── __about__.py
+│ │ └── customcontext/
+│ │ ├── __init__.py
+│ │ ├── agent.py
+│ │ └── context.py
+├── tests/
+```
+
+From here on out, your work is to customize the `agent.py` and `context.py` files to meet your needs. Once you're ready to give it a shot, you can run `pip install -e .` to install your context in development mode. Note that if you're using an environment without `beaker-kernel` installed you'll need to add it to the `pyproject.toml` file.
\ No newline at end of file
diff --git a/docs/debugging.md b/docs/debugging.md
index 8e54f1e8..63107b45 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -1,6 +1,6 @@
---
layout: default
-title: Getting Started
+title: Debugging
nav_order: 6
has_toc: true
---
@@ -13,4 +13,6 @@ Logging and debugging information can be bubbled up in two seperate ways, either
in the Jupyter service logs, or as `debug-event` messages from the kernel or
subkernel.
+## Debugging
+It is possible to run Beaker with a debugger. Reach out to the Beaker team for more information about how to configure your IDE to do this.
diff --git a/docs/getting_started.md b/docs/getting_started.md
index f047d7e0..f0fc174f 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -7,4 +7,61 @@ has_toc: true
# Getting Started
-## Coming soon
+There are a few things to know when getting started with Beaker. Let's run through them quickly:
+
+- [Setup and running your first notebook](#setup-and-running-your-first-notebook)
+- [Beaker as a drop in replacement for Jupyter](#beaker-as-a-drop-in-replacement-for-jupyter)
+- [Beaker file system browser](#beaker-file-system-browser)
+- [Saving and loading Beaker notebooks](#saving-and-loading-beaker-notebooks)
+- [Navigation between chat and coding interfaces](#navigation-between-chat-and-coding-interfaces)
+- [Setting the context](#setting-the-context)
+
+
+## Setup and running your first notebook
+
+Once you've installed Beaker, you should ensure you're config is ready by running `beaker config update`. At minimum, you'll need to provide your OpenAI API key. The rest of the config can be left _as is_ for now. Then just run `beaker notebook` and navigate to [`localhost:8000`](http://localhost:8000) in your browser.
+
+
+
+ 
+
+
+
+## Beaker as a drop in replacement for Jupyter
+
+Beaker truly is designed to be a drop-in replacement for Jupyter notebooks. The core functionality is identical--you can run code cells, you can edit code cells, you can add new code cells, etc. The only difference is that you have a conversational agent at your fingertips to help you write code and explore data. We've worked hard to achieve parity with Jupyter, including using the same keybindings and a similar UIs for the coding interface.
+
+
+
+ 
+
+
+## Beaker file system browser
+
+Beaker has a built in file system browser that lets you navigate the file system and upload and download files. You can access the file system browser by clicking the `Files` icon in the sidebar.
+
+
+
+ 
+
+
+## Saving and loading Beaker notebooks
+
+Beaker notebooks are easy to save and load. You can save a notebook by clicking the `Save` button in the top bar. You can double click on a notebook in the file browser to load it. And of course, notebooks are exported to `.ipynb` format so you can use them in any other Jupyter-compatible environment.
+
+
+
+ 
+
+
+## Navigation between chat and coding interfaces
+
+It's easy to hop between the chat interface and the coding interface. You can access the chat interface by clicking the `Chat` icon in the top menu. You can also use that menu to swap between light and dark themes.
+
+
+
+ 
+
+
+## Setting the context
+
+If you're using a custom context you'll want to make sure it's set as the current context. To do that, click the dropdown menu in the top left of the coding interface. If you're in the chat interface click the green button on the left hand side.
+
+
+
+ 
+
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 7cfd2795..9404c696 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,35 +5,23 @@ nav_order: 1
has_toc: true
---
-# Beaker Kernel: Contextually-aware notebooks with built-in AI assistant
+# Beaker: the AI-first coding notebook
-Beaker is a custom Jupyter kernel that allows you not just work in notebooks in
-the language of your choice, but to integrate notebooks into any web
-application. You can design your own notebook or not even display a notebook at
-all, allowing native elements in your web application to run code in any
-language in a persistent session. And by leveraging the power of LLMs (Large
-Language Models), you can easily super-power your application and/or notebook
-with a powerful [ReAct](https://www.promptingguide.ai/techniques/react) AI agent
-powered by [Archytas](https://github.com/jataware/archytas).
+Beaker is a next generation coding notebook built for the AI era. Beaker seamlessly integrates a Jupyter-like experience with an AI agent that can be used to generate code and run code on the user's behalf. The agent has access to the entire notebook environment as its context, allowing it to make smart decisions about the code to generate and run. It can even debug itself and fix errors so that you don't have to. When the agent wants to use a library that isn't installed, it can even install it automatically.
-The Beaker AI agent can generate code to populate an existing notebook, or run
-code in the notebook environment in the background, passing the updated state
-or task response to the front-end for display. Possible uses of Beaker include
-AI powered auto-complete, assistance writing code,
+Beyond that, Beaker solves one of the major challenges presented by coding notebooks--it introduces a true _undo_ mechanism so that the user can roll back to any previous state in the notebook. Beaker also lets you swap effortlessly between a notebook style coding interface and a chat style interface, giving you the best of both worlds. Since everything is interoperable with Jupyter, you can always export your notebook and use it in any other Jupyter-compatible environment.
+Beaker is powered by [Archytas](https://github.com/jataware/archytas), our framework for building AI agents that can interact with code and advanced users can generate their own custom agents to meet their specific needs. These agents can have custom ReAct toolsets built in and can be extended to support any number of use cases.
-## Components of Beaker
+We like to think of Beaker as a (much better!) drop in replacement for workflows where you'd normally rely on Jupyter notebooks and we hope you'll give it a try and let us know what you think!
-This package contains the following components:
+## Quick demo
-* The Beaker Jupyter kernel (`beaker`)
-* A stand-alone Jupyter service (`service`)
- * Contains a both a production-ready custom server and a standalone
- development interface
-* A library of contexts (`contexts`) that can be extended to add functionality
-to Beaker
-* The Beaker AI/LLM agent (`agent`) that brings the power of LLMs to whatever
-you are doing, wherever you are doing it
+Here is a quick demo of using Beaker to interact with a [free weather API](https://open-meteo.com/en/docs), fetch some data, perform some data transformations and a bit of analysis. This is really just scratching the surface of what you can do with Beaker, but it gives you a sense of the kinds of things it can do.
+
+
+
+
+
## How Beaker works
@@ -57,24 +45,27 @@ Beaker, you need to set a context.
## Contexts
-Setting a [context](./contexts.html) adds extra functionality to the existing
-session. Where before Beaker was a slightly smarter Jupyter notebook, now it
-has a mission and special tools at its disposal. The contexts add custom
-message handlers, tools for the agent, and a specialized LLM prompt to focus
-the agent to help in the current situation at hand.
+Contexts provide behind the scene magic to make Beaker work for you.
+Contexts let you add extra functionality to Beaker to support your specific use case, including custom data loaders,
+bespoke tools for your agent to utilize, customized LLM prompts, and custom actions that facilitate integration with external applications.
+Though Beaker's out of the box context provides robust functionality for a wide array of data analysis tasks,
+you can easily create and set custom [contexts](./contexts.html). With a custom context, Beaker now
+has a mission and special tools at its disposal.
+
+
+## How is Beaker different from Jupyter?
+We like to think of Beaker as Jupyter on AI steroids. It provides much the same functionality as a
+Jupyter notebook except that the user has access to a conversational agent that can
+write and run code. This is hugely beneficial for speeding up data analysis tasks and for tedious things like
+generating plotting code. Since the agent has full visibility to the entire notebook environment it can write
+high fidelity code that typically works out of the box. When its code fails though, it can automatically read tracebacks
+and fix its errors.
-## Differences from vanilla Jupyter
+Additionally, Beaker introduces a true undo mechanism so that the user can roll back to any previous state in the notebook.
+This is a killer feature for coding notebooks since it allows the user to experiment with ideas freely without the fear of breaking
+their environment.
-This setup uses stock Jupyter services as provided in the Jupyter Python
-packages.
+Finally, Beaker lets you swap effortlessly between a notebook style coding interface and a chat style interface, giving you the best of both worlds.
-The entry point of the docker file runs the file main.py which starts a
-JupyterLab Server App. The only differences here are:
-1. This service does not run any front-end and only provides API and websocket
-access as the expectation is for
-2. Some settings are changed to allow access through the Terarium interface and
-be accessed by the proxy kernel:
- 1. allow_orgin rule
- 2. disable_check_xsrf security issue to allow the proxy kernel to make API
- calls
+Since everything is interoperable with Jupyter, you can always export your notebook and use it in any other Jupyter-compatible environment.
diff --git a/docs/install.md b/docs/install.md
index fa88d77b..2af7f904 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -7,62 +7,40 @@ has_toc: true
# Install / setup
-## Structure
+Installing Beaker is easy! All you need to do is run:
-A Beaker install consists of the following:
-
-* A Jupyter kernel (`beaker-kernel`)
-* A Jupyter server (`beaker-server`) (optional but recommended)
-* LLM integration (`archytas`) (optional)
-* Custom contexts (`contexts`) (optional)
-
-
-### Installing the kernel
-
-Beaker-kernel can be installed as a normal Python package via pip, by using
-[Hatch](https://hatch.pypa.io/latest/), or as a docker image.
-
-
-
-### python
-
-Via pypi:
```bash
pip install beaker-kernel
```
+Next, you'll run `beaker config update` to set up your configuration. This will create a `beaker.conf` file in your home directory's `.config` folder. You can leave everything as the default except for the `LLM_SERVICE_TOKEN` which you'll need to set to your OpenAI API (or other LLM provider) key.
+
+Now that you've got things installed and set up, just simply run:
-Local installation:
```bash
-$ pip install .
-```
+beaker notebook
+```
+
+Your notebook server will start up and Beaker will be ready to use at [`localhost:8888`](http://localhost:8888).
+
+## Installing custom contexts
+
+To install a custom context, you should navigate to the context's folder and run:
-Dev installation:
```bash
$ pip install -e .
```
-During pip install, the kernel is automatically installed in the proper
-location in your development environment.
+This will install the context so that it can be automatically loaded the next time you start Beaker.
+For debugging your custom context, you can try navigating to [`localhost:8888/dev`](http://localhost:8888/dev) which will launch the development UI. This gives you access to enhanced logging, the ability to inspect messages, and the ability to launch custom actions from the UI.
-## Dev setup
+## Developer setup
-This package is bundled with a basic development UI for development and
-testing, via docker-compose.
+For developers interested in modifying Beaker or contributing to it, you can start by cloning the repo and running:
```bash
$ make dev
```
-This will start the Jupyter service and launch a specialized notebook interface
-in your browser similar to if you ran `$ jupyter notebook` normally.
-
-
-## Adding python dependencies/updating requirements
-
-The python requirements are maintained by Hatch and are defined in the
-pyproject.toml file.
-
-Please see the [Hatch dependency documentation](https://hatch.pypa.io/latest/config/dependency/)
-for more details.
+This will start Beaker in development mode which will automatically reload when you make changes to the code so you can quickly iterate on your changes to the core codebase.
\ No newline at end of file