https://github.com/i-am-bee/bee-python-sdk
Interacting with bee-api through OpenAI Python SDK
https://github.com/i-am-bee/bee-python-sdk
python
Last synced: 2 months ago
JSON representation
Interacting with bee-api through OpenAI Python SDK
- Host: GitHub
- URL: https://github.com/i-am-bee/bee-python-sdk
- Owner: i-am-bee
- License: apache-2.0
- Archived: true
- Created: 2024-10-09T07:27:45.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-03-18T13:51:07.000Z (4 months ago)
- Last Synced: 2025-03-27T02:21:13.796Z (4 months ago)
- Topics: python
- Language: Shell
- Size: 90.8 KB
- Stars: 25
- Watchers: 9
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
> [!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](#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`.
```shell
pip install openai
```
### Environment variables ♻️
Make sure to have the following environment variables configured,
see [example.env](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 🧑💻
```python
import os
from openai import OpenAI
# Instantiate OpenAI client with Bee credentials from env
client = OpenAI(base_url=f'{os.getenv("BEE_API")}/v1', api_key=os.getenv("BEE_API_KEY"))
# Create assistant
assistant = client.beta.assistants.create(
model="meta-llama/llama-3-1-70b-instruct", tools=[{"type": "code_interpreter"}]
)
# Create a thread with user message
question = "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 completion
run = client.beta.threads.runs.create_and_poll(thread_id=thread.id, assistant_id=assistant.id)
assert run.status == "completed"
# List messages and get an answer
messages = 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](https://python-poetry.org/).
```shell
# Install dependencies
poetry install
```
Set up a local bee-stack
```shell
git clone [email protected]:i-am-bee/bee-stack.git
cd bee-stack
./bee-stack.sh setup
```
Create a correct `.env` file.
```shell
# Create .env file
cp example.env .env
# Insert your API key
open .env
```
Run examples through poetry
```shell
poetry run python -m examples.basic_usage
```
## OpenAI Compatibility 🧭
Here are the important differences from the official [OpenAI SDK](https://github.com/openai/openai-python).
### Supported OpenAI APIs ✅
```python
from openai import OpenAI
client: OpenAI = ...
# OpenAI
# Assistants
client.beta.assistants
client.beta.threads
client.beta.threads.messages
client.beta.threads.runs
client.beta.threads.runs.steps
client.beta.threads.runs.stream # early stage event compatibility
client.beta.vector_stores
client.beta.vector_stores.files
## Not supported:
# client.beta.vector_stores.file_batches
# Files
client.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](examples/custom_tool.py) as an example.
```python
from openai import OpenAI, BaseModel
client: OpenAI = ...
# Tools
client.get('/tools', cast_to=BaseModel) # list tools
client.post('/tools', cast_to=BaseModel) # create tool
client.post('/tools/:tool_id', cast_to=BaseModel) # update tool
client.delete('/tools/:tool_id', cast_to=BaseModel) # delete tool
# Observe
client.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](examples/download_trace.py):
```python
import os
from openai import OpenAI, BaseModel
# Normal bee client
bee_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_url
observe_client = OpenAI(base_url=f'{os.getenv("BEE_API")}/observe', api_key=os.getenv("BEE_API_KEY"))
# Get trace
params = {"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](https://platform.openai.com/docs/assistants/overview)
- [API reference](https://platform.openai.com/docs/api-reference/assistants)
### ⚠️ 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](https://platform.openai.com/docs/assistants/tools/file-search/step-5-create-a-run-and-check-the-output))
- *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](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'](https://github.com/pydantic/pydantic/discussions/7710),
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](./CONTRIBUTING.md).