Metadata-Version: 2.4
Name: heybee
Version: 0.9.0
Summary: Python SDK for automating and integrating with the HeyBee controller.
Project-URL: Homepage, https://heybee.app
Project-URL: Documentation, https://docs.heybee.app
Author: HeyBee
License: MIT
License-File: LICENSE
Keywords: benchmarking,evaluations,heybee,outputs,variants
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: attrs>=22.2
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: pydantic<3,>=2.8
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.11; extra == 'dev'
Requires-Dist: openapi-python-client==0.29.0; (python_version >= '3.11') and extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# heybee

Python SDK for automating and integrating with the HeyBee controller.

## Install

```bash
pip install heybee
```

## Quick start

The public API supports the product language users see in the app:

- evaluation / output / variant / prompt
- `client.evaluations.create()`
- `client.outputs.upload()`
- `client.voting_links.create()`
- `client.results.get()`
- `client.insights.parameters()`

```python
from heybee import HeyBee

client = HeyBee(api_key="hb_...")

evaluation = client.evaluations.create(
    name="SDXL sampler benchmark",
    evaluation_type="image",
    objective="benchmark",
    prompt_field="prompt",
    variant_definitions=[
        {"name": "sampler", "type": "categorical", "values": ["euler", "dpmpp_2m"]},
        {"name": "steps", "type": "continuous", "min_value": 10, "max_value": 60},
    ],
)

uploaded_outputs = client.outputs.upload(
    evaluation_id=evaluation.id,
    outputs=[
        {
            "path": "outputs/cat-euler.png",
            "prompt": "A cinematic photo of a cat",
            "variant_key": "sdxl-euler",
            "variant_label": "SDXL Euler",
            "parameters": {"sampler": "euler", "steps": 30},
        },
        {
            "path": "outputs/cat-dpmpp.png",
            "prompt": "A cinematic photo of a cat",
            "variant_key": "sdxl-dpmpp",
            "variant_label": "SDXL DPM++ 2M",
            "parameters": {"sampler": "dpmpp_2m", "steps": 30},
        },
    ],
    spend_limit=500,
)

voting_link = client.voting_links.create(
    evaluation_id=evaluation.id,
    name="SDXL round 1",
    max_participants=200,
)

print(evaluation.id)
print(voting_link.voting_url if voting_link else "No voting link created")
```

Compatibility names remain supported for existing scripts:

```python
from heybee import ExperimentSpec, HeyBee, ParameterDefinition, SampleInput

client = HeyBee(api_key="hb_...")

result = client.publish.experiment(
    experiment=ExperimentSpec(
        name="SDXL sampler benchmark",
        experiment_type="image",
        kind="advanced",
        objective="benchmark",
        anchor_field="prompt",
        parameter_schema=[
            ParameterDefinition(name="sampler", type="categorical", values=["euler", "dpmpp_2m"]),
            ParameterDefinition(name="steps", type="continuous", min_value=10, max_value=60),
        ],
    ),
    samples=[
        SampleInput(
            path="outputs/cat-euler.png",
            anchor_value="A cinematic photo of a cat",
            candidate_key="sdxl-euler",
            candidate_label="SDXL Euler",
            parameters={"sampler": "euler", "steps": 30},
        ),
        SampleInput(
            path="outputs/cat-dpmpp.png",
            anchor_value="A cinematic photo of a cat",
            candidate_key="sdxl-dpmpp",
            candidate_label="SDXL DPM++ 2M",
            parameters={"sampler": "dpmpp_2m", "steps": 30},
        ),
    ],
    fund_comparisons=500,
)

print(result.experiment.id)
print(result.voting.voting_url if result.voting else "No voting link created")
```

The compatibility snippet maps current SDK names to the same product concepts:
experiments are evaluations, samples are outputs, anchors are prompts, and
candidates are variants. Owner-paid credits are authoritative: counted votes
spend from the evaluation credit owner's account, `spend_limit` maps to the
evaluation spend limit, and `fund_comparisons` / `fund()` are compatibility APIs
for that spend-limit behavior rather than a separate comparison pool.

## Design goals

- Sync-first API for scripts and notebooks
- API-key, JWT bearer, and anonymous seat-token route support
- A stable, product-facing public surface (evaluations, outputs, voting links, results, insights) with wider controller route coverage available for advanced use
- Typed models for stable workflows plus dictionary payloads for broad route parity
- Backward-compatible experiment/sample naming while product-language aliases migrate users toward evaluations and outputs

## Public surface

The supported, semver-stable surface contains customer-owned product resources
only. Internal administration and test-runner routes are intentionally absent
from the package. Private operations use a separately distributed admin tool.
