smartpipe-cli 1.3.0__py3-none-any.whl

smartpipe/config/store.py

@@ -0,0 +1,252 @@
+"""Read and write ``config.toml``.
+
+Rules (plan/decisions.md D09 + DEFER-1): the file is optional; unknown keys are
+*ignored* on read (forward compatibility) but *preserved* on write — an older
+smartpipe never strips a newer one's settings; wrong-typed values fail loudly
+with the key named; API keys are never stored here. Writes are atomic
+(same-directory temp file + ``os.replace``), so a concurrent reader can never
+see a torn file. Comments do not survive a rewrite: tomli-w cannot round-trip
+them and tomlkit stays outside the dependency budget — docs/reference/cli.md
+says so out loud.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import tempfile
+import tomllib
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import tomli_w
+
+from smartpipe.config.paths import human_path
+from smartpipe.core.errors import SetupFault
+from smartpipe.core.jsontools import as_record
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+__all__ = [
+    "BUILTIN_PROFILES",
+    "Config",
+    "load_config",
+    "profile_names",
+    "save_config",
+    "set_active_profile",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    model: str | None = None
+    embed_model: str | None = None
+    concurrency: int | None = None
+    output: str | None = None
+    profile: str | None = None  # the active profile's name (D30)
+    allow_captions: bool | None = None  # cloud conversions consent (D35; flag wins)
+    stt_model: str | None = None  # remote transcription role (D39/05); unset = the ladder
+    cache: bool | None = None  # result caching (D38/15) — account-level posture
+    cache_days: int | None = None  # sweep TTL (D39/02); default 30
+    cache_max_mb: int | None = None  # LRU size cap (D39/02); default 500
+
+
+_EMPTY_PROFILE: Mapping[str, object] = {}
+
+# D30: shipped presets, generated here so they can't rot in user files. A
+# profile is ONLY a bundle of existing config keys — that's the fence.
+BUILTIN_PROFILES: Mapping[str, Mapping[str, object]] = {
+    # picking a cloud preset IS the consent for paid image/audio-to-text
+    # conversions (D35) — the wizard says so; per-row disclosures continue
+    # gpt-5.4-mini works on BOTH the key wire and the ChatGPT-login (Codex)
+    # wire — 4o-mini is rejected by Codex accounts (owner-hit). Audio input is
+    # assumed UNSUPPORTED on OpenAI: the ladder falls to whisper automatically.
+    "openai": {
+        "model": "gpt-5.4-mini",
+        "embed-model": "text-embedding-3-small",
+        "allow-captions": True,
+    },
+    "gemini": {
+        "model": "gemini-3.1-flash-lite",  # GA, fully multimodal, probe-verified (D45)
+        "embed-model": "gemini/gemini-embedding-001",
+        "allow-captions": True,
+    },
+    "local": {
+        "model": "ollama/gemma-4-e2b",  # multimodal 2.3B-effective, 128k
+        "embed-model": "ollama/embeddinggemma",  # the pivot anchor: 308M, multilingual
+    },
+}
+
+
+def load_config(path: Path, environ: Mapping[str, str] | None = None) -> Config:
+    """Flat keys win over the active profile (a direct set is the most recent
+    intent); the active profile is SMARTPIPE_PROFILE > the file's `profile` key."""
+    data = _read_raw(path)
+    active = _active_profile(data, environ or {}, path)
+    base: Mapping[str, object] = _profile_values(data, active, path) if active is not None else {}
+    merged = {**base, **{k: v for k, v in data.items() if k != "profiles"}}
+    return Config(
+        model=_string(merged, "model", path),
+        embed_model=_string(merged, "embed-model", path),
+        concurrency=_positive_int(merged, "concurrency", path),
+        output=_string(merged, "output", path),
+        profile=active,
+        allow_captions=_boolean(merged, "allow-captions", path),
+        stt_model=_string(merged, "stt-model", path),
+        cache=_boolean(merged, "cache", path),
+        cache_days=_positive_int(merged, "cache-days", path),
+        cache_max_mb=_positive_int(merged, "cache-max-mb", path),
+    )
+
+
+def set_active_profile(path: Path, name: str | None) -> None:
+    """Flip ONLY the profile key — never the flat keys, so resolved profile
+    values are not materialized into the file (they'd shadow every later
+    profile switch)."""
+    merged = dict(_read_raw(path))
+    if name is None:
+        merged.pop("profile", None)
+    else:
+        merged["profile"] = name
+    _write_raw(path, merged)
+
+
+def profile_names(path: Path) -> tuple[str, ...]:
+    """Every selectable profile: user-defined tables plus the shipped presets."""
+    defined = as_record(_read_raw(path).get("profiles"))
+    names = set(BUILTIN_PROFILES)
+    if defined is not None:
+        names.update(defined)
+    return tuple(sorted(names))
+
+
+def _active_profile(
+    data: Mapping[str, object], environ: Mapping[str, str], path: Path
+) -> str | None:
+    from_env = environ.get("SMARTPIPE_PROFILE", "").strip()
+    name = from_env or _string(data, "profile", path)
+    if not name:
+        return None
+    defined = as_record(data.get("profiles"))
+    known: set[str] = set(BUILTIN_PROFILES)
+    if defined is not None:
+        known |= set(defined)
+    if name not in known:
+        raise SetupFault(
+            f"error: profile {name!r} doesn't exist\n"
+            f"  Known profiles: {', '.join(sorted(known))}\n"
+            "  Pick one: smartpipe config profile NAME — or define [profiles."
+            f"{name}] in {human_path(path)}"
+        )
+    return name
+
+
+def _profile_values(data: Mapping[str, object], name: str, path: Path) -> Mapping[str, object]:
+    del path  # errors here don't need the file location — the key names suffice
+    defined = as_record(data.get("profiles"))
+    table = as_record(defined.get(name)) if defined is not None else None
+    if table is not None:
+        allowed = {"model", "embed-model", "concurrency", "output", "allow-captions"}
+        unknown = set(table) - allowed
+        if unknown:
+            raise SetupFault(
+                f"error: profile {name!r} has unknown key {sorted(unknown)[0]!r}\n"
+                f"  A profile bundles: {', '.join(sorted(allowed))}"
+            )
+        return table
+    return BUILTIN_PROFILES.get(name, _EMPTY_PROFILE)
+
+
+def save_config(path: Path, config: Config) -> None:
+    merged = dict(_read_raw(path))  # a corrupt file fails loudly before we overwrite evidence
+    ours: dict[str, str | int | None] = {
+        "model": config.model,
+        "embed-model": config.embed_model,
+        "concurrency": config.concurrency,
+        "output": config.output,
+        "profile": config.profile,
+        "allow-captions": config.allow_captions,
+        "stt-model": config.stt_model,
+        "cache": config.cache,
+        "cache-days": config.cache_days,
+        "cache-max-mb": config.cache_max_mb,
+    }
+    for key, value in ours.items():
+        if value is None:
+            merged.pop(key, None)  # None = unset (pinned semantics)
+        else:
+            merged[key] = value
+    _write_raw(path, merged)
+
+
+def _write_raw(path: Path, merged: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(tomli_w.dumps(merged))
+        os.replace(tmp, path)  # atomic on POSIX & Windows (same volume by construction)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
+def _read_raw(path: Path) -> Mapping[str, object]:
+    """The file as parsed TOML — ``{}`` if missing, the broken-file screen if corrupt."""
+    if not path.exists():
+        return {}
+    try:
+        return tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise SetupFault(_broken_screen(path, exc)) from exc
+
+
+def _string(data: Mapping[str, object], key: str, path: Path) -> str | None:
+    value = data.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise SetupFault(_wrong_type_screen(path, key, "a string", value))
+    return value
+
+
+def _boolean(data: Mapping[str, object], key: str, path: Path) -> bool | None:
+    value = data.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, bool):
+        raise SetupFault(_wrong_type_screen(path, key, "true or false", value))
+    return value
+
+
+def _positive_int(data: Mapping[str, object], key: str, path: Path) -> int | None:
+    value = data.get(key)
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise SetupFault(_wrong_type_screen(path, key, "a whole number ≥ 1", value))
+    return value
+
+
+def _broken_screen(path: Path, exc: tomllib.TOMLDecodeError) -> str:
+    detail = str(exc)
+    located = re.search(r"at line (\d+)", detail)
+    location = f", line {located.group(1)}" if located else ""
+    detail = re.sub(r"\s*\(at line [^)]*\)$", "", detail)
+    return (
+        "error: config file has a syntax error\n"
+        f"  {human_path(path)}{location}: {detail}\n"
+        "  Fix the line, or start fresh: smartpipe config"
+    )
+
+
+def _wrong_type_screen(path: Path, key: str, expected: str, value: object) -> str:
+    return (
+        f"error: config value '{key}' should be {expected}\n"
+        f"  {human_path(path)} has: {key} = {value!r}\n"
+        f"  Fix the line, or reset it: smartpipe config"
+    )

smartpipe/container.py

@@ -0,0 +1,439 @@
+"""The composition root (design template: intent-finder's ``src/containers.py``).
+
+One place wires every dependency for an invocation: the env snapshot, the loaded
+config, a shared ``httpx.AsyncClient``, the retry policy, and the color mode. Verbs
+receive a built ``AppContainer`` and ask it for ``Protocol``-typed collaborators
+(``ChatModel``, ``EmbeddingModel``, ``ResultWriter``) — they never construct
+adapters or read the environment themselves.
+
+Unlike the template, the wiring is hand-rolled rather than using ``dependency-
+injector``: the core dependency budget is frozen (plan/decisions.md D10), and a
+CLI's composition root is small enough that a frozen dataclass of factory methods
+is clearer than a container framework.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, assert_never
+
+from smartpipe.cli import screens
+from smartpipe.config.paths import config_path
+from smartpipe.config.store import Config, load_config
+from smartpipe.core.errors import SetupFault, UsageFault
+from smartpipe.io import diagnostics, tty
+from smartpipe.io.tty import ColorMode
+from smartpipe.io.writers import OutputFormat, WriterConfig, make_writer, resolve_format
+from smartpipe.models.anthropic_adapter import build_anthropic_chat_model
+from smartpipe.models.base import ModelRef, parse_model_ref
+from smartpipe.models.budget import CallBudget, budgeted_chat, budgeted_embed
+from smartpipe.models.http_support import make_client
+from smartpipe.models.ollama import (
+    OllamaChatModel,
+    OllamaEmbeddingModel,
+    ollama_model_names,
+    resolve_host,
+)
+from smartpipe.models.openai_compat import (
+    GEMINI_WIRE,
+    MISTRAL_WIRE,
+    OPENROUTER_WIRE,
+    OpenAIChatModel,
+    OpenAIEmbeddingModel,
+    WireConfig,
+    require_api_key,
+    resolve_base_url,
+)
+from smartpipe.models.resolve import resolve_chat_ref, resolve_embed_ref
+from smartpipe.models.retry import RetryPolicy
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Mapping
+    from typing import TextIO
+
+    import httpx
+
+    from smartpipe.io.writers import ResultWriter
+    from smartpipe.models.base import ChatModel, EmbeddingModel
+    from smartpipe.models.stt import RemoteTranscriber
+
+__all__ = ["AppContainer", "build_container"]
+
+_DEFAULT_CONCURRENCY = 4
+
+
+@dataclass(frozen=True, slots=True)
+class AppContainer:
+    env: Mapping[str, str]
+    config: Config
+    http_client: httpx.AsyncClient
+    retry: RetryPolicy = field(default_factory=RetryPolicy)
+    color_mode: ColorMode = ColorMode.AUTO
+    budget: CallBudget | None = None  # --max-calls (D18); None = uncapped
+    caches: list[object] = field(default_factory=list[object])  # CachingChatModel wrappers (D38/15)
+    window_cache: dict[str, int | None] = field(default_factory=dict[str, "int | None"])
+
+    async def chat_model(self, flag: str | None = None) -> ChatModel:
+        resolved = await resolve_chat_ref(flag, self.env, self.config, self.probe_ollama)
+        if resolved.notice is not None:
+            diagnostics.note(resolved.notice)
+        model = self._build_chat(resolved.ref)
+        wired = model if self.budget is None else budgeted_chat(model, self.budget)
+        if not _cache_enabled(self.env, self.config):
+            return wired
+        # cache OUTERMOST: a hit short-circuits before the budget counts it —
+        # the belt caps SPEND, not answers (D38/15)
+        from smartpipe.models.cache import CachingChatModel
+
+        wrapper = CachingChatModel(wired, _cache_dir(self.env))
+        self.caches.append(wrapper)
+        return wrapper
+
+    async def context_window(self, ref: ModelRef) -> int | None:
+        """The model's context window: env override > one cached live probe > None
+        (D26 layer 1). Called lazily — only when chunking math needs it."""
+        override = self.env.get("SMARTPIPE_CONTEXT_TOKENS", "").strip()
+        if override:
+            if not override.isdigit():
+                raise SetupFault(
+                    f"error: SMARTPIPE_CONTEXT_TOKENS must be a token count, got {override!r}\n"
+                    "  Example: SMARTPIPE_CONTEXT_TOKENS=32000"
+                )
+            return int(override)
+        key = f"{ref.provider}/{ref.name}"
+        if key not in self.window_cache:
+            from smartpipe.models.windows import probe_context_window
+
+            self.window_cache[key] = await probe_context_window(
+                ref, client=self.http_client, env=self.env
+            )
+        return self.window_cache[key]
+
+    async def embedding_model(self, flag: str | None = None) -> EmbeddingModel:
+        model = self._build_embed(resolve_embed_ref(flag, self.env, self.config))
+        return model if self.budget is None else budgeted_embed(model, self.budget)
+
+    def remote_transcriber(self, chat_ref: ModelRef | None = None) -> RemoteTranscriber | None:
+        """The stt-model role (D39/05): explicit env/config wins; otherwise the
+        owner's auto-matrix — an openai KEY means whisper-1 (the API supports
+        it; ChatGPT-login does not, so OAuth-only stays local); gemini hears
+        natively (no preemption); ollama has no STT (local whisper)."""
+        raw = self.env.get("SMARTPIPE_STT_MODEL", "").strip() or (self.config.stt_model or "")
+        if not raw:
+            if (
+                chat_ref is not None
+                and chat_ref.provider == "openai"
+                and self.env.get("OPENAI_API_KEY", "").strip()
+            ):
+                raw = "openai/whisper-1"  # the key wire supports transcriptions
+            else:
+                return None
+        ref = parse_model_ref(raw)
+        if ref.provider != "openai":
+            raise SetupFault(
+                f"error: no STT wire for {ref.provider!r} yet\n"
+                "  Remote transcription supports openai models: "
+                "smartpipe config stt-model openai/whisper-1"
+            )
+        key = self.env.get("OPENAI_API_KEY", "").strip()
+        if not key:
+            raise SetupFault(
+                "error: remote transcription needs OPENAI_API_KEY\n"
+                "  export OPENAI_API_KEY=sk-…   (or unset stt-model to use the ladder)"
+            )
+        from smartpipe.models.stt import RemoteTranscriber
+
+        return RemoteTranscriber(ref=ref, client=self.http_client, api_key=key, retry=self.retry)
+
+    def concurrency(self, flag: int | None = None) -> int:
+        """Max parallel model calls: flag > SMARTPIPE_CONCURRENCY > config > default 4."""
+        if flag is not None:
+            if flag < 1:
+                raise UsageFault(f"--concurrency must be >= 1, got {flag}")
+            return flag
+        env_value = self.env.get("SMARTPIPE_CONCURRENCY", "").strip()
+        if env_value:
+            if not (env_value.isdigit() and int(env_value) >= 1):
+                raise UsageFault(
+                    f"SMARTPIPE_CONCURRENCY must be a whole number >= 1, got {env_value!r}"
+                )
+            return int(env_value)
+        if self.config.concurrency is not None:
+            return self.config.concurrency
+        return _DEFAULT_CONCURRENCY
+
+    def writer(
+        self,
+        output_flag: OutputFormat,
+        *,
+        structured: bool,
+        stdout: TextIO,
+        fields: tuple[str, ...] | None = None,
+    ) -> ResultWriter:
+        mode = resolve_format(
+            output_flag,
+            self.env,
+            stdout_tty=tty.stdout_is_tty(),
+            structured=structured,
+            fields=fields,
+        )
+        config = WriterConfig(
+            mode=mode,
+            color=tty.stdout_supports_color(self.color_mode),
+            width=tty.terminal_width(),
+            fields=fields,
+        )
+        return make_writer(config, stdout)
+
+    def _build_openai_chat(self, ref: ModelRef) -> ChatModel:
+        """D19 precedence: an explicit API key (billable, deliberate) always wins;
+        else a stored ChatGPT login rides the codex wire; else the dual-fix screen."""
+        if self.env.get("OPENAI_API_KEY", "").strip():
+            return OpenAIChatModel(
+                ref=ref,
+                client=self.http_client,
+                base_url=resolve_base_url(self.env),
+                api_key=require_api_key(self.env, ref.name),
+                retry=self.retry,
+            )
+        from smartpipe.config.credentials import credentials_path, load_oauth
+
+        store = credentials_path(self.env)
+        credential = load_oauth(store, "openai")
+        if credential is not None:
+            from smartpipe.models.openai_codex import CodexChatModel
+
+            return CodexChatModel(
+                ref=ref, client=self.http_client, store_path=store, credential=credential
+            )
+        raise SetupFault(screens.openai_needs_key_or_login(ref.name))
+
+    def _build_openai_embed(self, ref: ModelRef) -> EmbeddingModel:
+        if not self.env.get("OPENAI_API_KEY", "").strip():
+            from smartpipe.config.credentials import credentials_path, load_oauth
+
+            if load_oauth(credentials_path(self.env), "openai") is not None:
+                raise SetupFault(screens.EMBEDDINGS_NEED_KEY)  # the login wire has no embeddings
+        return OpenAIEmbeddingModel(
+            ref=ref,
+            client=self.http_client,
+            base_url=resolve_base_url(self.env),
+            api_key=require_api_key(self.env, ref.name),
+            retry=self.retry,
+        )
+
+    def _build_chat(self, ref: ModelRef) -> ChatModel:
+        match ref.provider:
+            case "ollama":
+                return OllamaChatModel(
+                    ref=ref,
+                    client=self.http_client,
+                    host=resolve_host(self.env),
+                    retry=self.retry,
+                )
+            case "openai":
+                return self._build_openai_chat(ref)
+            case "anthropic":
+                return build_anthropic_chat_model(ref)
+            case "mistral":  # the parametrized OpenAI wire (workstream 10)
+                return self._wire_chat(ref, MISTRAL_WIRE)
+            case "jina" | "local":
+                raise SetupFault(
+                    f"error: '{ref.name}' is an embedding model, not a chat model\n"
+                    "  Pick a chat model instead: smartpipe config model …"
+                )
+            case "gemini":  # D34: chat rides the NATIVE wire — the one that watches video
+                from smartpipe.models.gemini_native import GeminiNativeChatModel, native_base_url
+                from smartpipe.models.openai_compat import require_api_key
+
+                return GeminiNativeChatModel(
+                    ref=ref,
+                    client=self.http_client,
+                    base_url=native_base_url(self.env),
+                    api_key=require_api_key(self.env, ref.name, GEMINI_WIRE),
+                    retry=self.retry,
+                )
+            case "openrouter":
+                return self._wire_chat(ref, OPENROUTER_WIRE)
+            case _ as unreachable:  # pragma: no cover — pyright proves exhaustiveness
+                assert_never(unreachable)
+
+    def _wire_chat(self, ref: ModelRef, wire: WireConfig) -> ChatModel:
+        return OpenAIChatModel(
+            ref=ref,
+            client=self.http_client,
+            base_url=resolve_base_url(self.env, wire),
+            api_key=require_api_key(self.env, ref.name, wire),
+            retry=self.retry,
+            wire=wire,
+        )
+
+    def _wire_embed(self, ref: ModelRef, wire: WireConfig) -> EmbeddingModel:
+        return OpenAIEmbeddingModel(
+            ref=ref,
+            client=self.http_client,
+            base_url=resolve_base_url(self.env, wire),
+            api_key=require_api_key(self.env, ref.name, wire),
+            retry=self.retry,
+            wire=wire,
+        )
+
+    def _build_embed(self, ref: ModelRef) -> EmbeddingModel:
+        match ref.provider:
+            case "local":  # D44: the on-device default — no server, no key
+                from smartpipe.models.local_embed import LocalEmbeddingModel
+
+                return LocalEmbeddingModel(ref=ref)
+            case "ollama":
+                return OllamaEmbeddingModel(
+                    ref=ref,
+                    client=self.http_client,
+                    host=resolve_host(self.env),
+                    retry=self.retry,
+                )
+            case "openai":
+                return self._build_openai_embed(ref)
+            case "anthropic":
+                raise SetupFault(
+                    f"error: '{ref.name}' is a chat model, not an embedding model\n"
+                    "  Claude models don't provide embeddings. Use a local one:\n"
+                    "  smartpipe config embed-model nomic-embed-text"
+                )
+            case "mistral":  # mistral-embed rides the same /v1/embeddings wire
+                return self._wire_embed(ref, MISTRAL_WIRE)
+            case "gemini":
+                return self._wire_embed(ref, GEMINI_WIRE)
+            case "openrouter":
+                return self._wire_embed(ref, OPENROUTER_WIRE)
+            case "jina":  # D39/04: the media-native space (text + images)
+                key = self.env.get("JINA_API_KEY", "").strip()
+                if not key:
+                    raise SetupFault(
+                        "error: Jina needs an API key\n  export JINA_API_KEY=…   (https://jina.ai)"
+                    )
+                from smartpipe.models.jina import JINA_BASE_URL, JinaClipEmbeddingModel
+
+                base = self.env.get("SMARTPIPE_JINA_BASE_URL", "").strip().rstrip("/")
+                return JinaClipEmbeddingModel(
+                    ref=ref,
+                    client=self.http_client,
+                    api_key=key,
+                    base_url=base or JINA_BASE_URL,
+                    retry=self.retry,
+                )
+            case _ as unreachable:  # pragma: no cover — pyright proves exhaustiveness
+                assert_never(unreachable)
+
+    async def probe_ollama(self) -> tuple[str, ...] | None:
+        """Installed ollama model names, or None if nothing is listening."""
+        return await ollama_model_names(self.http_client, resolve_host(self.env))
+
+
+def _resolve_max_calls(environ: Mapping[str, str], flag: int | None) -> int | None:
+    """--max-calls > SMARTPIPE_MAX_CALLS > uncapped; bad values are loud (D18)."""
+    if flag is not None:
+        if flag < 1:
+            raise UsageFault(f"--max-calls must be >= 1, got {flag}")
+        return flag
+    env_value = environ.get("SMARTPIPE_MAX_CALLS", "").strip()
+    if not env_value:
+        return None
+    if not (env_value.isdigit() and int(env_value) >= 1):
+        raise UsageFault(f"SMARTPIPE_MAX_CALLS must be a whole number >= 1, got {env_value!r}")
+    return int(env_value)
+
+
+def _cache_enabled(env: Mapping[str, str], config: Config) -> bool:
+    flag = env.get("SMARTPIPE_CACHE", "").strip().lower()
+    if flag in ("1", "true", "on", "yes"):
+        return True
+    if flag in ("0", "false", "off", "no"):
+        return False
+    return bool(config.cache)
+
+
+def _cache_dir(env: Mapping[str, str]) -> Path:
+    base = env.get("XDG_CACHE_HOME", "").strip()
+    root = Path(base) if base else Path.home() / ".cache"
+    return root / "smartpipe" / "results"
+
+
+@asynccontextmanager
+async def build_container(
+    environ: Mapping[str, str],
+    *,
+    color_mode: ColorMode = ColorMode.AUTO,
+    max_calls: int | None = None,
+    stop: asyncio.Event | None = None,
+) -> AsyncGenerator[AppContainer]:
+    """Build the container for one invocation and own the HTTP client's lifecycle.
+
+    ``stop`` is the drain event of the per-item verbs: a tripped call budget stops
+    intake through it. Whole-set verbs pass no stop — exhaustion there is fatal.
+    """
+    limit = _resolve_max_calls(environ, max_calls)
+    config = load_config(config_path(environ), environ)
+    client = make_client()
+    from smartpipe.io import metering
+
+    metering.reset()  # a fresh run's meter (D40)
+    container = AppContainer(
+        env=dict(environ),
+        config=config,
+        http_client=client,
+        color_mode=color_mode,
+        budget=None if limit is None else CallBudget(limit=limit, stop=stop),
+    )
+    try:
+        yield container
+    finally:
+        await client.aclose()
+        totals = metering.receipt()
+        if totals is not None:
+            diagnostics.note(totals)  # D40: the number that goes in the report
+        from smartpipe.io import usage
+
+        usage.record_run(metering.snapshot(), container.env)  # D41: the ledger
+        _cache_receipt(container)
+
+
+def _cache_receipt(container: AppContainer) -> None:
+    from smartpipe.models.cache import CachingChatModel
+
+    hits = sum(w.hits for w in container.caches if isinstance(w, CachingChatModel))
+    misses = sum(w.misses for w in container.caches if isinstance(w, CachingChatModel))
+    if hits or misses:
+        diagnostics.note(f"cache: {hits:,} hits · {misses:,} calls")
+    if container.caches:
+        _maybe_sweep(container)
+
+
+def _maybe_sweep(container: AppContainer) -> None:
+    """TTL + LRU sweep at exit, at most daily — the cache is never the user's
+    problem (D39/02). Any filesystem trouble is swallowed: a broken cache dir
+    must never fail a run."""
+    import time
+
+    from smartpipe.models.cache import sweep
+
+    directory = _cache_dir(container.env)
+    marker = directory / "last-sweep"
+    try:
+        now = time.time()
+        if marker.exists() and now - marker.stat().st_mtime < 86_400:
+            return
+        directory.mkdir(parents=True, exist_ok=True)
+        marker.write_text("", encoding="utf-8")
+        removed, freed = sweep(
+            directory,
+            ttl_days=container.config.cache_days or 30,
+            max_mb=container.config.cache_max_mb or 500,
+            now=now,
+        )
+        if removed:
+            diagnostics.note(f"cache: swept {removed:,} entries ({freed / 1_048_576:.1f} MB)")
+    except OSError:
+        return

smartpipe/core/__init__.py

@@ -0,0 +1,5 @@
+"""Shared value types, errors, and exit codes."""
+
+from __future__ import annotations
+
+__all__: list[str] = []