hail-tool - Human–AI Ledger

Overview

hail-tool is the core capture layer of the HAIL ecosystem. AI driver integrations (hail-ollama, hail-claude, hail-openai, etc.) rely on HAILSession from hail_tool.api instead of implementing their own ledger logic.

Citation

Troendle, E.P. (2026). Human–AI Ledger (HAIL): A Structured Workflow for Traceable, Reproducible Human–AI Collaboration. Zenodo. DOI link

Installation

pip install hail-tool

Or from source:

git clone https://github.com/human-ai-ledger/hail-tool
cd hail-tool
pip install -e .

Quick Start

# Start a new session in your project directory
hail init

# Log a checkpoint during your work
hail checkpoint

# Sign off, generate & validate the Session Ledger YAML
hail signoff

# Export a Markdown report
hail signoff --export-md

Python API

from hail_tool.api import HAILSession

session = HAILSession(model_version="your-model", gdpr=True)

session.sign_on(
    identity_raw="Your Name",
    core_values=["transparency", "open science"],
    cognitive_style="iterative",
    communication_style="structured",
    ethical_orientation="responsible AI use",
    creative_orientation="co-creative",
    purpose="Your research purpose",
    goal="Session objective",
    constraints="none",
)

session.checkpoint(
    ai_contribution="What the AI did",
    human_contribution="What you provided or decided",
    reflections="Observations, tensions, insights",
)

path = session.sign_off(
    final_reflection="Summary of session.",
    summary="High-level aggregate of objectives.",
)

result = session.validate()
print(result.summary())

Session Ledgers

Finalised ledgers are saved to:

.hail/sessions/HAIL_session_<YYYYMMDD_HHMMSS>.yaml

Recommended .gitignore entry for in-progress sessions:

.hail/sessions/.current_session.yaml

Commit finalised HAIL_session_*.yaml files with your code for full reproducibility.

GDPR Safe Mode

By default (--gdpr), identity is SHA-256 hashed before writing to the ledger. Use --no-gdpr for raw identifiers.

Ecosystem

HAIL: Normative schema and workflow
hail-tool: Core capture layer — library & CLI
hail-ollama: Offline driver using local Ollama models
hail-claude: Planned driver for Anthropic Claude API
hail-openai: Planned driver for OpenAI API

Licence

hail-tool is free software released under the AGPL-3.0. For proprietary environments, see COMMERCIAL.md.