Metadata-Version: 2.4
Name: hirara
Version: 0.2.0
Summary: Python SDK for Hirara agent tools — run web/PDF/Office tools in-process, or call a self-hosted hub
Author: Lucas D Marshall (Kaung Myat San)
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/lucasdmarshall/Hirara
Project-URL: Repository, https://github.com/lucasdmarshall/Hirara
Project-URL: Issues, https://github.com/lucasdmarshall/Hirara/issues
Keywords: llm,agent,mcp,tool-hub,client,sdk,self-hosted
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: httpx>=0.28
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: local
Requires-Dist: hirara-web>=0.1.0; extra == "local"
Requires-Dist: hirarapdf>=0.1.0; extra == "local"
Requires-Dist: hirarareader>=0.1.0; extra == "local"
Provides-Extra: ocr
Requires-Dist: hiraraocr>=0.1.0; extra == "ocr"
Provides-Extra: stt
Requires-Dist: hirarastt>=0.1.0; extra == "stt"
Provides-Extra: all
Requires-Dist: hirara[local]; extra == "all"
Requires-Dist: hirara[ocr]; extra == "all"
Requires-Dist: hirara[stt]; extra == "all"
Dynamic: license-file

<div align="center">

# hirara

**The Python client for the [Hirara](https://github.com/lucasdmarshall/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](https://img.shields.io/pypi/v/hirara.svg)](https://pypi.org/project/hirara/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)

</div>

---

```bash
pip install hirara
```

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

```python
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](https://github.com/lucasdmarshall/Hirara)**,
which you self-host:

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

```bash
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](LICENSE) and [NOTICE](NOTICE).

Copyright 2026 Lucas D Marshall (Kaung Myat San).
