Warning

This repository has been archived and is no longer actively maintained or updated. It is provided here for historical reference and may contain outdated or unsupported code. Users are encouraged to fork or adapt the contents as needed, but please note that no further updates, bug fixes, or security patches will be applied by the original maintainers.

Bee API Python experience

Interact with bee-api through OpenAI Python SDK

⚠️ COMPATIBILITY DISCLAIMER ⚠️ The bee-api is designed to overlap with OpenAI API to a degree that is sufficitent for most use-cases, however some types and operations are not 100% compatible, see the section on OpenAI Compatibility below. The examples provided in this repository are regularly tested to be working, however we will never guarantee full compatibility with OpenAI. Please create an issue if you stumbled upon non-compatible behavior that is blocking you.

Quick Start

Installation 🔧

We are using purely OpenAI SDK, so the only required package is openai.

pip install openai

Environment variables ♻️

Make sure to have the following environment variables configured, see example.env:

BEE_API=http://localhost:4000
BEE_API_KEY=sk-proj-testkey
# This is required to prevent some pydantic serialization errors
DEFER_PYDANTIC_BUILD=false

Basic usage 🧑‍💻

importosfromopenaiimportOpenAI# Instantiate OpenAI client with Bee credentials from envclient=OpenAI(base_url=f'{os.getenv("BEE_API")}/v1', api_key=os.getenv("BEE_API_KEY"))
# Create assistantassistant=client.beta.assistants.create(
model="meta-llama/llama-3-1-70b-instruct", tools=[{"type": "code_interpreter"}]
)
# Create a thread with user messagequestion="What is the unicode character U+1F41D? Create a haiku about it."thread=client.beta.threads.create(messages=[{"role": "user", "content": question}])
# Create a run and wait for completionrun=client.beta.threads.runs.create_and_poll(thread_id=thread.id, assistant_id=assistant.id)
assertrun.status=="completed"# List messages and get an answermessages=client.beta.threads.messages.list(thread_id=thread.id)
print("Answer:", messages.data[0].content[0].text.value)

Run examples 🏃‍♀️

If you want to run the examples in this repository, install all dependencies using poetry.

# Install dependencies
poetry install

Set up a local bee-stack

git clone git@github.com:i-am-bee/bee-stack.git
cd bee-stack
./bee-stack.sh setup

Create a correct .env file.

# Create .env file
cp example.env .env
# Insert your API key
open .env

Run examples through poetry

poetry run python -m examples.basic_usage

OpenAI Compatibility 🧭

Here are the important differences from the official OpenAI SDK.

Supported OpenAI APIs ✅

fromopenaiimportOpenAIclient: OpenAI= ...
# OpenAI# Assistantsclient.beta.assistantsclient.beta.threadsclient.beta.threads.messagesclient.beta.threads.runsclient.beta.threads.runs.stepsclient.beta.threads.runs.stream# early stage event compatibilityclient.beta.vector_storesclient.beta.vector_stores.files## Not supported:# client.beta.vector_stores.file_batches# Filesclient.files

Bee API extensions 🐝

Extensions can be called using the low-level OpenAI client methods (get, post, put, delete). See the definition of a custom tool in examples/custom_tool.py as an example.

fromopenaiimportOpenAI, BaseModelclient: OpenAI= ...
# Toolsclient.get('/tools', cast_to=BaseModel) # list toolsclient.post('/tools', cast_to=BaseModel) # create toolclient.post('/tools/:tool_id', cast_to=BaseModel) # update toolclient.delete('/tools/:tool_id', cast_to=BaseModel) # delete tool# Observeclient.get('/threads/:thread_id/runs/:run_id/trace') # Get trace ID for a run

Bee observe 🎥

Observe API module is designed to provide full trace of everything that happened during a run. You can obtain the trace using a special /observe endpoint, here is a brief example, for full code see examples/download_trace.py:

importosfromopenaiimportOpenAI, BaseModel# Normal bee clientbee_client=OpenAI(base_url=f'{os.getenv("BEE_API")}/v1', api_key=os.getenv("BEE_API_KEY"))
thread= ...
run= ...
trace_info=bee_client.get(f"/threads/{thread.id}/runs/{run.id}/trace", cast_to=BaseModel)
# (!) Note different base_urlobserve_client=OpenAI(base_url=f'{os.getenv("BEE_API")}/observe', api_key=os.getenv("BEE_API_KEY"))
# Get traceparams= {"include_tree": True, "include_mlflow": True}
trace=observe_client.get(f"/trace/{trace_info.id}", options={"params": params}, cast_to=BaseModel)

OpenAI documentation 📄

Use the official OpenAI documentation with caution (see caveats below), here are links to the relevant topics:

• Assistants
• API reference

⚠️ Caveats ⚠️

• streaming events are not fully compatible yet, the "With streaming" portions of OpenAI documentation will not work as expected (for example in file search)
• some features are not implemented:
  • vector store file batches - client.beta.vector_stores.file_batches
  • adding message attachment to file_search without previously embedding the file in a thread vector store, see examples/vector_store.py
  • ... and more
• some type unions are extended so the data returned does not match the original openai models:
  • you may see pydantic warningns during serialization, you can avoid this by using warnings="none" when dumping a model, for example assistant.model_dump(warnings="none")
  • you must set the DEFER_PYDANTIC_BUILD=false environment variable before all imports, if you see an error similar to 'MockValSer' object cannot be converted to 'SchemaSerializer', you are probably missing this configuration

Contributing

This is an open-source project and we ❤️ contributions.

If you'd like to contribute to Bee, please take a look at our contribution guidelines.