devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/reasoning_plus/learning/models.py

@@ -0,0 +1,116 @@
+"""
+devtorch_core.reasoning_plus.learning.models
+===========================================
+Data models for Reasoning Plus Learning (DRPL).
+
+A ReasoningCall is a single recorded step (LLM, tool, memory, or action).
+A Learning is a distilled, reusable insight derived from one or more calls.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import asdict, dataclass, field, fields
+from datetime import datetime, timezone
+from typing import Any
+
+
+VALID_CALL_TYPES = ("llm", "tool", "memory", "action")
+VALID_OUTCOMES = ("success", "failure", "partial", "unknown")
+VALID_LEARNING_TYPES = ("insight", "correction", "pattern", "avoid", "confirm")
+VALID_VALIDITIES = ("active", "stale", "deprecated")
+VALID_DISCLOSURE_LEVELS = ("PUBLIC", "PROTECTED", "PRIVATE")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _make_id(prefix: str = "drpl") -> str:
+    return f"{prefix}_{uuid.uuid4().hex[:16]}"
+
+
+@dataclass
+class ReasoningCall:
+    """One recorded reasoning step."""
+
+    reasoning: str
+    call_type: str = "llm"
+    name: str = ""
+    input: str = ""
+    output: str = ""
+    outcome: str = "unknown"
+    state_hash: str = ""
+    concepts: list[str] = field(default_factory=list)
+    confidence: float = 1.0
+    sensitivity: str = "PUBLIC"
+    session_id: str = ""
+    timestamp: str = field(default_factory=_now_iso)
+    id: str = field(default_factory=lambda: _make_id("call"))
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.call_type not in VALID_CALL_TYPES:
+            raise ValueError(f"Invalid call_type: {self.call_type}")
+        if self.outcome not in VALID_OUTCOMES:
+            raise ValueError(f"Invalid outcome: {self.outcome}")
+        if self.sensitivity not in VALID_DISCLOSURE_LEVELS:
+            raise ValueError(f"Invalid sensitivity: {self.sensitivity}")
+        self.confidence = max(0.0, min(1.0, float(self.confidence)))
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ReasoningCall":
+        valid = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in valid})
+
+
+@dataclass
+class Learning:
+    """A distilled, reusable learning from one or more reasoning calls."""
+
+    content: str
+    type: str = "insight"
+    trigger_concepts: list[str] = field(default_factory=list)
+    state_hash: str = ""
+    validity: str = "active"
+    confidence: float = 1.0
+    source_reasoning_ids: list[str] = field(default_factory=list)
+    sensitivity: str = "PUBLIC"
+    created_at: str = field(default_factory=_now_iso)
+    updated_at: str = field(default_factory=_now_iso)
+    id: str = field(default_factory=lambda: _make_id("learn"))
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.type not in VALID_LEARNING_TYPES:
+            raise ValueError(f"Invalid learning type: {self.type}")
+        if self.validity not in VALID_VALIDITIES:
+            raise ValueError(f"Invalid validity: {self.validity}")
+        if self.sensitivity not in VALID_DISCLOSURE_LEVELS:
+            raise ValueError(f"Invalid sensitivity: {self.sensitivity}")
+        self.confidence = max(0.0, min(1.0, float(self.confidence)))
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Learning":
+        valid = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in valid})
+
+    def short_form(self, max_chars: int = 200) -> str:
+        """Compact, prompt-ready representation."""
+        text = self.content.strip().replace("\n", " ")
+        if len(text) > max_chars:
+            text = text[: max_chars - 3].rstrip() + "..."
+        return text
+
+
+def hash_state(*items: str) -> str:
+    """Stable hash for a set of state tokens."""
+    joined = "|".join(sorted(items))
+    return hashlib.sha256(joined.encode("utf-8")).hexdigest()[:16]

devtorch_core/reasoning_plus/learning/provenance.py

@@ -0,0 +1,126 @@
+"""
+devtorch_core.reasoning_plus.learning.provenance
+===============================================
+Provenance tracking for injected learnings.
+
+Records which Learning records were injected into each LLM/tool call so that
+observed outcomes can be attributed back to the learnings that influenced the
+call.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from dataclasses import asdict, dataclass, field, fields
+from pathlib import Path
+from typing import Any
+
+from devtorch_core.reasoning_plus.learning.models import _make_id, _now_iso
+
+logger = logging.getLogger("devtorch.reasoning_plus.learning")
+
+
+@dataclass
+class ProvenanceRecord:
+    """Which learnings were injected into a single call, and what the outcome was."""
+
+    call_id: str
+    learning_ids: list[str] = field(default_factory=list)
+    session_id: str = ""
+    prompt_hash: str = ""
+    prompt_excerpt: str = ""
+    model_name: str = ""
+    outcome: str | None = None
+    injected_at: str = field(default_factory=_now_iso)
+    updated_at: str = field(default_factory=_now_iso)
+    id: str = field(default_factory=lambda: _make_id("prov"))
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ProvenanceRecord":
+        valid = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in valid})
+
+
+class ProvenanceStore:
+    """Persist ProvenanceRecord records under .GCC/reasoning_learnings/provenance/."""
+
+    def __init__(self, gcc_dir: Path | str) -> None:
+        self._gcc_dir = Path(gcc_dir)
+        self._provenance_dir = self._gcc_dir / "reasoning_learnings" / "provenance"
+
+    def save(self, record: ProvenanceRecord) -> Path:
+        self._provenance_dir.mkdir(parents=True, exist_ok=True)
+        path = self._provenance_dir / f"{record.id}.json"
+        _atomic_json_write(path, record.to_dict())
+        return path
+
+    def get(self, record_id: str) -> ProvenanceRecord | None:
+        path = self._provenance_dir / f"{record_id}.json"
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return ProvenanceRecord.from_dict(data)
+        except Exception as exc:
+            logger.warning("devtorch: failed to read provenance %s — %s", record_id, exc)
+            return None
+
+    def get_by_call(self, call_id: str) -> ProvenanceRecord | None:
+        for record in self.list():
+            if record.call_id == call_id:
+                return record
+        return None
+
+    def list(self, outcome: str | None = None, learning_id: str | None = None) -> list[ProvenanceRecord]:
+        out: list[ProvenanceRecord] = []
+        if not self._provenance_dir.exists():
+            return out
+        for path in sorted(self._provenance_dir.glob("*.json")):
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                record = ProvenanceRecord.from_dict(data)
+                if outcome and record.outcome != outcome:
+                    continue
+                if learning_id and learning_id not in record.learning_ids:
+                    continue
+                out.append(record)
+            except Exception as exc:
+                logger.debug("devtorch: skipping malformed provenance %s — %s", path, exc)
+        return out
+
+    def update_outcome(self, call_id: str, outcome: str) -> ProvenanceRecord | None:
+        record = self.get_by_call(call_id)
+        if not record:
+            return None
+        record.outcome = outcome
+        record.updated_at = _now_iso()
+        self.save(record)
+        return record
+
+    def count(self) -> int:
+        if not self._provenance_dir.exists():
+            return 0
+        return len(list(self._provenance_dir.glob("*.json")))
+
+
+def _atomic_json_write(path: Path, data: dict[str, Any]) -> None:
+    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)
+    finally:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except Exception:
+                pass
+
+
+def _hash_prompt(prompt_text: str) -> str:
+    return hashlib.sha256(prompt_text.encode("utf-8")).hexdigest()[:16]

devtorch_core/reasoning_plus/learning/recorder.py

@@ -0,0 +1,81 @@
+"""
+devtorch_core.reasoning_plus.learning.recorder
+==============================================
+Record reasoning calls (LLM, tool, memory, action) to .GCC/.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from devtorch_core.reasoning_plus.learning.models import ReasoningCall
+
+logger = logging.getLogger("devtorch.reasoning_plus.learning")
+
+
+class CallRecorder:
+    """Persist ReasoningCall records under .GCC/reasoning_learnings/calls/."""
+
+    def __init__(self, gcc_dir: Path | str) -> None:
+        self._gcc_dir = Path(gcc_dir)
+        self._calls_dir = self._gcc_dir / "reasoning_learnings" / "calls"
+
+    def record(self, call: ReasoningCall) -> Path:
+        """Write a call to disk and return the path."""
+        self._calls_dir.mkdir(parents=True, exist_ok=True)
+        path = self._calls_dir / f"{call.id}.json"
+        try:
+            _atomic_json_write(path, call.to_dict())
+        except Exception as exc:
+            logger.warning("devtorch: failed to record reasoning call — %s", exc)
+        return path
+
+    def get(self, call_id: str) -> ReasoningCall | None:
+        path = self._calls_dir / f"{call_id}.json"
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return ReasoningCall.from_dict(data)
+        except Exception as exc:
+            logger.warning("devtorch: failed to read reasoning call %s — %s", call_id, exc)
+            return None
+
+    def list(self, session_id: str | None = None, call_type: str | None = None) -> list[ReasoningCall]:
+        """List recorded calls, optionally filtered by session or type."""
+        out: list[ReasoningCall] = []
+        if not self._calls_dir.exists():
+            return out
+        for path in sorted(self._calls_dir.glob("*.json")):
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                call = ReasoningCall.from_dict(data)
+                if session_id and call.session_id != session_id:
+                    continue
+                if call_type and call.call_type != call_type:
+                    continue
+                out.append(call)
+            except Exception as exc:
+                logger.debug("devtorch: skipping malformed call record %s — %s", path, exc)
+        return out
+
+    def count(self) -> int:
+        if not self._calls_dir.exists():
+            return 0
+        return len(list(self._calls_dir.glob("*.json")))
+
+
+def _atomic_json_write(path: Path, data: dict[str, Any]) -> None:
+    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)
+    finally:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except Exception:
+                pass

devtorch_core/reasoning_plus/learning/relevance.py

@@ -0,0 +1,122 @@
+"""
+devtorch_core.reasoning_plus.learning.relevance
+=================================================
+Rank learnings by relevance to the current context and state.
+
+Scoring factors (two-dimensional):
+1. Semantic similarity between context and learning content (embedding)
+2. Concept overlap between context keywords and learning trigger_concepts
+3. Confidence
+4. State freshness (matching state_hash boosts score)
+"""
+from __future__ import annotations
+
+import hashlib
+import time
+from typing import Any
+
+from devtorch_core.reasoning_plus.context import extract_keywords
+from devtorch_core.reasoning_plus.learning.embeddings import (
+    EmbeddingBackend,
+    KeywordEmbeddingBackend,
+)
+from devtorch_core.reasoning_plus.learning.models import Learning
+
+
+class RelevanceEngine:
+    """Score and rank learnings for a given context using an embedding backend."""
+
+    def __init__(self, backend: EmbeddingBackend | None = None, cache_ttl: float = 0) -> None:
+        self._backend = backend or KeywordEmbeddingBackend()
+        self._cache_ttl = cache_ttl
+        self._cache: dict[str, tuple[list[Learning], float]] = {}
+
+    def rank(
+        self,
+        context: str,
+        learnings: list[Learning],
+        current_state_hash: str | None = None,
+        top_n: int = 3,
+    ) -> list[Learning]:
+        """
+        Return the top-N active learnings ranked by relevance.
+
+        Scoring factors:
+        - semantic similarity between context and learning content
+        - concept overlap between context keywords and learning trigger_concepts
+        - confidence
+        - state freshness (matching state_hash boosts score)
+
+        Results are cached in memory when ``cache_ttl`` > 0 so repeated
+        similar prompts in the same session avoid recomputing embeddings.
+        """
+        cache_key = self._cache_key(context, learnings, current_state_hash, top_n)
+        if self._cache_ttl and cache_key:
+            cached = self._cache.get(cache_key)
+            if cached and (time.monotonic() - cached[1]) < self._cache_ttl:
+                return cached[0]
+
+        context_embedding = self._backend.encode(context)
+        context_keywords = set(extract_keywords(context, max_keywords=30))
+        scored: list[tuple[float, Learning]] = []
+
+        for learning in learnings:
+            if learning.validity != "active":
+                continue
+            score = self._score(
+                learning, context_embedding, current_state_hash, context_keywords,
+            )
+            scored.append((score, learning))
+
+        scored.sort(key=lambda x: x[0], reverse=True)
+        result = [learning for _, learning in scored[:top_n]]
+
+        if self._cache_ttl and cache_key:
+            self._cache[cache_key] = (result, time.monotonic())
+        return result
+
+    def _cache_key(
+        self,
+        context: str,
+        learnings: list[Learning],
+        current_state_hash: str | None,
+        top_n: int,
+    ) -> str:
+        """Stable key for the relevance cache."""
+        context_hash = hashlib.sha256(context.encode("utf-8")).hexdigest()[:16]
+        learning_ids = sorted({l.id for l in learnings})
+        learning_hash = hashlib.sha256(
+            "|".join(learning_ids).encode("utf-8")
+        ).hexdigest()[:16]
+        return f"{context_hash}:{current_state_hash or ''}:{learning_hash}:{top_n}"
+
+    def _score(
+        self,
+        learning: Learning,
+        context_embedding: Any,
+        current_state_hash: str | None,
+        context_keywords: set[str] | None = None,
+    ) -> float:
+        learning_embedding = self._backend.encode(learning.content)
+        semantic_score = self._backend.similarity(context_embedding, learning_embedding)
+
+        confidence_weight = learning.confidence
+
+        state_bonus = 0.0
+        if current_state_hash and learning.state_hash == current_state_hash:
+            state_bonus = 0.2
+
+        # Concept overlap: how much the learning's trigger_concepts overlap
+        # with keywords extracted from the current prompt context.
+        concept_bonus = 0.0
+        if context_keywords and learning.trigger_concepts:
+            learning_concepts = {c.lower() for c in learning.trigger_concepts}
+            overlap = len(context_keywords & learning_concepts)
+            if overlap > 0:
+                concept_bonus = min(0.3, overlap * 0.1)
+
+        return semantic_score + confidence_weight * 0.5 + state_bonus + concept_bonus
+
+    def invalidate_cache(self) -> None:
+        """Clear the relevance cache."""
+        self._cache.clear()

devtorch_core/reasoning_plus/learning/state.py

@@ -0,0 +1,86 @@
+"""
+devtorch_core.reasoning_plus.learning.state
+===========================================
+Workspace state hashing and staleness detection for learnings.
+"""
+from __future__ import annotations
+
+import logging
+import subprocess
+from pathlib import Path
+from typing import Iterable
+
+from devtorch_core.reasoning_plus.learning.models import hash_state
+
+logger = logging.getLogger("devtorch.reasoning_plus.learning")
+
+
+def workspace_state_hash(repo_path: Path | str, file_paths: Iterable[str] | None = None) -> str:
+    """
+    Return a short hash representing the current state of the workspace.
+
+    Strategy:
+    - If inside a git repo, include the current HEAD commit hash.
+    - For any provided file_paths, include the current file content hash.
+    - If not a git repo and no file paths, fall back to a hash of the directory path.
+    """
+    repo_path = Path(repo_path)
+    tokens: list[str] = []
+
+    head = _git_head(repo_path)
+    if head:
+        tokens.append(f"head:{head}")
+
+    for fp in file_paths or []:
+        content_hash = _file_content_hash(repo_path / fp)
+        if content_hash:
+            tokens.append(f"{fp}:{content_hash}")
+
+    if not tokens:
+        tokens.append(str(repo_path.resolve()))
+
+    return hash_state(*tokens)
+
+
+def _git_head(repo_path: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            errors="ignore",
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception as exc:
+        logger.debug("devtorch: could not read git HEAD — %s", exc)
+    return None
+
+
+def _file_content_hash(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    try:
+        return hash_state(path.read_text(encoding="utf-8", errors="ignore"))
+    except Exception as exc:
+        logger.debug("devtorch: could not hash %s — %s", path, exc)
+        return None
+
+
+def affected_by_state_change(repo_path: Path | str, learning_file_paths: Iterable[str], changed_paths: Iterable[str]) -> bool:
+    """
+    Return True if a learning should be re-evaluated because the workspace changed.
+
+    A learning is affected when any of the paths it references overlap with a changed path.
+    """
+    changed = set(changed_paths)
+    for fp in learning_file_paths:
+        if fp in changed:
+            return True
+        # Also invalidate if a parent directory was changed
+        for changed_path in changed:
+            if changed_path.startswith(fp) or fp.startswith(changed_path):
+                return True
+    return False

devtorch_core/reasoning_plus/learning/store.py

@@ -0,0 +1,160 @@
+"""
+devtorch_core.reasoning_plus.learning.store
+===========================================
+Persistence layer for distilled learnings.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from devtorch_core.reasoning_plus.context import extract_keywords
+from devtorch_core.reasoning_plus.learning.models import Learning
+
+logger = logging.getLogger("devtorch.reasoning_plus.learning")
+
+
+class LearningStore:
+    """Persist Learning records under .GCC/reasoning_learnings/learnings/."""
+
+    def __init__(self, gcc_dir: Path | str) -> None:
+        self._gcc_dir = Path(gcc_dir)
+        self._learnings_dir = self._gcc_dir / "reasoning_learnings" / "learnings"
+
+    def save(self, learning: Learning, deduplicate: bool = True) -> Path:
+        self._learnings_dir.mkdir(parents=True, exist_ok=True)
+        if deduplicate and learning.validity == "active":
+            duplicate = self._find_duplicate(learning)
+            if duplicate:
+                merged = self._merge(duplicate, learning)
+                path = self._learnings_dir / f"{merged.id}.json"
+                try:
+                    _atomic_json_write(path, merged.to_dict())
+                except Exception as exc:
+                    logger.warning("devtorch: failed to save merged learning — %s", exc)
+                return path
+        path = self._learnings_dir / f"{learning.id}.json"
+        try:
+            _atomic_json_write(path, learning.to_dict())
+        except Exception as exc:
+            logger.warning("devtorch: failed to save learning — %s", exc)
+        return path
+
+    def get(self, learning_id: str) -> Learning | None:
+        path = self._learnings_dir / f"{learning_id}.json"
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return Learning.from_dict(data)
+        except Exception as exc:
+            logger.warning("devtorch: failed to read learning %s — %s", learning_id, exc)
+            return None
+
+    def list(self, validity: str | None = None, concept: str | None = None) -> list[Learning]:
+        out: list[Learning] = []
+        if not self._learnings_dir.exists():
+            return out
+        for path in sorted(self._learnings_dir.glob("*.json")):
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                learning = Learning.from_dict(data)
+                if validity and learning.validity != validity:
+                    continue
+                if concept and concept.lower() not in {c.lower() for c in learning.trigger_concepts}:
+                    continue
+                out.append(learning)
+            except Exception as exc:
+                logger.debug("devtorch: skipping malformed learning %s — %s", path, exc)
+        return out
+
+    def invalidate(self, learning_id: str, reason: str = "stale") -> Learning | None:
+        learning = self.get(learning_id)
+        if not learning:
+            return None
+        learning.validity = "stale" if reason == "stale" else "deprecated"
+        learning.updated_at = _now_iso()
+        self.save(learning)
+        return learning
+
+    def count(self) -> int:
+        if not self._learnings_dir.exists():
+            return 0
+        return len(list(self._learnings_dir.glob("*.json")))
+
+    # ------------------------------------------------------------------
+    # Deduplication
+    # ------------------------------------------------------------------
+
+    def _find_duplicate(self, learning: Learning, threshold: float = 0.8) -> Learning | None:
+        """Return the most similar *other* active learning if it reaches the threshold."""
+        best: Learning | None = None
+        best_score = threshold
+        for existing in self.list(validity="active"):
+            if existing.id == learning.id:
+                continue
+            score = self._similarity(existing, learning)
+            if score >= best_score:
+                best_score = score
+                best = existing
+        return best
+
+    def _similarity(self, a: Learning, b: Learning) -> float:
+        """Combined concept and content similarity in [0, 1].
+
+        Concept overlap is weighted more heavily because two learnings that share
+        the same trigger concepts are likely talking about the same situation.
+        """
+        a_concepts = {c.lower() for c in a.trigger_concepts}
+        b_concepts = {c.lower() for c in b.trigger_concepts}
+        concept_union = len(a_concepts | b_concepts)
+        concept_score = len(a_concepts & b_concepts) / concept_union if concept_union else 0.0
+
+        a_keywords = set(extract_keywords(a.content, max_keywords=15))
+        b_keywords = set(extract_keywords(b.content, max_keywords=15))
+        content_union = len(a_keywords | b_keywords)
+        content_score = len(a_keywords & b_keywords) / content_union if content_union else 0.0
+
+        return 0.8 * concept_score + 0.2 * content_score
+
+    def _merge(self, existing: Learning, new: Learning) -> Learning:
+        """Merge *new* into *existing*, keeping the existing stable ID."""
+        merged = Learning.from_dict(existing.to_dict())
+        merged.content = new.content
+        merged.trigger_concepts = sorted(
+            set(existing.trigger_concepts) | set(new.trigger_concepts)
+        )
+        merged.confidence = max(existing.confidence, new.confidence)
+        merged.source_reasoning_ids = list(
+            set(existing.source_reasoning_ids) | set(new.source_reasoning_ids)
+        )
+        merged.validity = _more_restrictive_validity(existing.validity, new.validity)
+        merged.updated_at = _now_iso()
+        return merged
+
+
+def _atomic_json_write(path: Path, data: dict[str, Any]) -> None:
+    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)
+    finally:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except Exception:
+                pass
+
+
+def _more_restrictive_validity(a: str, b: str) -> str:
+    """Return the more restrictive validity status."""
+    order = {"deprecated": 2, "stale": 1, "active": 0}
+    return a if order.get(a, 0) >= order.get(b, 0) else b
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()