Metadata-Version: 2.4
Name: hiveminded-ai
Version: 0.1.0
Summary: Official Python SDK and command line interface for the Hive Minded AI beekeeping management API.
Project-URL: Homepage, https://hiveminded.ai
Project-URL: Documentation, https://api.hiveminded.ai/docs
Author: Hive Minded AI
License: MIT
Keywords: ai,api,beekeeping,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Hive Minded AI Python SDK

A small, typed Python client and command line interface for the
[Hive Minded AI](https://hiveminded.ai) beekeeping management API.

## Install

Once published to PyPI:

```bash
pip install hiveminded-ai
```

For local development from this repository:

```bash
pip install -e sdk/python
```

## Authentication

The client and CLI read credentials from the environment:

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `HIVEMINDED_API_KEY` | yes | none | Bearer token sent as `Authorization: Bearer <key>` |
| `HIVEMINDED_BASE_URL` | no | `https://api.hiveminded.ai` | API origin |

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

## Quickstart (Python)

```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

```python
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)

```bash
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):

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

## Development

```bash
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.
