{"id":20471915,"url":"https://github.com/i-am-bee/bee-python-sdk","last_synced_at":"2025-05-09T00:32:23.923Z","repository":{"id":261315953,"uuid":"869951892","full_name":"i-am-bee/bee-python-sdk","owner":"i-am-bee","description":"Interacting with bee-api through OpenAI Python SDK","archived":true,"fork":false,"pushed_at":"2025-03-18T13:51:07.000Z","size":93,"stargazers_count":25,"open_issues_count":0,"forks_count":2,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-27T02:21:13.796Z","etag":null,"topics":["python"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/i-am-bee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-09T07:27:45.000Z","updated_at":"2025-03-18T13:52:02.000Z","dependencies_parsed_at":"2024-11-05T22:25:47.086Z","dependency_job_id":"990df09b-83a6-45d5-aa00-7028c70c9f44","html_url":"https://github.com/i-am-bee/bee-python-sdk","commit_stats":null,"previous_names":["i-am-bee/bee-python-sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-am-bee%2Fbee-python-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-am-bee%2Fbee-python-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-am-bee%2Fbee-python-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-am-bee%2Fbee-python-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/i-am-bee","download_url":"https://codeload.github.com/i-am-bee/bee-python-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253171129,"owners_count":21865275,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python"],"created_at":"2024-11-15T14:17:36.332Z","updated_at":"2025-05-09T00:32:23.913Z","avatar_url":"https://github.com/i-am-bee.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!WARNING]  \n\u003e \n\u003e 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.\n\n# Bee API Python experience\n\nInteract with bee-api through **OpenAI Python SDK**\n\n\u003e **⚠️ COMPATIBILITY DISCLAIMER ⚠️**\n\u003e The bee-api is designed to overlap with OpenAI API\n\u003e to a degree that is sufficitent for most use-cases, however some types and operations are not 100%\n\u003e compatible, see the section on [OpenAI Compatibility](#openai-compatibility-) below. The examples provided in this\n\u003e repository are regularly tested to be working, however we will never guarantee full compatibility with OpenAI.\n\u003e Please create an issue if you stumbled upon non-compatible behavior that is blocking you.\n\n## Quick Start\n\n### Installation 🔧\n\nWe are using purely OpenAI SDK, so the only required package is `openai`.\n\n```shell\npip install openai\n```\n\n### Environment variables ♻️\n\nMake sure to have the following environment variables configured,\nsee [example.env](example.env):\n\n```\nBEE_API=http://localhost:4000\nBEE_API_KEY=sk-proj-testkey\n\n# This is required to prevent some pydantic serialization errors\nDEFER_PYDANTIC_BUILD=false\n```\n\n### Basic usage 🧑‍💻\n\n```python\nimport os\nfrom openai import OpenAI\n\n# Instantiate OpenAI client with Bee credentials from env\nclient = OpenAI(base_url=f'{os.getenv(\"BEE_API\")}/v1', api_key=os.getenv(\"BEE_API_KEY\"))\n\n# Create assistant\nassistant = client.beta.assistants.create(\n    model=\"meta-llama/llama-3-1-70b-instruct\", tools=[{\"type\": \"code_interpreter\"}]\n)\n\n# Create a thread with user message\nquestion = \"What is the unicode character U+1F41D? Create a haiku about it.\"\nthread = client.beta.threads.create(messages=[{\"role\": \"user\", \"content\": question}])\n\n# Create a run and wait for completion\nrun = client.beta.threads.runs.create_and_poll(thread_id=thread.id, assistant_id=assistant.id)\nassert run.status == \"completed\"\n\n# List messages and get an answer\nmessages = client.beta.threads.messages.list(thread_id=thread.id)\nprint(\"Answer:\", messages.data[0].content[0].text.value)\n```\n\n## Run examples 🏃‍♀️\n\nIf you want to run the examples in this repository, install all dependencies\nusing [poetry](https://python-poetry.org/).\n\n```shell\n# Install dependencies\npoetry install\n```\n\nSet up a local bee-stack\n\n```shell\ngit clone git@github.com:i-am-bee/bee-stack.git\ncd bee-stack\n./bee-stack.sh setup\n```\n\nCreate a correct `.env` file.\n\n```shell\n# Create .env file\ncp example.env .env\n\n# Insert your API key\nopen .env\n```\n\nRun examples through poetry\n\n```shell\npoetry run python -m examples.basic_usage\n```\n\n## OpenAI Compatibility 🧭\nHere are the important differences from the official [OpenAI SDK](https://github.com/openai/openai-python).\n\n### Supported OpenAI APIs ✅\n\n```python\nfrom openai import OpenAI\n\nclient: OpenAI = ...\n\n# OpenAI\n# Assistants\nclient.beta.assistants\nclient.beta.threads\nclient.beta.threads.messages\nclient.beta.threads.runs\nclient.beta.threads.runs.steps\nclient.beta.threads.runs.stream  # early stage event compatibility\nclient.beta.vector_stores\nclient.beta.vector_stores.files\n\n## Not supported:\n# client.beta.vector_stores.file_batches\n\n# Files\nclient.files\n```\n\n### Bee API extensions 🐝\n\nExtensions can be called using the low-level OpenAI client methods (get, post, put, delete). See the\ndefinition of a custom tool in [examples/custom_tool.py](examples/custom_tool.py) as an example.\n\n```python\nfrom openai import OpenAI, BaseModel\n\nclient: OpenAI = ...\n\n# Tools\nclient.get('/tools', cast_to=BaseModel)  # list tools\nclient.post('/tools', cast_to=BaseModel)  # create tool\nclient.post('/tools/:tool_id', cast_to=BaseModel)  # update tool\nclient.delete('/tools/:tool_id', cast_to=BaseModel)  # delete tool\n\n# Observe\nclient.get('/threads/:thread_id/runs/:run_id/trace')  # Get trace ID for a run\n```\n\n### Bee observe 🎥\n\nObserve API module is designed to provide full trace of everything that happened during a run.\nYou can obtain the trace using a special `/observe` endpoint, here is a brief example, for full code\nsee [examples/download_trace.py](examples/download_trace.py):\n\n```python\nimport os\nfrom openai import OpenAI, BaseModel\n\n# Normal bee client\nbee_client = OpenAI(base_url=f'{os.getenv(\"BEE_API\")}/v1', api_key=os.getenv(\"BEE_API_KEY\"))\nthread = ...\nrun = ...\ntrace_info = bee_client.get(f\"/threads/{thread.id}/runs/{run.id}/trace\", cast_to=BaseModel)\n\n# (!) Note different base_url\nobserve_client = OpenAI(base_url=f'{os.getenv(\"BEE_API\")}/observe', api_key=os.getenv(\"BEE_API_KEY\"))\n\n# Get trace\nparams = {\"include_tree\": True, \"include_mlflow\": True}\ntrace = observe_client.get(f\"/trace/{trace_info.id}\", options={\"params\": params}, cast_to=BaseModel)\n```\n\n### OpenAI documentation 📄\n\nUse the official OpenAI documentation with caution (see **caveats** below), here are links to the relevant topics:\n\n- [Assistants](https://platform.openai.com/docs/assistants/overview)\n- [API reference](https://platform.openai.com/docs/api-reference/assistants)\n\n### ⚠️ Caveats ⚠️\n\n- *streaming* events are not fully compatible yet, the \"With streaming\" portions of OpenAI documentation will not work\n  as expected (for example in\n  [file search](https://platform.openai.com/docs/assistants/tools/file-search/step-5-create-a-run-and-check-the-output))\n- *some features are not implemented*:\n    - vector store file batches - `client.beta.vector_stores.file_batches`\n    - adding message attachment to `file_search` without previously embedding the file in a thread vector store,\n      see [examples/vector_store.py](examples/vector_store.py)\n    - ... and more\n- *some type unions are extended* so the data returned does not match the original openai models:\n    - you may see pydantic warningns during serialization, you can avoid this by using `warnings=\"none\"` when dumping a\n      model, for example `assistant.model_dump(warnings=\"none\")`\n    - you must set the `DEFER_PYDANTIC_BUILD=false` environment variable before all imports, if you see an error similar\n      to ['MockValSer' object cannot be converted to 'SchemaSerializer'](https://github.com/pydantic/pydantic/discussions/7710),\n      you are probably missing this configuration\n\n# Contributing\nThis is an open-source project and we ❤️ contributions.\n\nIf you'd like to contribute to Bee, please take a look at our [contribution guidelines](./CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi-am-bee%2Fbee-python-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fi-am-bee%2Fbee-python-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi-am-bee%2Fbee-python-sdk/lists"}