pip install hirara

import hirara
hirara.configure("http://localhost:8080")          # or set HIRARA_HUB_URL

hirara.web_search("rust borrow checker", max_results=5)
hirara.pdf_read(path="report.pdf")                  # client reads + base64s the file for you
hirara.office_read(path="deck.pptx")["markdown"]
hirara.execute_code("python", "print(sum(range(10)))")
hirara.ocr_read(path="scan.png", languages=["en"])

Or an explicit client (multiple hubs, threads, custom timeout):

from hirara import Client
hub = Client("http://localhost:8080", token="…")    # or HIRARA_HUB_TOKEN
hub.form_extract(path="invoice.pdf")["fields"]

It talks to a running hub

hirara is a thin client — it does not bundle the tools (some need Docker, SearXNG, or heavy models). It forwards calls to a running Hirara hub, which you self-host:

docker compose -f docker-compose.hub.yml up -d --build

pip install hirara + a hub running = tools that work. No hub, no results.

Nice touches

• Local files just work. Pass path= and the client reads the file and sends it as base64 — so it works even when the hub has no access to your disk (the default for a networked hub). Or pass url= / base64=.
• Errors are exceptions. A tool that reports a problem (blocked URL, bad input) raises HiraraToolError; an unreachable hub or bad token raises HiraraError. Pass raise_on_error=False to call() to get the raw dict.
• Discovery. hirara.tools() returns the hub's aggregated tool schemas; hirara.health() reports which backends are up.
• Auth. Set a token (arg or HIRARA_HUB_TOKEN) and it's sent as a bearer header — needed only when the hub is exposed on a network.

Tools

File tools accept path= (local, auto-base64), url=, or base64=.

Environment

Testing

pip install -e ".[dev]"
pytest -q

The suite drives the client against a mock hub (httpx MockTransport): argument forwarding, path= → base64, one-source validation, error-to-exception mapping, auth headers, and discovery.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 Lucas D Marshall (Kaung Myat San).