thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core/reasoning_plus/augmenter.py

@@ -0,0 +1,337 @@
+"""
+thinkstack_core.reasoning_plus.augmenter
+======================================
+High-level Reasoning Plus orchestrator.
+
+- Decides whether to augment based on config and workspace state.
+- Builds the augmented system prompt (RACP + smart context + reasoning directive).
+- Captures inline <thinking> blocks from the response and strips them before returning.
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+from pathlib import Path
+from typing import Any
+
+from thinkstack_core.reasoning_plus.capture import (
+    commit_reasoning,
+    extract_inline_thinking,
+    strip_inline_thinking,
+)
+from thinkstack_core.reasoning_plus.config import ReasoningPlusConfig, SettingsStore
+from thinkstack_core.reasoning_plus.context import gather_smart_context
+from thinkstack_core.reasoning_plus.learning import ReasoningPlusLearning
+from thinkstack_core.reasoning_plus.prompt import build_reasoning_plus_system_prompt
+
+logger = logging.getLogger("thinkstack.reasoning_plus")
+
+
+class ReasoningPlusAugmenter:
+    """
+    Per-repo augmenter. Caches smart context and config for performance.
+
+    Usage:
+        augmenter = ReasoningPlusAugmenter(repo_path)
+        if augmenter.should_augment():
+            system_prompt = augmenter.build_system_prompt(base_prompt, user_text)
+        clean_text = augmenter.capture_and_strip(raw_text, session_id, user_text)
+    """
+
+    def __init__(
+        self,
+        repo_path: Path | str,
+        gcc_repo: Any | None = None,
+        config: ReasoningPlusConfig | None = None,
+    ) -> None:
+        self._repo_path = Path(repo_path)
+        self._gcc_repo = gcc_repo
+
+        # If a gcc_repo object is supplied, prefer its gcc_dir for settings.
+        gcc_dir = getattr(gcc_repo, "gcc_dir", None)
+        self._store = SettingsStore(gcc_dir)
+        self._config, self._config_source = (
+            (config, "provided") if config is not None else self._store.load()
+        )
+
+        # Learning layer: only if a gcc_dir is available and learning is enabled.
+        self._learning: ReasoningPlusLearning | None = None
+        if gcc_dir and self._config.learning_enabled:
+            try:
+                self._learning = ReasoningPlusLearning(
+                    gcc_dir=gcc_dir,
+                    repo_path=self._repo_path,
+                    config=self._config,
+                )
+            except Exception as exc:
+                logger.warning("thinkstack: failed to initialize learning layer — %s", exc)
+
+        # Cache: prompt hash -> (contents, timestamp)
+        self._cache: dict[str, tuple[str, float]] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def config(self) -> ReasoningPlusConfig:
+        return self._config
+
+    @property
+    def config_source(self) -> str:
+        return self._config_source
+
+    def should_augment(self) -> bool:
+        """Return True if Reasoning Plus should be applied to this call."""
+        if not self._config.enabled:
+            return False
+        # Must be a git repo to gather smart context
+        return self._is_git_repo()
+
+    def build_system_prompt(
+        self,
+        base_prompt: str,
+        prompt_text_for_context: str | None = None,
+        *,
+        task_prompt: str = "",
+    ) -> str:
+        """
+        Return a Reasoning Plus system prompt.
+
+        If the augmenter is disabled, returns `base_prompt` unchanged.
+        """
+        if not self._config.enabled:
+            return base_prompt
+
+        smart_context = ""
+        if prompt_text_for_context:
+            smart_context = self._get_cached_smart_context(prompt_text_for_context)
+
+        return build_reasoning_plus_system_prompt(
+            base_prompt,
+            smart_context=smart_context,
+            require_thinking=self._config.require_thinking,
+            task_prompt=task_prompt,
+        )
+
+    def capture_and_strip(
+        self,
+        response_text: str,
+        session_id: str,
+        prompt_text: str | None = None,
+    ) -> str:
+        """
+        Extract inline reasoning from the response, commit it, and return text
+        with the <thinking> blocks stripped.
+        """
+        if not self._config.enabled:
+            return response_text
+
+        thinking_blocks = extract_inline_thinking(response_text)
+        if thinking_blocks:
+            combined = "\n\n".join(thinking_blocks)
+            try:
+                commit_reasoning(
+                    self._gcc_repo,
+                    combined,
+                    session_id,
+                    prompt_text or "",
+                )
+            except Exception as exc:
+                logger.warning("thinkstack: reasoning_plus capture failed — %s", exc)
+
+        cleaned_text = strip_inline_thinking(response_text)
+
+        # Record this LLM call in the learning layer so its reasoning can be reused.
+        if self._learning and thinking_blocks:
+            try:
+                call_id = self._learning.record_call(
+                    call_type="llm",
+                    reasoning="\n\n".join(thinking_blocks),
+                    input=prompt_text or "",
+                    output=cleaned_text,
+                    outcome="unknown",
+                    session_id=session_id,
+                )
+                self._learning.queue_extraction(call_id)
+            except Exception as exc:
+                logger.warning("thinkstack: learning layer recording failed — %s", exc)
+
+        return cleaned_text
+
+    def get_learning_context(self, context: str, session_id: str = "") -> str:
+        """
+        Return a compact <learnings> block for the given context, or "" if none.
+
+        Callers should append the returned block to the user prompt.
+        """
+        block, _ = self.get_learning_context_with_provenance(context, session_id=session_id)
+        return block
+
+    def get_learning_context_with_provenance(
+        self,
+        context: str,
+        session_id: str = "",
+        call_id: str = "",
+        model_name: str = "",
+    ) -> tuple[str, list[str]]:
+        """
+        Return a compact <learnings> block plus the IDs of injected learnings.
+
+        If *call_id* is provided, a provenance record is saved so outcomes can be
+        attributed back to the injected learnings.
+        """
+        if not self._learning:
+            return "", []
+        try:
+            learnings = self._learning.get_relevant_learnings(
+                context,
+                top_n=self._config.learning_top_n,
+            )
+            block = self._learning.compose_user_prompt("", learnings).strip()
+            learning_ids = [l.id for l in learnings]
+            if call_id and learning_ids:
+                self._learning.record_injection(
+                    learning_ids,
+                    call_id=call_id,
+                    session_id=session_id,
+                    prompt_text=context,
+                    model_name=model_name,
+                )
+            return block, learning_ids
+        except Exception as exc:
+            logger.warning("thinkstack: learning context retrieval failed — %s", exc)
+            return "", []
+
+    def build_system_prompt_with_learning_context(
+        self,
+        base_prompt: str,
+        prompt_text_for_context: str | None = None,
+        *,
+        task_prompt: str = "",
+        call_id: str = "",
+        session_id: str = "",
+        model_name: str = "",
+    ) -> tuple[str, list[str]]:
+        """
+        Build a Reasoning Plus system prompt and append relevant learnings.
+
+        Returns the augmented prompt and the list of learning IDs that were
+        injected (if any). A provenance record is written when *call_id* is set.
+        """
+        system_prompt = self.build_system_prompt(
+            base_prompt,
+            prompt_text_for_context=prompt_text_for_context,
+            task_prompt=task_prompt,
+        )
+        learning_ids: list[str] = []
+        if prompt_text_for_context:
+            block, learning_ids = self.get_learning_context_with_provenance(
+                prompt_text_for_context,
+                session_id=session_id,
+                call_id=call_id,
+                model_name=model_name,
+            )
+            if block:
+                system_prompt = f"{system_prompt}\n\n[ThinkStack learnings]\n{block}"
+        return system_prompt, learning_ids
+
+    def record_learning_call(
+        self,
+        *,
+        call_type: str,
+        reasoning: str,
+        session_id: str = "",
+        name: str = "",
+        input: str = "",
+        output: str = "",
+        outcome: str = "unknown",
+    ) -> str:
+        """
+        Record a tool/memory/action call in the learning layer.
+
+        Returns the call ID so the caller can apply feedback later.
+        """
+        if not self._learning:
+            return ""
+        try:
+            return self._learning.record_call(
+                call_type=call_type,
+                reasoning=reasoning,
+                session_id=session_id,
+                name=name,
+                input=input,
+                output=output,
+                outcome=outcome,
+            )
+        except Exception as exc:
+            logger.warning("thinkstack: learning call recording failed — %s", exc)
+            return ""
+
+    def flush_learnings(self) -> int:
+        """Flush any pending batch extractions. Returns number of learning IDs extracted."""
+        if not self._learning:
+            return 0
+        try:
+            ids = self._learning.flush_extractions()
+            return len(ids)
+        except Exception as exc:
+            logger.warning("thinkstack: learning flush failed — %s", exc)
+            return 0
+
+    def invalidate_cache(self) -> None:
+        """Clear the smart context cache (call after a thinkstack commit)."""
+        self._cache.clear()
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _get_cached_smart_context(self, prompt_text: str) -> str:
+        """Return cached smart context, or gather and cache it."""
+        prompt_hash = _hash_prompt(prompt_text)
+        now = time.monotonic()
+        ttl = self._config.cache_ttl_secs
+
+        cached = self._cache.get(prompt_hash)
+        if cached and (now - cached[1]) < ttl:
+            return cached[0]
+
+        _, contents = gather_smart_context(
+            self._repo_path,
+            prompt_text,
+            top_n=self._config.smart_top_n,
+            max_lines=self._config.smart_max_lines,
+            max_keywords=self._config.max_keywords,
+        )
+        self._cache[prompt_hash] = (contents, now)
+        return contents
+
+    def _is_git_repo(self) -> bool:
+        try:
+            import subprocess
+            result = subprocess.run(
+                ["git", "rev-parse", "--git-dir"],
+                cwd=self._repo_path,
+                capture_output=True,
+                text=True,
+                errors="ignore",
+                timeout=5,
+            )
+            return result.returncode == 0 and result.stdout.strip() != ""
+        except Exception:
+            return False
+
+
+def _hash_prompt(prompt_text: str) -> str:
+    """Stable hash for cache keys."""
+    return hashlib.sha256(prompt_text.encode("utf-8")).hexdigest()[:16]
+
+
+def is_enabled(repo_path: Path | None = None) -> bool:
+    """Convenience helper: is Reasoning Plus enabled for the given repo path?"""
+    if not repo_path:
+        config, _ = SettingsStore().load()
+        return config.enabled
+    return ReasoningPlusAugmenter(repo_path).should_augment()

thinkstack_core/reasoning_plus/capture.py

@@ -0,0 +1,51 @@
+"""
+thinkstack_core.reasoning_plus.capture
+====================================
+Extract inline <thinking> blocks from LLM output and commit them to .GCC/.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+logger = logging.getLogger("thinkstack.reasoning_plus")
+
+_THINKING_RE = re.compile(r"<thinking>(.*?)</thinking>", re.DOTALL | re.IGNORECASE)
+
+
+def extract_inline_thinking(text: str) -> list[str]:
+    """Return all <thinking>...</thinking> bodies found in `text`."""
+    return [m.strip() for m in _THINKING_RE.findall(text or "")]
+
+
+def strip_inline_thinking(text: str) -> str:
+    """Remove <thinking>...</thinking> blocks from `text` and collapse whitespace."""
+    cleaned = _THINKING_RE.sub("\n", text or "")
+    # Collapse multiple blank lines introduced by stripping
+    cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
+    return cleaned.strip()
+
+
+def commit_reasoning(
+    repo: Any,
+    reasoning_text: str,
+    session_id: str,
+    prompt_text: str = "",
+) -> None:
+    """
+    Commit a reasoning block to .GCC/ via the standard repo.commit() primitive.
+
+    This keeps the same audit path as all other ThinkStack captures.
+    """
+    try:
+        summary = reasoning_text.strip().replace("\n", " ")[:200]
+        prompt_summary = prompt_text.strip().replace("\n", " ")[:100]
+        message = (
+            f"[session={session_id}] reasoning_plus(conf=1.0): {summary}"
+        )
+        if prompt_summary:
+            message += f" | prompt: {prompt_summary}"
+        repo.commit(message=message)
+    except Exception as exc:
+        logger.warning("thinkstack: failed to commit reasoning — %s", exc)

thinkstack_core/reasoning_plus/config.py

@@ -0,0 +1,313 @@
+"""
+thinkstack_core.reasoning_plus.config
+=================================
+Configuration and settings for Reasoning Plus.
+
+Resolution order (highest priority first):
+  1. THINKSTACK_REASONING_PLUS env var (0/1).
+  2. Per-project .GCC/settings.json.
+  3. Global ~/.thinkstack/settings.json.
+  4. Built-in defaults (enabled by default).
+
+All settings access is defensive: malformed JSON or missing files return
+defaults so that wrappers never fail because of config errors.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("thinkstack.reasoning_plus")
+
+REASONING_PLUS_ENV_VAR = "THINKSTACK_REASONING_PLUS"
+GLOBAL_SETTINGS_DIR = Path.home() / ".thinkstack"
+GLOBAL_SETTINGS_PATH = GLOBAL_SETTINGS_DIR / "settings.json"
+PROJECT_SETTINGS_FILENAME = "settings.json"
+
+
+@dataclass
+class ReasoningPlusConfig:
+    """Immutable-ish configuration for Reasoning Plus.
+
+    Use `with_values()` to create a copy with selected overrides.
+    """
+
+    enabled: bool = True
+    smart_top_n: int = 3
+    smart_max_lines: int = 150
+    context_k: int = 4000
+    require_thinking: bool = True
+    max_keywords: int = 15
+    cache_ttl_secs: int = 60
+    learning_enabled: bool = True
+    learning_top_n: int = 3
+    learning_max_lines: int = 100
+    learning_embedding_backend: str = "keyword"
+    learning_embedding_model: str | None = None
+    learning_extraction_strategy: str = "rule"
+    learning_extraction_model: str = "claude-3-haiku-20240307"
+    learning_relevance_cache_ttl: int = 60
+    learning_batch_threshold: int = 5
+    learning_token_budget: int = 500
+    learning_relevance_threshold: float = 0.4
+    disclosure_policy: str = "standard"
+    learning_cross_project_enabled: bool = True
+    learning_org_sync_enabled: bool = True
+    learning_cross_project_top_n: int = 3
+    learning_max_org_learnings_per_call: int = 5
+    auto_sync_enabled: bool = True
+    auto_sync_interval_secs: int = 300
+    auto_sync_on_tool_use: bool = True
+    auto_sync_on_startup: bool = True
+    auto_sync_on_stop: bool = True
+
+    def with_values(self, **kwargs: Any) -> "ReasoningPlusConfig":
+        """Return a new config with the provided field overrides."""
+        valid = {f.name for f in fields(self)}
+        extra = set(kwargs) - valid
+        if extra:
+            raise ValueError(f"Unknown ReasoningPlusConfig fields: {extra}")
+        return ReasoningPlusConfig(
+            **{f.name: kwargs.get(f.name, getattr(self, f.name)) for f in fields(self)}
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "enabled": self.enabled,
+            "smart_top_n": self.smart_top_n,
+            "smart_max_lines": self.smart_max_lines,
+            "context_k": self.context_k,
+            "require_thinking": self.require_thinking,
+            "max_keywords": self.max_keywords,
+            "cache_ttl_secs": self.cache_ttl_secs,
+            "learning_enabled": self.learning_enabled,
+            "learning_top_n": self.learning_top_n,
+            "learning_max_lines": self.learning_max_lines,
+            "learning_embedding_backend": self.learning_embedding_backend,
+            "learning_embedding_model": self.learning_embedding_model,
+            "learning_extraction_strategy": self.learning_extraction_strategy,
+            "learning_extraction_model": self.learning_extraction_model,
+            "learning_relevance_cache_ttl": self.learning_relevance_cache_ttl,
+            "learning_batch_threshold": self.learning_batch_threshold,
+            "learning_token_budget": self.learning_token_budget,
+            "learning_relevance_threshold": self.learning_relevance_threshold,
+            "disclosure_policy": self.disclosure_policy,
+            "learning_cross_project_enabled": self.learning_cross_project_enabled,
+            "learning_org_sync_enabled": self.learning_org_sync_enabled,
+            "learning_cross_project_top_n": self.learning_cross_project_top_n,
+            "learning_max_org_learnings_per_call": self.learning_max_org_learnings_per_call,
+            "auto_sync_enabled": self.auto_sync_enabled,
+            "auto_sync_interval_secs": self.auto_sync_interval_secs,
+            "auto_sync_on_tool_use": self.auto_sync_on_tool_use,
+            "auto_sync_on_startup": self.auto_sync_on_startup,
+            "auto_sync_on_stop": self.auto_sync_on_stop,
+        }
+
+    @classmethod
+    def _validate_disclosure_policy(cls, value: str, default: str = "standard") -> str:
+        _VALID = frozenset({"strict", "standard", "permissive"})
+        if value in _VALID:
+            return value
+        logger.warning("thinkstack: invalid disclosure_policy '%s' — falling back to '%s'", value, default)
+        return default
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ReasoningPlusConfig":
+        """Build from a dict, ignoring unknown keys and using defaults for missing ones."""
+        return cls(
+            enabled=_bool(data.get("enabled", True)),
+            smart_top_n=_int(data.get("smart_top_n", 3), 3),
+            smart_max_lines=_int(data.get("smart_max_lines", 150), 150),
+            context_k=_int(data.get("context_k", 4000), 4000),
+            require_thinking=_bool(data.get("require_thinking", True)),
+            max_keywords=_int(data.get("max_keywords", 15), 15),
+            cache_ttl_secs=_int(data.get("cache_ttl_secs", 60), 60),
+            learning_enabled=_bool(data.get("learning_enabled", True)),
+            learning_top_n=_int(data.get("learning_top_n", 3), 3),
+            learning_max_lines=_int(data.get("learning_max_lines", 100), 100),
+            learning_embedding_backend=_str(data.get("learning_embedding_backend", "keyword"), "keyword"),
+            learning_embedding_model=_optional_str(data.get("learning_embedding_model")),
+            learning_extraction_strategy=_str(data.get("learning_extraction_strategy", "rule"), "rule"),
+            learning_extraction_model=_str(data.get("learning_extraction_model", "claude-3-haiku-20240307"), "claude-3-haiku-20240307"),
+            learning_relevance_cache_ttl=_int(data.get("learning_relevance_cache_ttl", 60), 60),
+            learning_batch_threshold=_int(data.get("learning_batch_threshold", 5), 5),
+            learning_token_budget=_int(data.get("learning_token_budget", 500), 500),
+            learning_relevance_threshold=_float(data.get("learning_relevance_threshold", 0.4), 0.4),
+            disclosure_policy=cls._validate_disclosure_policy(_str(data.get("disclosure_policy", "standard"), "standard")),
+            learning_cross_project_enabled=_bool(data.get("learning_cross_project_enabled", True)),
+            learning_org_sync_enabled=_bool(data.get("learning_org_sync_enabled", True)),
+            learning_cross_project_top_n=_int(data.get("learning_cross_project_top_n", 3), 3),
+            learning_max_org_learnings_per_call=_int(data.get("learning_max_org_learnings_per_call", 5), 5),
+            auto_sync_enabled=_bool(data.get("auto_sync_enabled", True)),
+            auto_sync_interval_secs=_int(data.get("auto_sync_interval_secs", 300), 300),
+            auto_sync_on_tool_use=_bool(data.get("auto_sync_on_tool_use", True)),
+            auto_sync_on_startup=_bool(data.get("auto_sync_on_startup", True)),
+            auto_sync_on_stop=_bool(data.get("auto_sync_on_stop", True)),
+        )
+
+
+class SettingsStore:
+    """Read and write Reasoning Plus settings at project and global levels."""
+
+    def __init__(self, gcc_dir: Path | None = None) -> None:
+        self._project_dir = gcc_dir
+        self._global_path = GLOBAL_SETTINGS_PATH
+
+    # ------------------------------------------------------------------
+    # Read
+    # ------------------------------------------------------------------
+
+    def load(self) -> tuple[ReasoningPlusConfig, str]:
+        """Return (config, source) where source describes where the config came from."""
+        # 1. Env var (highest priority)
+        env_val = os.environ.get(REASONING_PLUS_ENV_VAR, "").strip()
+        if env_val:
+            enabled = env_val in ("1", "true", "yes", "on")
+            config = ReasoningPlusConfig(enabled=enabled)
+            return config, "environment"
+
+        # 2. Project settings
+        project = self._read_project_settings()
+        if project is not None:
+            return ReasoningPlusConfig.from_dict(project.get("reasoning_plus", {})), "project"
+
+        # 3. Global settings
+        global_ = self._read_global_settings()
+        if global_ is not None:
+            return ReasoningPlusConfig.from_dict(global_.get("reasoning_plus", {})), "global"
+
+        # 4. Defaults
+        return ReasoningPlusConfig(), "default"
+
+    def _read_project_settings(self) -> dict[str, Any] | None:
+        if not self._project_dir:
+            return None
+        path = self._project_dir / PROJECT_SETTINGS_FILENAME
+        return _read_json(path)
+
+    def _read_global_settings(self) -> dict[str, Any] | None:
+        return _read_json(self._global_path)
+
+    # ------------------------------------------------------------------
+    # Write
+    # ------------------------------------------------------------------
+
+    def save_project(self, config: ReasoningPlusConfig) -> None:
+        """Write the Reasoning Plus section to .GCC/settings.json (creates file if needed)."""
+        if not self._project_dir:
+            raise ValueError("No project directory available for saving settings")
+        self._project_dir.mkdir(parents=True, exist_ok=True)
+        path = self._project_dir / PROJECT_SETTINGS_FILENAME
+        settings = _read_json(path) or {}
+        settings["reasoning_plus"] = config.to_dict()
+        settings.setdefault("version", 1)
+        _write_json(path, settings)
+
+    def save_global(self, config: ReasoningPlusConfig) -> None:
+        """Write the Reasoning Plus section to ~/.thinkstack/settings.json."""
+        GLOBAL_SETTINGS_DIR.mkdir(parents=True, exist_ok=True)
+        settings = _read_json(self._global_path) or {}
+        settings["reasoning_plus"] = config.to_dict()
+        settings.setdefault("version", 1)
+        _write_json(self._global_path, settings)
+
+    def reset_project(self) -> None:
+        """Remove the Reasoning Plus section from project settings.
+
+        If the settings file is empty after removal (only version remains), delete it.
+        """
+        if not self._project_dir:
+            return
+        path = self._project_dir / PROJECT_SETTINGS_FILENAME
+        settings = _read_json(path)
+        if settings and "reasoning_plus" in settings:
+            del settings["reasoning_plus"]
+            remaining_keys = [k for k in settings.keys() if k != "version"]
+            if remaining_keys:
+                _write_json(path, settings)
+            else:
+                try:
+                    path.unlink()
+                except Exception:
+                    pass
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in ("1", "true", "yes", "on")
+    return bool(value)
+
+
+def _int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _float(value: Any, default: float) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _str(value: Any, default: str) -> str:
+    if isinstance(value, str):
+        return value.strip()
+    return default
+
+
+def _optional_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        value = value.strip()
+        return value if value else None
+    return None
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    if not path.exists():
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data
+    except Exception as exc:
+        logger.warning("thinkstack: failed to read settings from %s — %s", path, exc)
+    return None
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+    """Atomic JSON write (temp file + rename)."""
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    try:
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        tmp.replace(path)
+    except Exception as exc:
+        logger.warning("thinkstack: failed to write settings to %s — %s", path, exc)
+        raise
+    finally:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except Exception:
+                pass
+
+
+def load_config(gcc_dir: Path | None = None) -> tuple[ReasoningPlusConfig, str]:
+    """Convenience function: load config + source."""
+    return SettingsStore(gcc_dir).load()