Metadata-Version: 2.4
Name: inferhive
Version: 0.3.1
Summary: SDK and CLI for InferHive: GPU rentals and reservations, batch jobs with a GPU queue, cloud files and an OpenAI-compatible LLM gateway, paid in processing coins
Keywords: gpu,inference,llm,jobs,kubernetes,openai-compatible,cli,sdk
Author: David Petrocelli, Agustín Hernando
Author-email: David Petrocelli <dmpetrocelli@gmail.com>, Agustín Hernando <agusher1304@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Spanish
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Dist: httpx>=0.28.1
Requires-Dist: typer>=0.27.2
Requires-Dist: openai>=3.22.1 ; extra == 'openai'
Requires-Dist: llama-cpp-python>=0.3 ; extra == 'worker'
Requires-Python: >=3.12
Project-URL: Homepage, https://hive.impulsate.lat
Project-URL: Portal, https://inferhive.impulsate.lat
Project-URL: Documentation, https://hive.impulsate.lat/detailed
Project-URL: Changelog, https://hive.impulsate.lat
Provides-Extra: openai
Provides-Extra: worker
Description-Content-Type: text/markdown

# inferhive (SDK + CLI)

Python SDK and command line for [InferHive](https://hive.impulsate.lat), the collaborative
GPU lending and LLM inference platform by Impulsate: rent or reserve GPUs, run batch jobs
(with a queue when every GPU is busy), move files to and from the cloud, and call an
OpenAI-compatible LLM gateway. Everything is paid in **processing coins (PC)**, the platform's
credits.

- Commands: `inferhive` (and `pcoin`, kept as an alias).
- Python import package: `pcoin`.
- Requires Python 3.12+. The portal lives at https://inferhive.impulsate.lat.

## Install

```bash
pip install inferhive            # SDK + CLI
pip install 'inferhive[openai]'  # plus the OpenAI client for the LLM gateway
pip install 'inferhive[worker]'  # plus llama-cpp-python, to lend your own device as a worker
```

## Log in

```bash
inferhive login              # opens the portal in your browser; type the code shown here
inferhive balance
```

`inferhive login` asks the portal for an API key: you approve it in the browser with your
usual portal session, typing the code the terminal prints. The key is stored in
`~/.config/pcoin/platform_key` (mode 0600) and used by the CLI and the SDK from then on.
Revoke it any time from the portal (API keys). Scripts and CI can use a key you created in
the portal instead, through the `INFERHIVE_API_KEY` environment variable.

## Command line

```bash
inferhive offers                                   # GPUs and CPU you can rent right now
inferhive rent --gpu dp-note --template pytorch-jupyter --hours 1   # then open the URL it prints
inferhive instances | stop INS-XXXXXX              # your rentals
inferhive reserve --gpu knode11 --start 2026-11-10T18:00 --hours 2

inferhive job run python:3.12-slim -- python -c "print('hola')"            # CPU job
inferhive job run ghcr.io/you/whisper:1 --offer gpu --minutes 60 \
    --input meeting.mp3 --outputs ./results -- python -m pcoin.jobio -- python run.py
inferhive job list | logs JOB-XXXXXX | cancel JOB-XXXXXX
inferhive job outputs JOB-XXXXXX ./results        # outputs of a job sent with --detach (--force to overwrite)

inferhive artifact put data.zip | list | get ART-XXXXXXXX | rm ART-XXXXXXXX
inferhive volume create dp-note 5 | list | delete VOL-XXXXXX
inferhive llm chat "Explain processing coins in one line"
```

GPU jobs sent with `--offer gpu` (any GPU) or with `--wait` on a busy node wait in a queue and
start when a GPU frees up; nothing is charged while they wait. Inside the job container,
`python -m pcoin.jobio -- <your command>` downloads the input files to `/inputs`, runs your
program and uploads `/outputs` as a tarball when it ends.

## Python

```python
import pcoin

with pcoin.Client() as c:  # uses the key saved by `inferhive login`
    print(c.balance())  # {"currency": "PC", "available": ..., ...}

    free = [o for o in c.offers(gpu="4060") if o["available_now"]]
    inst = c.rent(free[0]["id"], "pytorch-jupyter", hours=1)
    c.stop(inst["id"])

    audio = c.upload_artifact("meeting.mp3")
    job = c.submit_job(
        "ghcr.io/you/whisper:1",
        offer="gpu",  # or a node name
        timeout_minutes=60,
        inputs=[audio["id"]],
        outputs=True,
        command=["python", "-m", "pcoin.jobio", "--", "python", "run.py"],
    )
    done = c.wait_job(job["id"], on_update=lambda j: print(j["status"], j.get("queue_position")))
    c.download_artifact(done["result"]["output_artifact"], "results.tar.gz")
```

LLM gateway, with any OpenAI client (`pip install 'inferhive[openai]'`):

```python
from pcoin import llm

client = llm.openai_client()  # PCOIN_API_KEY or ~/.config/pcoin/api_key
reply = client.chat.completions.create(
    model="gemma4-e4b",
    messages=[{"role": "user", "content": "Hola"}],
)
print(reply.choices[0].message.content)
print(llm.chat_full("Hola")["cost_pc"])  # the PC the gateway charged for that call
```

## Environment variables

| Variable | Purpose |
|---|---|
| `INFERHIVE_API_KEY` | Platform API key (`pak_...`) for `/api/v1`; overrides the saved one |
| `PCOIN_API_KEY` | LLM gateway key (`pck_...`), created in the portal (LLM keys) |
| `INFERHIVE_PORTAL_URL`, `INFERHIVE_LLM_URL` | Other portal or gateway (defaults: the public ones) |
| `PCOIN_CONFIG_DIR` | Where keys are stored (default `~/.config/pcoin`) |
| `INFERHIVE_RETRY_429_MAX_WAIT` | Longest `Retry-After` (seconds) waited out on a `429` before retrying (default 120; 0 disables the retry) |

## Errors

Every API error raises a `pcoin.errors.PCoinError` subclass with a stable `code`
(`AuthError`, `InsufficientCreditsError`, `NotFoundError`, `ValidationError`, `RateLimitError`,
`ServerError`). The CLI prints the message and exits with status 1.

## Changes

- 0.3.1: `pcoin.jobio` retries GCS `5xx`/`429` and incomplete downloads (`.part` then rename),
  refuses two inputs with the same file name, builds the outputs tarball on disk and keeps the
  program's exit code when the upload fails; `job run --outputs` / `job outputs` never
  overwrite local files (`--force`) and list what they extracted; `download_artifact` uses a
  unique temporary file and an atomic final check; `upload_artifact` and `job run --input`
  delete the reserved files when an upload fails; the CLI says when it waits for a `429`
  (`INFERHIVE_RETRY_429_MAX_WAIT`); the Access redirect error tells students to run
  `inferhive login`; messages name the `inferhive` command.
- 0.3.0: `pcoin.jobio` uses `/inputs` and `/outputs` when the portal mounts them and otherwise
  writable folders under `/scratch`, and retries connection errors; automatic retry of `429`
  following `Retry-After`; `artifact get` no longer overwrites local files (`--force`);
  `job run --secret-env`, `--detach --outputs` and `job outputs`; `rent --minutes`;
  `llm keys save`.
- 0.2.0: browser login (`pcoin login`), GPU queue, cloud files and batch jobs.

## License

MIT. Full documentation, pricing and the platform's architecture: https://hive.impulsate.lat.
