hirara

The Python client for the Hirara self-hosted agent tool hub.

Call web search, PDF, OCR, code execution, and Office-document tools like functions — against a hub you run. No API keys.

PyPI License Python

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

Method Tool
web_search(query, …) · web_fetch(url, …) web
pdf_read(...) · pdf_info(...) · pdf_create(content, …) PDF
ocr_read(...) · form_extract(...) OCR / forms
office_read(...) Word / PowerPoint / Excel
execute_code(language, code, …) sandboxed code
call(name, arguments) any tool, raw

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

Environment

Variable Purpose
HIRARA_HUB_URL Hub base URL (default http://localhost:8080)
HIRARA_HUB_TOKEN Bearer token, if the hub requires auth

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

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for lucasdmarshall from gravatar.com lucasdmarshall

Credits

Author: Lucas D Marshall (Kaung Myat San)

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev local ocr stt all

Tags

llm agent mcp tool-hub client sdk self-hosted

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hirara-0.2.0.tar.gz (15.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hirara-0.2.0-py3-none-any.whl (14.0 kB view details)

Uploaded Python 3

File details

Details for the file hirara-0.2.0.tar.gz.

File metadata

  • Download URL: hirara-0.2.0.tar.gz
  • Upload date:
  • Size: 15.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hirara-0.2.0.tar.gz
Algorithm Hash digest
SHA256 60814d07802f38da2020c36f74ecb34836907e5c85b3b25b768a8572a6268b67
MD5 bd088141a3efc11c7175937ac55b03a9
BLAKE2b-256 ff17e6dff1fcf0a2fd1de999d03159f3dca24e489d12d7d154eebb649d15710c

See more details on using hashes here.

Provenance

The following attestation bundles were made for hirara-0.2.0.tar.gz:

Publisher: pypi-publish.yml on lucasdmarshall/Hirara

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hirara-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: hirara-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 14.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hirara-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 e4ac3cdf286c2a7142f7bbf5c699c5eae0bd959682655f2ae4dc43808daac6b4
MD5 eea3d5e3154d2ade08629c132c541324
BLAKE2b-256 4db9fddacddc1dd2197b9565fea07d2fe5da1c24cd78e697441ec03c34b792b0

See more details on using hashes here.

Provenance

The following attestation bundles were made for hirara-0.2.0-py3-none-any.whl:

Publisher: pypi-publish.yml on lucasdmarshall/Hirara

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page