heybee 0.9.0

Python SDK for automating and integrating with the HeyBee controller.

heybee

Python SDK for automating and integrating with the HeyBee controller.

Install

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()

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:

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.