Metadata-Version: 2.4
Name: hilt-python
Version: 0.2.5
Summary: HILT: Human-IA Log Trace - Privacy-first logging format for AI interactions
License: Apache-2.0
License-File: LICENSE
Keywords: ai,logging,llm,privacy,gdpr,openai
Author: HILT Team
Author-email: info@mcsedition.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: api
Provides-Extra: sheets
Requires-Dist: fastapi (>=0.109.0,<0.110.0) ; extra == "api"
Requires-Dist: google-auth (>=2.23.0,<3.0.0) ; extra == "sheets"
Requires-Dist: gspread (>=6.0.0,<7.0.0) ; extra == "sheets"
Requires-Dist: openai (>=1.0.0,<2.0.0)
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: python-dotenv (>=1.0.0,<2.0.0) ; extra == "api"
Requires-Dist: uvicorn (>=0.27.0,<0.28.0) ; extra == "api"
Project-URL: Bug Tracker, https://github.com/hilt-format/hilt-python/issues
Project-URL: Documentation, https://hilt-format.org
Project-URL: Homepage, https://hilt-format.org
Project-URL: Repository, https://github.com/hilt-format/hilt-python
Description-Content-Type: text/markdown

# HILT – Human–AI Log Tracing

[![Build Status](https://img.shields.io/github/actions/workflow/status/hilt-format/hilt-python/test.yml?branch=main)](https://github.com/hilt-format/hilt-python/actions)
[![Coverage](https://img.shields.io/codecov/c/github/hilt-format/hilt-python)](https://codecov.io/gh/hilt-format/hilt-python)
[![PyPI](https://img.shields.io/pypi/v/hilt)](https://pypi.org/project/hilt/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**HILT** is a privacy-first, open-source format for logging human–AI interactions. Drop in one line at startup and every LLM call is captured with prompts, completions, metrics, and error context—no refactors, no custom wrappers.

## What’s inside today

- **One-line auto-instrumentation** for the official OpenAI Python SDK (`client.chat.completions.create`)
- **Deterministic conversation threading** with prompt/completion links and reply metadata
- **Rich telemetry**: latency, token usage, cost estimates, HTTP-style status codes, and error surfaces
- **Storage backends** you control: append-only JSONL files or real-time Google Sheets dashboards
- **Thread-safe context management** so you can override sessions per request, per worker, or per tenant
- **Manual event logging** via `Session.append()` for tool calls, human feedback, or guardrail results

## Installation

```bash
pip install hilt
```

Need Google Sheets streaming? Install the Sheets extra:

```bash
pip install "hilt[sheets]"
```

## Quick start

```python
from hilt import instrument, uninstrument
from openai import OpenAI

# Enable automatic logging (writes to logs/chat.jsonl by default)
instrument(backend="local", filepath="logs/chat.jsonl")

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Give me three onboarding tips"}],
)

print(response.choices[0].message.content)

# Stop logging when your app shuts down
uninstrument()
```

After the single `instrument()` call:

- Prompts and completions are recorded as separate events
- Latency, tokens, cost, and status codes are populated automatically
- Conversation IDs remain stable so you can trace every exchange end to end

## Storage options

### Local JSONL (default)

```python
instrument(backend="local", filepath="logs/app.jsonl")
```

- Privacy-first: data never leaves your environment
- Plays nicely with analytics tooling (Python, Pandas, Spark, etc.)

### Google Sheets (real time)

See [Google Sheets setup guide](docs/google_sheets_setup.md) for credential and sheet ID steps.

```python
instrument(
    backend="sheets",
    sheet_id="1abc...",
    credentials_path="credentials.json",
    worksheet_name="LLM Logs",
    columns=["timestamp", "message", "cost_usd", "status_code"],
)
```

- Great for support, QA, or cost monitoring teams
- Columns control both ordering and visibility
- Works with `credentials_path` or in-memory `credentials_json`

## Advanced usage

### Provider selection

```python
instrument(
    backend="local",
    filepath="logs/app.jsonl",
    providers=["openai"],  # Anthropic / Gemini planned
)
```

Passing an empty list opens the session without patching any providers—useful for manual logging scenarios.

## Troubleshooting highlights

- **Nothing recorded?** Ensure `instrument()` runs before importing the OpenAI client.
- **Async apps?** Use the same call; the instrumentation is thread-safe and works with `AsyncOpenAI`.
- **Large logs?** Rotate files daily (`logs/app-YYYY-MM-DD.jsonl`) and prune with a cron job.
- **Sheets failing?** Double-check the service account has editor access and that `hilt[sheets]` is installed.

See `docs/` for deeper guides on privacy, advanced contexts, and FAQ.

## Development

Contributions are welcome! Start with [CONTRIBUTING.md](CONTRIBUTING.md). The test suite lives in `tests/`, and linting/type checking is configured via Ruff, Black, and MyPy.

## TODO

- Add auto-instrumentation for Anthropic Claude
- Add auto-instrumentation for Google Gemini
- Add auto-instrumentation for LangGraph

## License

Released under the [Apache License 2.0](LICENSE).
## Installation

```bash
pip install hilt-python
```

