Metadata-Version: 2.4
Name: bumblehive
Version: 0.1.0
Summary: An agent runtime designed for tool-driven loop engineering.
Project-URL: Homepage, https://github.com/wxhcore/bumblehive
Project-URL: Repository, https://github.com/wxhcore/bumblehive
Project-URL: Issues, https://github.com/wxhcore/bumblehive/issues
Author: wxhcore
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,agent-loop,ai,llm,mcp,tool-calling
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: fastmcp<4.0,>=3.0
Requires-Dist: jsonschema<5.0,>=4.0
Requires-Dist: mcp<2.0,>=1.26
Requires-Dist: openai<3.0,>=2.0
Requires-Dist: openpyxl<4.0,>=3.1
Requires-Dist: pymupdf<2.0,>=1.25
Requires-Dist: python-docx<2.0,>=1.1
Requires-Dist: python-pptx<2.0,>=1.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<16.0,>=14.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio<2.0,>=0.24; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Description-Content-Type: text/markdown

# BumbleHive

An agent runtime designed for tool-driven loop engineering.

BumbleHive is a lightweight Python library for building AI agents around a clear execution loop: build context, call the model, execute tools, observe events, and continue until a final result is produced.

## Highlights

- Tool-driven agent loop with built-in and MCP-backed tools.
- Streaming lifecycle events for model deltas, tool calls, errors, and final results.
- Session-aware runtime with isolated history and concurrency control.
- Modular Python APIs for configuration, providers, tools, skills, and observability.

## Quick Start

```python
import bumblehive


runtime = bumblehive.from_config(
    {
        "provider": {"model": "gpt-5.4"},
        "agent": {"tool_names": []},
    }
)

result = await runtime.run("Hello", session_id="user:123")
print(result.final_content)
```

## Streaming

```python
async for event in runtime.stream("Hello", session_id="user:123"):
    print(event.kind, event.session_id, event.payload)
```

## Local Development

The base requirements are Python 3.11+ and Node.js 20.19+/22.12+. A dedicated Conda environment is recommended:

```bash
conda create -n bumblehive_env python=3.11 -y
conda activate bumblehive_env
npm run setup
npm run doctor
```

`npm run setup` uses the currently active Python interpreter, does not depend on a fixed Conda path, and installs the SDK dependencies, Server, WebUI, and desktop dependencies together.

For daily development:

```bash
conda activate bumblehive_env
npm run dev
```

This starts the Server on `127.0.0.1:18421` and the WebUI on `127.0.0.1:1420`. Use `npm run dev:server` or `npm run dev:web` to run one component, and `npm test` for the Python test suite.

### Desktop

macOS additionally requires Rust and Xcode Command Line Tools. Windows additionally requires the Rust MSVC toolchain, WebView2, and Microsoft C++ Build Tools with the Desktop development with C++ workload.

On a clean checkout, build the generated desktop sidecar before running the full desktop environment check:

```bash
npm run build:sidecar
npm run doctor:desktop
```

Then start development or create a platform-specific installer:

```bash
npm run dev:desktop
npm run build:mac
npm run build:win
```

The sidecar is a generated artifact and is not created by `npm run setup`. `dev:desktop` and both packaging commands rebuild it automatically with the current Python environment. Use `build:mac` only on macOS and `build:win` only on Windows.
