配置与模型 Provider

使用 RuntimeArguments 创建简单配置，BumblehiveConfig 保存分层配置。单次 config 覆盖会深度合并，不会修改基础配置。MCP 连接与 Skills 目录不能在单次调用中更换。

模型配置指南 · 自定义 Provider

常用接口

接口	用途
RuntimeArguments	常用扁平配置，适合在 Python 中直接创建。
BumblehiveConfig	分层配置，支持字典与 JSON。
GenerationConfig	温度、输出预算、推理参数和供应商扩展字段；可用性取决于模型。
ModelProvider	自定义 Provider 的基类，实现 generate()，需要时实现流式生成和关闭。

应用配置

常用扁平配置，适合在 Python 中直接创建。

RuntimeArguments dataclass

Convenient flat arguments for constructing a Bumblehive runtime.

to_config

to_config() -> BumblehiveConfig

Convert flat runtime arguments into structured config.

分层配置，支持字典与 JSON。

BumblehiveConfig dataclass

Top-level runtime configuration.

from_dict classmethod

from_dict(data: Mapping[str, Any] | None) -> BumblehiveConfig

Build a config object from JSON-like dictionary data.

from_json_file classmethod

from_json_file(path: str | Path) -> BumblehiveConfig

Load a config object from a JSON file.

from_mapping classmethod

from_mapping(data: Mapping[str, Any] | None) -> BumblehiveConfig

Build a config object from JSON-like mapping data.

to_dict

to_dict() -> dict[str, Any]

Return this config as JSON-like dictionary data.

to_json_file

to_json_file(path: str | Path) -> None

Write this config to a JSON file.

模型名、密钥、Base URL 与 Provider 类型。

ProviderConfig dataclass

Provider settings used to build the default runtime provider.

指令、动态上下文和能力选择。

AgentConfig dataclass

Agent defaults applied to each runtime turn.

工作目录、上下文预算、迭代次数和文件路径规则。

RuntimeConfig dataclass

Per-runtime defaults applied to each turn.

配置入口接受的输入类型。

ConfigInput module-attribute

ConfigInput = str | Path | Mapping[str, Any] | BumblehiveConfig | RuntimeArguments | None

将配置输入转换成配置对象。

load_config

load_config(config: ConfigInput = None) -> BumblehiveConfig

Normalize supported config inputs into a BumblehiveConfig.

从 JSON 文件读取配置。

load_json_config

load_json_config(path: str | Path) -> BumblehiveConfig

Load a BumblehiveConfig from a JSON file.

生成参数

温度、输出预算、推理参数和供应商扩展字段；可用性取决于模型。

GenerationConfig dataclass

Provider-agnostic generation settings for one model request.

effective_max_completion_tokens property

effective_max_completion_tokens: int

Return the effective positive completion-token limit.

模型接入

自定义 Provider 的基类，实现 generate()，需要时实现流式生成和关闭。

ModelProvider

Bases: ABC

Base interface for model providers.

generate abstractmethod async

generate(request: ModelRequest) -> ModelResponse

Generate one non-streaming model response.

generate_stream async

generate_stream(request: ModelRequest, *, callbacks: ModelStreamCallbacks | None = None) -> ModelResponse

Generate one response while reporting provider-native deltas.

generate_with_retry async

generate_with_retry(request: ModelRequest, *, retry: RetryConfig | None = None) -> ModelResponse

Return one model response, retrying recoverable provider errors.

The default implementation is intentionally provider-agnostic: concrete providers classify errors on ModelResponse.error.recoverable and may attach retry_after. This wrapper only decides whether and when to repeat the same request.

generate_stream_with_retry async

generate_stream_with_retry(request: ModelRequest, *, callbacks: ModelStreamCallbacks | None = None, retry: RetryConfig | None = None) -> ModelResponse

Return one streaming model response, retrying before deltas escape.

close async

close() -> None

Release provider-owned resources.

高层 Runtime 当前使用的 Chat Completions 兼容实现。

OpenAIChatCompletionsProvider

Bases: ModelProvider

Provider for OpenAI-compatible Chat Completions APIs.

close async

close() -> None

Close the cached OpenAI SDK client, if it was created.

按连接配置缓存 Provider，关闭时释放连接。

ProviderManager

Runtime-scoped cache of providers by connection settings.

Providers with different API keys or base URLs may be used concurrently. Cached providers remain open until the manager is closed.

close async

close() -> None

Close and forget every cached provider.

发送给模型的统一请求。

ModelRequest dataclass

A single model request after context construction.

模型回答、工具请求、用量和结构化错误。

ModelResponse dataclass

Provider-normalized model output.

模型流式内容的回调接口。

ModelStreamCallbacks dataclass

Callbacks used by providers to report native streaming deltas.

可恢复模型请求的重试设置。

RetryConfig dataclass

Provider-agnostic retry settings for recoverable model errors.