Metadata-Version: 2.4
Name: heph
Version: 0.0.56
Summary: Local-first document workspace for grounded answers, citations, memory, and recall practice with any LLM
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: cli,documents,llm,rag,retrieval,learning
Classifier: Development Status :: 3 - Alpha
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/docs/assets/logo-auto.svg" width="320">
</p>

# Heph

Heph is the agent brain the user talks to.

It owns the user-facing agent identity, research/talking orchestration, the
command entrypoint, slash-command coordination, and the composition needed to
connect the harness, AI runtime, interfaces, and extension contracts.

The validation layer is the harness.

## Source Layout

```text
src/
  heph/
    cli/       Console entrypoint and top-level command routing
    commands/  Slash-command registry and command coordinators
    sdk/       Programmatic runtime/session surface for native apps and automation
    product/   Temporary bridge for Heph self-knowledge context
    identity/  Stable agent identity target
    prompts/   Prompt-program target for Heph-facing behavior
    state/     Declarative state contract target
```

The `product/` bridge exists for current self-knowledge routing. It should stay
thin and should not become a second harness or a place for domain behavior.

## Boundaries

Heph is protected as the brain and composition layer. Lower packages must not
import it, and optional behavior should extend Heph through contracts or
composition instead of modifying harness or AI internals:

- Heph calls the harness for grounded answering, validation, citations, retrieval,
  memory, and armory workflows.
- Heph calls AI for provider/model runtime.
- Heph calls Interfaces for terminal and TUI presentation.
- Heph calls Extensions for stable extension contracts.
- Heph exposes SDK wrappers for non-terminal clients; those wrappers must stay
  UI-neutral and must not import `interfaces.*`.

Reusable validation behavior should move to the harness. Provider/API behavior
should move to AI. Conversational strategy, research orchestration, and
Heph-facing identity should stay here or move here as the migration continues.

## Development

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

## Related Docs

- [Root architecture guide](../../docs/architecture.md)
