Metadata-Version: 2.4
Name: heph
Version: 0.0.59
Summary: Local document agent for accurate, cited answers.
Author-email: Gil <hi@gildrb.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/gildrb/heph
Project-URL: Repository, https://github.com/gildrb/heph
Project-URL: Issues, https://github.com/gildrb/heph/issues
Keywords: agent,cli,documents,llm,rag,retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi==2026.2.25
Requires-Dist: keyring==25.7.0
Requires-Dist: openai==2.24.0
Requires-Dist: bm25s==0.3.5
Requires-Dist: docling-slim[standard]==2.94.0
Requires-Dist: scikit-learn==1.8.0
Requires-Dist: sentence-transformers==5.3.0
Requires-Dist: unicodeit==0.7.5
Requires-Dist: rich==14.3.3
Requires-Dist: textual==8.2.4
Dynamic: license-file

<p align="center">
  <img alt="Heph" src="https://raw.githubusercontent.com/gildrb/heph/main/assets/logo-auto.svg" width="240">
</p>

# Heph

<p align="center">
  A local document agent for accurate, cited answers from your files.
</p>

Heph is built around normal folders. An armory keeps your documents in
`materials/` and Heph-owned local state in `.harness/`, so the armory stays
portable and inspectable.

## What Heph Does

- Answers from local armory materials with verifiable citations.
- Indexes PDFs, Office documents, notes, code, and other supported text sources.
- Opens retrieved evidence and source context from the terminal UI.
- Keeps chats, retrieval indexes, memory, traces, and usage snapshots in local
  armory state.
- Lets provider and model choices remain configurable instead of hardcoded.
- Exposes a Python SDK for native apps, GUI shells, and automation.

## Install

```bash
uv tool install heph@latest
```

You can also install with pip:

```bash
pip install heph
```

Heph requires Python 3.13 or newer.

## Update

```bash
heph update
heph --version
```

## Quick Start

```bash
heph armory init my-notes
cp ~/Downloads/example.pdf ~/.armories/my-notes/materials/
heph my-notes
```

Inside Heph, ask questions about your materials. When Heph cites evidence, use
the Evidence panel or `/evidence` command to inspect the cited source context.

## Trust Model

Heph is local-first beta software. Materials remain in your armory, and
memory is scoped to that armory unless you explicitly choose to move or share
state. Analytics and crash reporting are opt-in from `/settings`.

Model providers may receive prompt content when selected for a turn. Review
[Trust and ownership](https://github.com/gildrb/heph/blob/main/docs/trust.md)
and [Privacy](https://github.com/gildrb/heph/blob/main/docs/privacy.md) for the
full data, cache, prompt, and compute contract.

## Docs

- [Getting started](https://github.com/gildrb/heph/blob/main/docs/getting-started.md)
- [Armories](https://github.com/gildrb/heph/blob/main/docs/armories.md)
- [CLI reference](https://github.com/gildrb/heph/blob/main/docs/cli-reference.md)
- [Configuration](https://github.com/gildrb/heph/blob/main/docs/configuration.md)
- [Models](https://github.com/gildrb/heph/blob/main/docs/models.md)
- [SDK](https://github.com/gildrb/heph/blob/main/docs/sdk.md)
- [Troubleshooting](https://github.com/gildrb/heph/blob/main/docs/troubleshooting.md)

## Development

The public package bundles the Heph CLI, harness, AI runtime, interfaces, and
extension contracts into one installable distribution. Repository development
still keeps those layers separated under `packages/`.

```bash
uv run pytest --no-cov packages/heph/test
uv run heph --help
uv run python -m scripts.check_repo_policies
uv run lint-imports
```
