Hive Minded AI Python SDK

A small, typed Python client and command line interface for the Hive Minded AI beekeeping management API.

Install

Once published to PyPI:

pip install hiveminded-ai

For local development from this repository:

pip install -e sdk/python

Authentication

The client and CLI read credentials from the environment:

The key is never written to disk, logged, or exposed via repr.

Quickstart (Python)

from hiveminded import HiveMindedClient

# Reads HIVEMINDED_API_KEY from the environment, or pass api_key=...
with HiveMindedClient() as client:
    hives = client.hives.list(limit=10)
    for hive in hives["data"]:
        print(hive["id"])

    one = client.hives.get("hive_123")
    print(one["data"])

    inspection = client.inspections.create(
        hive_id="hive_123",
        notes="Strong laying pattern, no queen cells.",
    )

    result = client.agents.run("health_monitor", input={"hive_id": "hive_123"})

Responses are returned as the parsed JSON body. List endpoints use the standard envelope {"data": [...], "meta": {"total", "limit", "offset", "has_more", "cursor"}}; read response["data"] for the items.

Error handling

from hiveminded import (
    HiveMindedAuthError,
    HiveMindedNotFoundError,
    HiveMindedAPIError,
)

try:
    client.hives.get("does-not-exist")
except HiveMindedNotFoundError:
    ...          # HTTP 404
except HiveMindedAuthError:
    ...          # HTTP 401 / 403
except HiveMindedAPIError as err:
    print(err.status_code, err.code, err.request_id)

Errors never carry request payloads, headers, or credentials, so they are safe to log.

Quickstart (CLI)

export HIVEMINDED_API_KEY=sk_live_...

hiveminded hives list --limit 10
hiveminded hives get hive_123
hiveminded inspections create --hive hive_123 --notes "Looks healthy"
hiveminded tasks list --status open
hiveminded tasks create --title "Add second brood box"
hiveminded agents run health_monitor --input '{"hive_id": "hive_123"}'
hiveminded mcp config

Every command prints the API response as pretty-printed JSON. You can also pass the key inline for a single invocation (it is set for that process only and never persisted):

hiveminded --api-key sk_live_... hives list

Development

cd sdk/python
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q
.venv/bin/ruff check src tests

Tests use httpx.MockTransport and a fake client, so no network access is required.

Publishing

Publishing to PyPI is a maintainer step and is intentionally not automated here.