heph 0.0.49__py3-none-any.whl

ai/__init__.py

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

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

ai/diagnostics/py.typed

@@ -0,0 +1 @@
+

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

ai/logging/py.typed

@@ -0,0 +1 @@
+

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",
+]

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

ai/providers/api_profiles.py

@@ -0,0 +1,127 @@
+"""Provider-specific request profiles for OpenAI-compatible API surfaces."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from ai.providers.llama_cpp import LLAMA_CPP_PROVIDER_SLUG
+
+ReasoningPayload = Literal["openai", "deepseek", "openrouter", "none"]
+
+_REASONING_ORDER = ("low", "medium", "high", "xhigh")
+_OPENAI_ENDPOINT = "https://api.openai.com/v1"
+_DEEPSEEK_ENDPOINTS = ("https://api.deepseek.com", "https://api.deepseek.com/v1")
+_OPENROUTER_ENDPOINT = "https://openrouter.ai/api/v1"
+
+
+class ProviderProfileConfig(Protocol):
+    provider_slug: str
+    base_url: str
+    model: str
+
+
+class ReasoningPayloadConfig(ProviderProfileConfig, Protocol):
+    reasoning_level: str
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderRequestProfile:
+    name: str
+    reasoning_payload: ReasoningPayload
+    suppress_temperature_when_reasoning: bool = False
+
+
+_GENERIC_OPENAI_COMPATIBLE_PROFILE = ProviderRequestProfile(
+    name="openai-compatible",
+    reasoning_payload="openai",
+)
+_DEEPSEEK_PROFILE = ProviderRequestProfile(
+    name="deepseek",
+    reasoning_payload="deepseek",
+    suppress_temperature_when_reasoning=True,
+)
+_OPENROUTER_PROFILE = ProviderRequestProfile(
+    name="openrouter",
+    reasoning_payload="openrouter",
+)
+_NO_REASONING_PROFILE = ProviderRequestProfile(
+    name="provider-neutral",
+    reasoning_payload="none",
+)
+
+
+def request_profile_for_config(config: ProviderProfileConfig) -> ProviderRequestProfile:
+    slug = config.provider_slug
+    endpoint = _normalize_endpoint(config.base_url)
+    model = config.model.strip().lower()
+    if _uses_neutral_profile(slug):
+        return _NO_REASONING_PROFILE
+    if _uses_deepseek_profile(slug, endpoint, model):
+        return _DEEPSEEK_PROFILE
+    if _uses_openrouter_profile(slug, endpoint):
+        return _OPENROUTER_PROFILE
+    if _uses_openai_compatible_profile(slug, endpoint):
+        return _GENERIC_OPENAI_COMPATIBLE_PROFILE
+    return _GENERIC_OPENAI_COMPATIBLE_PROFILE
+
+
+def _uses_neutral_profile(slug: str) -> bool:
+    return slug in {LLAMA_CPP_PROVIDER_SLUG, "pollinations"}
+
+
+def _uses_deepseek_profile(slug: str, endpoint: str, model: str) -> bool:
+    return (
+        slug == "deepseek"
+        or endpoint in _DEEPSEEK_ENDPOINTS
+        or (model.startswith("deepseek-") and "deepseek.com" in endpoint)
+    )
+
+
+def _uses_openrouter_profile(slug: str, endpoint: str) -> bool:
+    return slug == "openrouter" or endpoint == _OPENROUTER_ENDPOINT
+
+
+def _uses_openai_compatible_profile(slug: str, endpoint: str) -> bool:
+    return slug in {"openai", "openai-codex"} or endpoint == _OPENAI_ENDPOINT
+
+
+def reasoning_payload_for_profile(
+    profile: ProviderRequestProfile,
+    requested_level: str,
+    supported_levels: Iterable[str],
+) -> dict[str, object]:
+    level = _select_reasoning_level(requested_level, supported_levels)
+    if level is None or profile.reasoning_payload == "none":
+        return {}
+    if profile.reasoning_payload == "deepseek":
+        effort = "max" if level == "xhigh" else "high"
+        return {"extra_body": {"thinking": {"type": "enabled"}}, "reasoning_effort": effort}
+    if profile.reasoning_payload == "openrouter":
+        return {"extra_body": {"reasoning": {"effort": level}}}
+    return {"reasoning_effort": level}
+
+
+def reasoning_payload_for_config(
+    config: ReasoningPayloadConfig,
+    supported_levels: Iterable[str],
+) -> tuple[dict[str, object], bool]:
+    profile = request_profile_for_config(config)
+    payload = reasoning_payload_for_profile(profile, config.reasoning_level, supported_levels)
+    suppress_temperature = profile.suppress_temperature_when_reasoning and bool(payload)
+    return payload, suppress_temperature
+
+
+def _select_reasoning_level(requested_level: str, supported_levels: Iterable[str]) -> str | None:
+    choices = tuple(level for level in supported_levels if level in _REASONING_ORDER)
+    if not choices:
+        return None
+    normalized = requested_level.casefold()
+    if normalized in choices:
+        return normalized
+    return choices[0]
+
+
+def _normalize_endpoint(base_url: str) -> str:
+    return base_url.strip().rstrip("/")