tunarag-python 0.2.1__py3-none-any.whl

tunarag/config.py

@@ -0,0 +1,257 @@
+"""Typed settings and deterministic configuration resolution."""
+
+import math
+import os
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+from .errors import ConfigurationError
+
+_ENV_TO_FIELD = {
+    "TUNARAG_HOME": "home",
+    "TUNARAG_DB_PATH": "db_path",
+    "TUNARAG_CACHE_DIR": "cache_dir",
+    "TUNARAG_ARTIFACT_DIR": "artifact_dir",
+    "TUNARAG_MAX_TRIALS": "max_trials",
+    "TUNARAG_CONCURRENCY": "concurrency",
+    "TUNARAG_SAMPLE_CONCURRENCY": "sample_concurrency",
+    "TUNARAG_SEED": "seed",
+    "TUNARAG_MAX_RETRIES": "max_retries",
+    "TUNARAG_SAMPLE_TIMEOUT_SECONDS": "sample_timeout_seconds",
+    "TUNARAG_TRIAL_TIMEOUT_SECONDS": "trial_timeout_seconds",
+    "TUNARAG_CACHE_POLICY": "cache_policy",
+}
+_FIELDS = frozenset(_ENV_TO_FIELD.values())
+_INTEGER_FIELDS = {
+    "max_trials",
+    "concurrency",
+    "sample_concurrency",
+    "seed",
+    "max_retries",
+}
+_PATH_FIELDS = {"home", "db_path", "cache_dir", "artifact_dir"}
+_FLOAT_FIELDS = {"sample_timeout_seconds", "trial_timeout_seconds"}
+
+
+class CachePolicy(str, Enum):
+    """Allowed cache read and write behavior."""
+
+    OFF = "off"
+    READ_ONLY = "read_only"
+    WRITE_ONLY = "write_only"
+    READ_WRITE = "read_write"
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Resolved core settings with no provider credentials."""
+
+    home: Path
+    db_path: Path
+    cache_dir: Path
+    artifact_dir: Path
+    max_trials: int = 25
+    concurrency: int = 4
+    sample_concurrency: int = 8
+    seed: int = 0
+    max_retries: int = 2
+    sample_timeout_seconds: float = 60.0
+    trial_timeout_seconds: float = 300.0
+    cache_policy: CachePolicy = CachePolicy.READ_WRITE
+
+    def __post_init__(self) -> None:
+        _require_positive("max_trials", self.max_trials)
+        _require_positive("concurrency", self.concurrency)
+        _require_positive("sample_concurrency", self.sample_concurrency)
+        _require_integer("seed", self.seed)
+        _require_integer("max_retries", self.max_retries)
+        if self.max_retries < 0:
+            raise ConfigurationError("max_retries must not be negative", stage="config")
+        for field in _FLOAT_FIELDS:
+            _require_positive_float(field, getattr(self, field))
+
+    @classmethod
+    def resolve(
+        cls,
+        *,
+        overrides: Mapping[str, Any] | None = None,
+        config_path: str | Path | None = None,
+        environ: Mapping[str, str] | None = None,
+    ) -> "Settings":
+        """Resolve defaults, selected TOML, known environment variables, and overrides."""
+
+        values: dict[str, Any] = {
+            "max_trials": 25,
+            "concurrency": 4,
+            "sample_concurrency": 8,
+            "seed": 0,
+            "max_retries": 2,
+            "sample_timeout_seconds": 60.0,
+            "trial_timeout_seconds": 300.0,
+            "cache_policy": CachePolicy.READ_WRITE,
+        }
+        if config_path is not None:
+            values.update(_read_toml(Path(config_path)))
+        values.update(_read_environment(os.environ if environ is None else environ))
+        if overrides is not None:
+            _reject_unknown(overrides, source="overrides")
+            values.update(overrides)
+
+        home = _as_path("home", values.get("home", _default_home()))
+        values["home"] = home
+        values.setdefault("db_path", home / "experiments.db")
+        values.setdefault("cache_dir", home / "cache")
+        values.setdefault("artifact_dir", home / "artifacts")
+
+        for field in _PATH_FIELDS:
+            values[field] = _as_path(field, values[field])
+        for field in _INTEGER_FIELDS:
+            values[field] = _as_integer(field, values[field])
+        for field in _FLOAT_FIELDS:
+            values[field] = _as_float(field, values[field])
+        values["cache_policy"] = _as_cache_policy(values["cache_policy"])
+        return cls(**values)
+
+    def as_dict(self) -> dict[str, str | int | float]:
+        """Return a serializable settings view containing no secrets."""
+
+        return {
+            "home": str(self.home),
+            "db_path": str(self.db_path),
+            "cache_dir": str(self.cache_dir),
+            "artifact_dir": str(self.artifact_dir),
+            "max_trials": self.max_trials,
+            "concurrency": self.concurrency,
+            "sample_concurrency": self.sample_concurrency,
+            "seed": self.seed,
+            "max_retries": self.max_retries,
+            "sample_timeout_seconds": self.sample_timeout_seconds,
+            "trial_timeout_seconds": self.trial_timeout_seconds,
+            "cache_policy": self.cache_policy.value,
+        }
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as stream:
+            document = tomllib.load(stream)
+    except (OSError, tomllib.TOMLDecodeError) as error:
+        raise ConfigurationError(
+            f"could not read TunaRAG configuration: {path}",
+            stage="config",
+            details={"path": str(path), "cause": type(error).__name__},
+        ) from error
+    section = document.get("tunarag", {})
+    if not isinstance(section, Mapping):
+        raise ConfigurationError("the [tunarag] TOML section must be a table", stage="config")
+    _reject_unknown(section, source=str(path))
+    return dict(section)
+
+
+def _read_environment(environ: Mapping[str, str]) -> dict[str, Any]:
+    values: dict[str, Any] = {}
+    for variable, field in _ENV_TO_FIELD.items():
+        if variable not in environ:
+            continue
+        raw = environ[variable]
+        if not raw.strip():
+            raise ConfigurationError(
+                f"{variable} must not be empty",
+                stage="config",
+                details={"variable": variable},
+            )
+        values[field] = raw
+    return values
+
+
+def _reject_unknown(values: Mapping[str, Any], *, source: str) -> None:
+    unknown = sorted(str(key) for key in values if key not in _FIELDS)
+    if unknown:
+        raise ConfigurationError(
+            f"unknown TunaRAG configuration keys in {source}",
+            stage="config",
+            details={"keys": unknown, "source": source},
+        )
+
+
+def _as_path(field: str, value: Any) -> Path:
+    if not isinstance(value, (str, os.PathLike)):
+        raise ConfigurationError(f"{field} must be a path", stage="config")
+    if isinstance(value, str) and not value.strip():
+        raise ConfigurationError(f"{field} must not be empty", stage="config")
+    return Path(value).expanduser()
+
+
+def _as_integer(field: str, value: Any) -> int:
+    if isinstance(value, bool):
+        raise ConfigurationError(f"{field} must be an integer", stage="config")
+    try:
+        converted = int(value)
+    except (TypeError, ValueError) as error:
+        raise ConfigurationError(f"{field} must be an integer", stage="config") from error
+    if isinstance(value, float) and not value.is_integer():
+        raise ConfigurationError(f"{field} must be an integer", stage="config")
+    if isinstance(value, str) and str(converted) != value.strip():
+        raise ConfigurationError(f"{field} must be an integer", stage="config")
+    return converted
+
+
+def _as_cache_policy(value: Any) -> CachePolicy:
+    if isinstance(value, CachePolicy):
+        return value
+    try:
+        return CachePolicy(value)
+    except (TypeError, ValueError) as error:
+        choices = ", ".join(policy.value for policy in CachePolicy)
+        raise ConfigurationError(
+            f"cache_policy must be one of: {choices}", stage="config"
+        ) from error
+
+
+def _as_float(field: str, value: Any) -> float:
+    if isinstance(value, bool):
+        raise ConfigurationError(f"{field} must be a number", stage="config")
+    try:
+        converted = float(value)
+    except (TypeError, ValueError) as error:
+        raise ConfigurationError(f"{field} must be a number", stage="config") from error
+    if not math.isfinite(converted):
+        raise ConfigurationError(f"{field} must be finite", stage="config")
+    return converted
+
+
+def _require_integer(field: str, value: int) -> None:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise ConfigurationError(f"{field} must be an integer", stage="config")
+
+
+def _require_positive(field: str, value: int) -> None:
+    _require_integer(field, value)
+    if value < 1:
+        raise ConfigurationError(f"{field} must be positive", stage="config")
+
+
+def _require_positive_float(field: str, value: float) -> None:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise ConfigurationError(f"{field} must be a number", stage="config")
+    if not math.isfinite(value) or value <= 0:
+        raise ConfigurationError(f"{field} must be a positive finite number", stage="config")
+
+
+def _default_home() -> Path:
+    if sys.platform == "win32":
+        root = os.environ.get("LOCALAPPDATA")
+        return Path(root) / "TunaRAG" if root else Path.home() / "AppData" / "Local" / "TunaRAG"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "TunaRAG"
+    root = os.environ.get("XDG_DATA_HOME")
+    return Path(root) / "tunarag" if root else Path.home() / ".local" / "share" / "tunarag"

tunarag/contracts.py

@@ -0,0 +1,88 @@
+"""Protocols implemented by user-owned RAG systems and package extensions."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from .cache import CacheEntry, CacheKey, CacheLookup, CachePrivacy
+from .domain import Candidate, MetricValue, UsageRecord
+
+if TYPE_CHECKING:
+    from .store import StudyEvent
+
+
+class RAGAdapter(Protocol):
+    """Execute a user's RAG system for one candidate and example."""
+
+    async def run(
+        self, candidate: Candidate, example: Any
+    ) -> tuple[Any, Sequence[UsageRecord]]: ...
+
+
+class Dataset(Protocol):
+    """Provide versioned evaluation examples."""
+
+    @property
+    def version(self) -> str: ...
+
+    def __aiter__(self) -> AsyncIterator[Any]: ...
+
+
+class Evaluator(Protocol):
+    """Convert an adapter output and example into metric observations."""
+
+    async def evaluate(self, output: Any, example: Any) -> Sequence[MetricValue]: ...
+
+
+class SearchStrategy(Protocol):
+    """Suggest candidates and observe completed trials."""
+
+    async def suggest(self) -> Candidate: ...
+
+    async def observe(
+        self,
+        candidate: Candidate,
+        metrics: Sequence[MetricValue],
+        usage: Sequence[UsageRecord],
+    ) -> None: ...
+
+
+@runtime_checkable
+class ReplayableSearchStrategy(Protocol):
+    """Restore strategy state from one durably reserved trial."""
+
+    async def replay(
+        self,
+        candidate: Candidate,
+        metrics: Sequence[MetricValue],
+        usage: Sequence[UsageRecord],
+    ) -> None: ...
+
+
+@runtime_checkable
+class Fingerprintable(Protocol):
+    """Expose secret-safe semantic configuration for identity checks."""
+
+    def fingerprint(self) -> Any: ...
+
+
+class EventCallback(Protocol):
+    """Consume a durable event after its transaction commits."""
+
+    async def on_event(self, event: StudyEvent) -> None: ...
+
+
+class Cache(Protocol):
+    """Persist and retrieve versioned semantic results."""
+
+    def get(self, key: CacheKey) -> CacheLookup: ...
+
+    def put(
+        self,
+        key: CacheKey,
+        payload: bytes | bytearray | memoryview,
+        *,
+        privacy: CachePrivacy = CachePrivacy.STANDARD,
+        ttl_seconds: float | None = None,
+    ) -> CacheEntry: ...