Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation #84

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
174 changes: 24 additions & 150 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,168 +1,42 @@
# Beaker Kernel: Contextually-aware notebooks with built-in AI assistant
Beaker allows you not just work in notebooks, but to integrate notebooks into any web application, and by leveraging the power of LLMs, you can easily super-power your application and/or notebook with a powerful [ReAct](https://www.promptingguide.ai/techniques/react) agent powered by [Archytas](https://github.com/jataware/archytas).
# Beaker: the AI-first coding notebook
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 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. This allows for tasks such as asking Beaker to create a certain document, and not only will Beaker generate the text of the document, but will take care of creating, filling, and saving the document, and then notify the front-end the id of the document so it can be displayed to the user once it's complete.
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:
## Getting Started

* 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
Getting Beaker up and running is easy! All you need to do is install the Beaker with:


## How Beaker works

The Beaker kernel acts custom Python kernel that sits between the user interface and the execution environment (subkernel) and proxies messages, as needed, to the subkernel. The Beaker kernel inspects the messages that pass through it and may take extra actions, as needed. This allows you to define custom message types that result in custom behavior, have extra behavior be triggered by normal actions, or modify the request and/or response messages on the fly.

When it is first initialized, the Beaker kernel will start a subkernel using its defaults (usually Python3). If you check the existing kernels in the Jupyter service, will see both kernels listed. At this point, you can use Beaker as a naive kernel and all regular messages will be sent to the subkernel as if you were connected directly to the subkernel itself. To really get started with Beaker, you need to set a context.

### Contexts

Beaker works best when used within a particular context. At a high level, a context has three parts: What language you're working in, what problem space are you working within, and any particular items/objects you are working on.

When connecting to Beaker, usually the first action following connecting is to set the context.

#### Setting a Beaker context will do the following:

* Change the subkernel language if needed (destroying the current subkernel and creating a new one)
* Set the LLM prompt for the context
* Run initialization code in the subkernel to pre-import libraries and load objects/instances (optional)
* Register any context-specific custom message handlers (optional)
* Register any "post-execute" actions to run after a notebook cell is executed (optional)

** Currently, setting a context is the only way to change the language of the subkernel.

#### Setting the context

You set a context by sending a custom message to the beaker kernel. The message should have the following format:

`msg_type`: `context_setup_request`<br/>
`msg_payload`:<br/>
```json
{
"language": "<subkernel name>",
"context": "<context name>",
"context_info": {"json payload of any settings/info required to start the context"}
}
```

The list of available languages and contexts depends on what has been installed. The `context_info` payload is dependent on the particular context chosen.

The Beaker service provides an end-point that will return a JSON payload listing the installed contexts and the languages available for each context to allow discovery.

This endpoint is found at: `http://{jupyter_url}/contexts`, usually, `http://localhost:8888/contexts`

### Components of contexts

#### Toolsets

Toolsets are, primarily, set of tools provided to the LLM that allows the LLM to interact with both the subkernel environment and the front-end using the [Archytas ReAct framework](https://github.com/jataware/archytas). Details for how toolsets work and should be defined can be found in the [Archytas documentation](https://github.com/jataware/archytas).


#### Codesets

Codesets define snippets of code that run in a subkernel. These can often be thought of as analogous to functions, although it can be important to keep in mind that these are executed directly within the subkernel environment exactly as if the codeset content were executed within a notebook code cell.

Codesets are separated by context and language, allowing for analogous behavior across different subkernel languages for each configured contexts.

Each codeset is defined using the [Jinja templating language](https://jinja.palletsprojects.com/en/3.1.x/), allowing for dynamic variation of the code based on the current state of the context/subkernel environment.

Code from a codeset can be rendered using the `get_code()` method on an context object.
Once the template is rendered in to properly formatted code, it can be executed in the subkernel using the `execute()` or `evaluate()` methods on the context.


#### Subkernels

The subkernel files within the context directory are required to define some common behaviours and provide a function for Beaker to behave consistently and properly parse the responses from subkernel executions.

#TODO: Move subkernels out of context?


## Install / setup

### Docker



### python (local)

Normal installation:
```bash
# Requires [hatch](https://github.com/pypa/hatch)
$ pip install hatch # If needed
$ pip install .
pip install beaker-kernel
```

Development installation
```bash
$ pip install -e .
```


### Jupyter kernel

The Beaker Kernel should be automatically installed if Beaker is installed
using the method above.
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.

If the kernel is not installed, or you want to install the kernel manually
ensure that the `beaker_kernel` package is accessible in your environmnet
and then simply copy or symlink the `kernel.json` file to one of the
directories defined in the following document inside a unique directory:
Now that you've got things installed and set up, just simply run:

https://jupyter-client.readthedocs.io/en/stable/kernels.html#kernel-specs


For example:
```bash
$ cp -r beaker_kernel/kernel.json /usr/share/jupyter/kernels/beaker/kernel.json
```

Once the directory exists and the jupyter service is restarted the kernel
should be available for selection.


## Dev setup

This package is bundled with a basic development UI for development and testing.

You will need to update the .env file with your OpenAI/GPT API key to use the
LLM.

Once you have set up the environment and added your keys you can start the dev
server by 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.
beaker notebook
```

Your notebook server will start up and Beaker will be ready to use at [`localhost:8888`](http://localhost:8888).

## Differences from vanilla Jupyter
## Quick demo

This setup uses mostly stock Jupyter services as provided in the Jupyter Python
packages, with minor differences.
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.

The entry point of the docker file runs the file main.py which
starts a JupyterLab Server App. The key differences here
are:
1. This service does not run any front-end outside of dev mode and only provides
API and websocket access as this service is expected to connect to a custom
interface.
2. Some security settings are loosened to allow access through the a custom
interface and allow Beaker to access the Jupyter service API to manage
subkernels:
1. `allow_orgin` rule loosened as UI and Kernel likely do not share the same
domain.
2. `disable_check_xsrf` set so as the Jupyter API does not require xsrf
checks, allowing Beaker to make calls directly
<div align="center">
<a href="https://www.youtube.com/watch?v=AP9LT_cxjzY" target="_blank">
<img src="docs/assets/beaker-movie-3x-optimized-higherres.gif" alt="Beaker demo" width="90%">
</a>
<br/>
Watch original video on <a href="https://www.youtube.com/watch?v=AP9LT_cxjzY">Youtube here</a>.
</div>

These security settings will be reviewed in the future in an attempt to tighten
the modifications.
## Want to know more?

More information can be found in [the official docs](https://jataware.github.io/beaker-kernel/).
There is a lot more to Beaker than what we've covered here, so we've put together more detailed [docs](https://jataware.github.io/beaker-kernel/) that cover how to customize and extend Beaker in more detail. These include information on how to build your own custom contexts, toolsets, and subkernels to make Beaker meet your specific needs and usecases. It also gets into the basics of using the Beaker TypeScript SDK to build your own custom front-ends around Beaker.
1 change: 1 addition & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
_site
Gemfile.lock
142 changes: 0 additions & 142 deletions docs/Gemfile.lock

This file was deleted.

7 changes: 7 additions & 0 deletions docs/_sass/custom/custom.scss
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
pre.highlight {
white-space: pre-line;
}

iframe.youtube {
width: 100%;
aspect-ratio: 10/7;
height: auto;
z-index: 5;
}
Binary file added docs/assets/beaker-custom-context.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/beaker-getting-started-setup-3x.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/beaker-movie-3x-optimized.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 9 additions & 11 deletions docs/contexts.md
Original file line number Diff line number Diff line change
@@ -8,12 +8,12 @@ has_children: true

# Contexts

Beaker works best when used within a particular context. At a high level, a
context consist of the following:
Beaker can be totally customized by creating bespoke, use case driven contexts.
At a high level, a context consist of the following:
* A subkernel which acts as your notebook environment.
* Selecting a subkernel also sets the language you will work in and what
libraries you have access to.
* Knowledge regarding the items/objects that you are working on in, either in
libraries you have access to. Currently Beaker supports `Python`, `R`, and `Julia`.
* Knowledge of the items/objects that you are working on in, either in
the subkernel or via the context tool or LLM Agent.
* The context can automatically pre-load items at startup that you are
planning to work on.
@@ -28,19 +28,18 @@ the subkernel or via the context tool or LLM Agent.
* An LLM Agent that accepts human languge requests and acts on your behalf.
* Uses all of the tools available to it, and the knowledge contained in the
context to make decisions on how to best satisfy your request.
* Has its own set of ReAct tools to allow it to query the subkernel, the
* Has its own set of chain-of-thought style tools developed in the [Archytas framework](https://github.com/jataware/archytas) to allow it to query the subkernel, the
internet, or custom defined services to fetch the information it needs to
complete the request.
* Is able to answer questions, generate code to accomplish a request in a new
code cell, or just execute code in the subkernel to update the state, and
more.


When connecting to Beaker, usually the first action following connecting is to
set the context.

## Setting a Beaker context will do the following:

To use a custom context, it must be set once the user has loaded the notebook. Checkout the [getting started guide](getting_started.md) for more information on how to load a custom context. Once the context is set, it will do the following:

* Change the subkernel, recreating if needed (destroying the current subkernel
and creating a new one)
* Set the LLM prompt so that it is appropriate for the context
@@ -50,13 +49,12 @@ load objects/instances (optional)
* Register any "post-execute" actions to run after a notebook cell is executed
(optional)

** Currently, setting a context is the only way to change the language of the
> **Note**: currently, setting a context is the only way to change the language of the
subkernel.

### Setting the context

You set a context by sending a custom message to the beaker kernel. The message
should have the following format:
Contexts can be set by external applications (such as a custom frontend) by sending a custom message to the beaker kernel. The message should have the following format:

`msg_type`: `context_setup_request`<br/>
`msg_payload`:<br/>
30 changes: 26 additions & 4 deletions docs/contexts_context.md
Original file line number Diff line number Diff line change
@@ -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.

<div align="center">
<img src="assets/beaker-custom-context.gif" alt="Custom context creation" width="90%">
</div>

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.
4 changes: 3 additions & 1 deletion docs/debugging.md
Original file line number Diff line number Diff line change
@@ -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.
59 changes: 58 additions & 1 deletion docs/getting_started.md
Original file line number Diff line number Diff line change
@@ -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.

<div align="center">
<img src="assets/beaker-getting-started-setup-3x.gif" alt="Setup" width="90%">
</div>


## 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.

<div align="center">
<img src="assets/beaker-getting-started-keyboard-shortcuts-3x.gif" alt="Keyboard shortcuts" width="90%">
</div>

## 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.

<div align="center">
<img src="assets/beaker-getting-started-file-browser-3x.gif" alt="File browser" width="90%">
</div>

## 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.

<div align="center">
<img src="assets/beaker-getting-started-saving-notebook-3x.gif" alt="Saving notebook" width="90%">
</div>

## 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.

<div align="center">
<img src="assets/beaker-getting-started-navigation-3x.gif" alt="Navigation" width="90%">
</div>

## 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.

<div align="center">
<img src="assets/beaker-getting-started-setting-context-3x.gif" alt="Setting context" width="90%">
</div>
71 changes: 31 additions & 40 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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.

<div align="center">
<iframe class="youtube" width="560" height="315" src="https://www.youtube.com/embed/AP9LT_cxjzY?si=8y-WqQzL0kUGwQIP" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div>


## 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.
56 changes: 17 additions & 39 deletions docs/install.md
Original file line number Diff line number Diff line change
@@ -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.