Skip to main content

Hailer

Hailer is a Python command-line package for chatting with your data. Ask questions about local CSV, Parquet, JSON or Excel files in plain English, and it explores the data and adds tables, charts and summaries to a live marimo notebook in your browser. You chat in the terminal; the notebook keeps the analysis and its Python code.

Documentation · Quickstart · Command reference

Quick start

You'll need:

  • uv, which provides the uvx command. Install it, then reopen your terminal.
  • Docker, installed and running: Docker Desktop on Windows or macOS, Docker Engine on Linux. Your notebook code runs in a Docker container that sees only your data folder, read-only, with no network.
  • An OpenAI API key for the default setup.
  • A web browser.

These steps work in PowerShell on Windows and in a terminal on macOS or Linux. uvx downloads Hailer, its dependencies and a suitable Python version when needed. You do not need to clone this repository.

1. Create a workspace and sign in

Run these commands in your terminal:

mkdir my-analysis
cd my-analysis
uvx hailer init
uvx hailer login openai

init creates your settings (hailer.toml), a starter notebook and a data/ folder. At the login prompt, paste your API key; input is hidden and the key is saved in your operating system's credential store. The starter settings use OpenAI with gpt-5.5 and the Docker kernel ([kernel] runtime = "docker"). If Docker is not on your machine, init says so and how to get it.

For a company or another model endpoint, follow custom endpoint setup after init, using that provider's login command, then continue below.

2. Add your data

Copy the CSV, Parquet, JSON or Excel files you want to analyse into the data/ folder inside my-analysis. Any filenames work.

For a small example, save this as data/sales.csv in your workspace:

month,region,revenue
2026-01,North,1200
2026-01,South,900
2026-02,North,1500
2026-02,South,1100

3. Start chatting

From the same terminal, run:

uvx hailer

The first start downloads Hailer's kernel image, which takes a minute or two. Then Hailer opens the notebook in your browser and starts the chat in your terminal. Keep the notebook tab open while you work; it provides the live session that runs the analysis.

Ask a question in the terminal, for example:

What data do I have? Summarise the columns and any missing values.

With the sample CSV, try:

Chart total revenue by month, split by region.

Tables and charts appear in the notebook. Type /exit to finish. To continue later, open a terminal in my-analysis and run uvx hailer again; it resumes your conversation and active notebook. Use /new for a fresh conversation, or /help to see the chat commands.

If startup fails, run uvx hailer doctor for checks and suggested fixes, or see Troubleshooting. Docker is not installed. or Docker is not running. means exactly that: install or start Docker and run uvx hailer again. doctor starts no kernel: every uvx hailer session starts its own and stops it when the chat ends.

Data and code: files are read locally, but your messages, code and notebook tool outputs (which can include data samples) go to the configured model endpoint. Notebook code runs in the Docker container, which sees your data folder read-only and has no network. Where Docker is not an option, runtime = "unsafe-local" runs it on your machine as you, with your files and network, if you accept that. See Security and kernel runtimes for details.

Inside another project

Hailer can also live inside an existing project, a uv workspace monorepo included, as a support chat that answers questions about both the data and the product:

uv add --dev hailer
uv run hailer init
uv run hailer data add finance "~/Shared/Finance exports"
uv run hailer

init puts everything in .hailer/ (settings, notebooks, context and skills to commit; data, state and this machine's local.toml ignored by git). The agent can search and read the project's code and docs, read-only, and data add mounts a folder from anywhere on the machine read-only in the kernel as DATA_FOLDERS["finance"]. See Inside another project.

Documentation

Development

git clone https://github.com/OpenAfterHours/hailer.git
cd hailer
uv sync --locked
uv run hailer login openai
uv run hailer
uv run pytest

Read the development guide for sample data and test details, and the release guide for the release process. Before changing the agent, providers, tools or conversation lifecycle, read docs/LEARNINGS.md, docs/INTERFACES.md and PLAN.md.

Preview the documentation:

uv run --locked --group docs zensical serve

See Maintaining the docs for build and publishing instructions.

Metadata

Release files for hailer 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hailer 0.4.0
File Size Uploaded Provenance Actions
hailer-0.4.0.tar.gz 831.8 kB With provenance Details for hailer-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hailer 0.4.0
File Interpreter ABI Platform Actions
hailer-0.4.0-py3-none-any.whl Python 3 none any Details for hailer-0.4.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / hailer-0.4.0.tar.gz

Download URL hailer-0.4.0.tar.gz
Size 831.8 kB
Tags Source
SHA-256 checksum
How to use checksums
26b8b8d21f6171b61598dcab5a271904183f9b2b745c9ad09afabc6f45b20d27
BLAKE2b-256 checksum
How to use checksums
977349bfae72e9dbf08b5eef62c06bc7f5426b5eb98e32b1bd80199b3b51db7d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / hailer-0.4.0-py3-none-any.whl

Download URL hailer-0.4.0-py3-none-any.whl
Size 267.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
128a5ca412b4c15550b72488d5d986f5030d944ba9d326d5abd4448dad9b3412
BLAKE2b-256 checksum
How to use checksums
aea9d22e16526e360d972bcd70b70e19ee998ae599961e4aa517ab80ca3c5c3f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for hailer 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hailer-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page