heph 0.0.49__tar.gz

heph-0.0.49/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heph-0.0.49/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: heph
+Version: 0.0.49
+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: docling==2.94.0
+Requires-Dist: gymnasium==0.29.1
+Requires-Dist: numpy==1.26.4
+Requires-Dist: pufferlib==3.0.0
+Requires-Dist: torch==2.11.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="Hephaion" src="https://gildrb.github.io/heph/logo-auto.svg" width="128">
+</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.
+
+Heph is not the validation harness. That is Hephaion.
+
+## 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 Hephaion 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 Hephaion. 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)

heph-0.0.49/README.md

@@ -0,0 +1,61 @@
+<p align="center">
+  <img alt="Hephaion" src="https://gildrb.github.io/heph/logo-auto.svg" width="128">
+</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.
+
+Heph is not the validation harness. That is Hephaion.
+
+## 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 Hephaion 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 Hephaion. 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)

heph-0.0.49/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "heph"
+version = "0.0.49"
+description = "Local-first document workspace for grounded answers, citations, memory, and recall practice with any LLM"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Gil", email = "hi@gildrb.com" },
+]
+requires-python = ">=3.13"
+keywords = [
+    "cli",
+    "documents",
+    "llm",
+    "rag",
+    "retrieval",
+    "learning",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "certifi==2026.2.25",
+    "keyring==25.7.0",
+    "openai==2.24.0",
+    "docling==2.94.0",
+    "gymnasium==0.29.1",
+    "numpy==1.26.4",
+    "pufferlib==3.0.0",
+    "torch==2.11.0",
+    "unicodeit==0.7.5",
+    "rich==14.3.3",
+    "textual==8.2.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/gildrb/heph"
+Repository = "https://github.com/gildrb/heph"
+Issues = "https://github.com/gildrb/heph/issues"
+
+[project.scripts]
+heph = "heph.cli.main:main"
+hephaion = "heph.cli.main:main"
+
+[build-system]
+requires = ["setuptools==81.0.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ai*", "extensions*", "heph*", "hephaion*", "interfaces*"]
+
+[tool.setuptools.package-data]
+"*" = ["*.md", "*.toml", "py.typed"]

heph-0.0.49/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

heph-0.0.49/src/ai/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

heph-0.0.49/src/ai/diagnostics/__init__.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Self
+
+
+class NoopSpan:
+    __slots__ = ()
+
+    def set_attribute(self, key: str, value: object) -> object:
+        del key, value
+        return self
+
+    def end(self, end_time: float | None = None) -> None:
+        del end_time
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.end()
+
+
+class NoopTracer:
+    __slots__ = ()
+
+    def start_span(self, name: str, **kwargs: object) -> NoopSpan:
+        del name, kwargs
+        return NoopSpan()
+
+    def start_as_current_span(self, name: str, **kwargs: object) -> NoopSpan:
+        del name, kwargs
+        return NoopSpan()
+
+
+class NoopInstrument:
+    __slots__ = ()
+
+    def record(self, value: float, _attributes: dict[str, str] | None = None) -> None:
+        del value, _attributes
+
+    def add(self, value: float, _attributes: dict[str, str] | None = None) -> None:
+        del value, _attributes
+
+    def set(self, value: float, _attributes: dict[str, str] | None = None) -> None:
+        del value, _attributes
+
+
+class NoopMeter:
+    __slots__ = ()
+
+    def create_histogram(self, name: str, **kwargs: object) -> NoopInstrument:
+        del name, kwargs
+        return NoopInstrument()
+
+    def create_counter(self, name: str, **kwargs: object) -> NoopInstrument:
+        del name, kwargs
+        return NoopInstrument()
+
+    create_up_down_counter = create_counter
+
+    def create_gauge(self, name: str, **kwargs: object) -> NoopInstrument:
+        del name, kwargs
+        return NoopInstrument()
+
+
+_NOOP_TRACER = NoopTracer()
+_NOOP_METER = NoopMeter()
+
+
+def get_tracer(name: str) -> NoopTracer:
+    del name
+    return _NOOP_TRACER
+
+
+def get_meter(name: str) -> NoopMeter:
+    del name
+    return _NOOP_METER

heph-0.0.49/src/ai/diagnostics/py.typed

@@ -0,0 +1 @@
+

heph-0.0.49/src/ai/logging/__init__.py

@@ -0,0 +1,216 @@
+"""Structured logging, redaction, and timers."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re as _re
+import sys
+import time
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import ClassVar, Self
+
+from ai.types import is_object_list, is_string_mapping
+
+_LOG_TEXT_MUTED = "#6F6F6F"
+_LOG_ACCENT = "#D06A4A"
+_LOG_ERROR = "#FF6B5A"
+
+
+def _ansi_fg(hex_color: str) -> str:
+    color = hex_color.lstrip("#")
+    red = int(color[0:2], 16)
+    green = int(color[2:4], 16)
+    blue = int(color[4:6], 16)
+    return f"\033[38;2;{red};{green};{blue}m"
+
+
+# -- Redaction / scrubbing ---------------------------------------------------
+
+# Patterns for dict keys whose values should always be redacted
+_SENSITIVE_KEY_PATTERNS: list[_re.Pattern[str]] = [
+    _re.compile(r"(?i)(api.?key|secret|token(?!s)|password|auth(orization|entication))"),
+    _re.compile(r"(?i)(bearer|credential|private.?key)"),
+]
+
+# Unanchored versions — find secrets embedded within longer text
+_SENSITIVE_TEXT_PATTERNS: list[_re.Pattern[str]] = [
+    _re.compile(r"sk-or-v1-[a-zA-Z0-9\-_]{20,}"),  # OpenRouter API keys
+    _re.compile(r"sk-proj-[a-zA-Z0-9\-_]{20,}"),  # OpenAI project API keys
+    _re.compile(r"sk-[a-zA-Z0-9]{20,}"),  # OpenAI-style API keys
+    _re.compile(r"sk-ant-[a-zA-Z0-9\-]{20,}"),  # Provider API keys
+    _re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"),  # AWS access keys
+    _re.compile(r"AIza[0-9A-Za-z\-_]{35}"),  # Google API keys
+    _re.compile(r"ya29\.[0-9A-Za-z\-_]+"),  # Google OAuth tokens
+    _re.compile(r"Bearer\s+\S+", _re.IGNORECASE),  # Bearer tokens
+    _re.compile(r"\b[a-f0-9]{32,}\b"),  # Long hex strings (potential tokens)
+]
+
+_REDACTED = "***REDACTED***"
+
+
+def redact_text(text: str) -> str:
+    if not text:
+        return text
+    for pattern in _SENSITIVE_TEXT_PATTERNS:
+        text = pattern.sub(_REDACTED, text)
+    return text
+
+
+def _redact_dict(data: Mapping[str, object]) -> dict[str, object]:
+    return {key: _redact_value(key, value) for key, value in data.items()}
+
+
+def redact_mapping(data: Mapping[str, object]) -> dict[str, object]:
+    return _redact_dict(data)
+
+
+def _redact_value(key: str, value: object) -> object:
+    if any(pattern.search(key) for pattern in _SENSITIVE_KEY_PATTERNS):
+        return _REDACTED
+    return _redact_unkeyed_value(value)
+
+
+def _redact_unkeyed_value(value: object) -> object:
+    if is_string_mapping(value):
+        return _redact_dict(value)
+    if is_object_list(value):
+        return [_redact_unkeyed_value(item) for item in value]
+    if isinstance(value, str):
+        return redact_text(value)
+    return value
+
+
+class _JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        entry: dict[str, object] = {
+            "ts": datetime.fromtimestamp(record.created, tz=UTC).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        fields = getattr(record, "fields", None)
+        if is_string_mapping(fields):
+            entry.update(fields)
+        if record.exc_info and record.exc_info[1] is not None:
+            entry["exc"] = self.formatException(record.exc_info)
+        return json.dumps(_redact_dict(entry), default=str, ensure_ascii=False)
+
+
+class _TextFormatter(logging.Formatter):
+    _LEVEL_COLOURS: ClassVar[dict[str, str]] = {
+        "DEBUG": _ansi_fg(_LOG_TEXT_MUTED),
+        "INFO": _ansi_fg(_LOG_ACCENT),
+        "WARNING": _ansi_fg(_LOG_ACCENT),
+        "ERROR": _ansi_fg(_LOG_ERROR),
+        "CRITICAL": f"\033[1m{_ansi_fg(_LOG_ERROR)}",
+    }
+    _RESET = "\033[0m"
+    _DIM = f"\033[2m{_ansi_fg(_LOG_TEXT_MUTED)}"
+
+    def format(self, record: logging.LogRecord) -> str:
+        ts = datetime.fromtimestamp(record.created, tz=UTC).strftime("%H:%M:%S")
+        colour = self._LEVEL_COLOURS.get(record.levelname, "")
+        level = f"{colour}{record.levelname:<8}{self._RESET}"
+        parts = [f"{self._DIM}{ts}{self._RESET} {level} {record.name}: {record.getMessage()}"]
+        parts.extend(self._field_lines(record))
+        parts.extend(self._exception_lines(record))
+        return "\n".join(parts)
+
+    def _field_lines(self, record: logging.LogRecord) -> list[str]:
+        fields = getattr(record, "fields", None)
+        if not is_string_mapping(fields):
+            return []
+        return [
+            f"  {self._DIM}{key}={value}{self._RESET}"
+            for key, value in _redact_dict(fields).items()
+        ]
+
+    def _exception_lines(self, record: logging.LogRecord) -> list[str]:
+        if record.exc_info and record.exc_info[1] is not None:
+            return [self.formatException(record.exc_info)]
+        return []
+
+
+LOG_LEVEL_ENV = "HEPHAION_LOG_LEVEL"
+LOG_FILE_ENV = "HEPHAION_LOG_FILE"
+LOG_FORMAT_ENV = "HEPHAION_LOG_FORMAT"
+
+_hephaion_logger_initialised = False
+
+
+def get_logger(name: str) -> logging.Logger:
+    _ensure_hephaion_logger()
+    if not name.startswith("hephaion"):
+        name = f"hephaion.{name}"
+    return logging.getLogger(name)
+
+
+def _ensure_hephaion_logger() -> None:
+    global _hephaion_logger_initialised  # noqa: PLW0603
+    if _hephaion_logger_initialised:
+        return
+    _hephaion_logger_initialised = True
+
+    level, fmt = _logging_config()
+    logger = logging.getLogger("hephaion")
+    logger.setLevel(level)
+    logger.propagate = False
+    if not logger.handlers:
+        logger.addHandler(_stderr_handler(level, fmt))
+        if log_file := os.environ.get(LOG_FILE_ENV):
+            logger.addHandler(_file_handler(Path(log_file), level))
+    _quiet_noisy_loggers()
+
+
+def _logging_config() -> tuple[int, str]:
+    is_tty = sys.stderr.isatty()
+    default_level_name = "ERROR" if is_tty else "WARNING"
+    default_format = "text" if is_tty else "json"
+    level_name = os.environ.get(LOG_LEVEL_ENV, default_level_name).upper()
+    return getattr(logging, level_name, logging.WARNING), os.environ.get(
+        LOG_FORMAT_ENV,
+        default_format,
+    ).lower()
+
+
+def _stderr_handler(level: int, fmt: str) -> logging.Handler:
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setLevel(level)
+    handler.setFormatter(_JsonFormatter() if fmt == "json" else _TextFormatter())
+    return handler
+
+
+def _file_handler(path: Path, level: int) -> logging.Handler:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handler = logging.FileHandler(path, encoding="utf-8")
+    handler.setLevel(level)
+    handler.setFormatter(_JsonFormatter())
+    return handler
+
+
+def _quiet_noisy_loggers() -> None:
+    for noisy in ("openai", "httpx", "httpcore", "urllib3", "sentence_transformers"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+
+class Timer:
+    __slots__ = ("_end", "_start")
+
+    def __init__(self) -> None:
+        self._start: float = 0.0
+        self._end: float = 0.0
+
+    def __enter__(self) -> Self:
+        self._start = time.perf_counter()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self._end = time.perf_counter()
+
+    @property
+    def ms(self) -> float:
+        return (self._end - self._start) * 1000

heph-0.0.49/src/ai/logging/py.typed

@@ -0,0 +1 @@
+

heph-0.0.49/src/ai/providers/__init__.py

@@ -0,0 +1,24 @@
+"""Multi-provider LLM configuration."""
+
+from ai.providers.catalog import (
+    LiveProviderCatalog,
+    hydrate_provider_models,
+    prefetch_provider_model_catalogs,
+)
+from ai.providers.config import Provider, ProviderConfig, default_config, providers_dir
+from ai.providers.keyring_store import mask_key, resolve_key
+from ai.providers.registry import ModelInfo, get_registry
+
+__all__ = [
+    "LiveProviderCatalog",
+    "ModelInfo",
+    "Provider",
+    "ProviderConfig",
+    "default_config",
+    "get_registry",
+    "hydrate_provider_models",
+    "mask_key",
+    "prefetch_provider_model_catalogs",
+    "providers_dir",
+    "resolve_key",
+]

heph-0.0.49/src/ai/providers/access.py

@@ -0,0 +1,32 @@
+"""Provider access decisions independent of UI adapters."""
+
+from __future__ import annotations
+
+from ai.providers.catalog import hydrate_provider_models
+from ai.providers.config import Provider, ProviderConfig
+from ai.providers.endpoints import provider_uses_keyless_access
+from ai.providers.keyring_store import resolve_key
+from ai.providers.oauth import resolve_oauth_key
+
+
+def provider_is_accessible(provider: Provider, *, refresh_oauth: bool = True) -> bool:
+    if provider.slug == "openai-codex":
+        return bool(resolve_oauth_key(provider.slug, refresh_expired=refresh_oauth))
+    if provider_uses_keyless_access(provider.slug, provider.endpoint):
+        return True
+    return bool(
+        resolve_key(
+            provider.slug,
+            provider.api_key_env,
+            refresh_oauth=refresh_oauth,
+        )
+    )
+
+
+def activate_provider_config(pc: ProviderConfig, slug: str) -> Provider:
+    pc.set_active(slug)
+    hydrate_provider_models(pc, provider_slugs={slug})
+    provider = pc.providers[slug]
+    if not provider.current_model and provider.models:
+        provider.current_model = provider.models[0]
+    return provider