cherry-docs 0.2.0__py3-none-any.whl

app/services/memory_retrieval_text.py

@@ -0,0 +1,113 @@
+"""Text/token helpers for memory retrieval — tokenization, overlap, question mode, file matching."""
+
+from __future__ import annotations
+
+import re
+
+_STOPWORDS = {
+    "a",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "be",
+    "because",
+    "for",
+    "from",
+    "how",
+    "i",
+    "if",
+    "in",
+    "into",
+    "is",
+    "it",
+    "of",
+    "on",
+    "or",
+    "that",
+    "the",
+    "this",
+    "to",
+    "was",
+    "what",
+    "why",
+    "with",
+}
+_RECENCY_QUERY_TERMS = {"latest", "recent", "newest", "changed", "change", "now", "currently", "just"}
+
+
+def _stem(token: str) -> str:
+    """Minimal English stemmer: strip common suffixes so plural/verb forms match."""
+    for suffix in ("tions", "tion", "ings", "ing", "ions", "ion", "ies", "ed", "es", "ly", "s"):
+        if token.endswith(suffix) and len(token) - len(suffix) > 2:
+            return token[: -len(suffix)]
+    return token
+
+
+def _tokens(value: str) -> set[str]:
+    raw = {
+        token
+        for token in re.findall(r"[a-z0-9]+", value.lower())
+        if token and token not in _STOPWORDS and len(token) > 2
+    }
+    return {_stem(t) for t in raw}
+
+
+def _score_overlap(left: str, right: str) -> float:
+    left_tokens = _tokens(left)
+    right_tokens = _tokens(right)
+    if not left_tokens or not right_tokens:
+        return 0.0
+    overlap = len(left_tokens & right_tokens)
+    return overlap / max(1, min(len(left_tokens), len(right_tokens)))
+
+
+def _question_mode(question: str) -> str:
+    lowered = question.lower()
+    if "why" in lowered:
+        return "why"
+    if "how" in lowered:
+        return "how"
+    if "fail" in lowered:
+        return "what_failed"
+    if "what" in lowered or "which" in lowered or "state" in lowered or "current" in lowered:
+        return "what"
+    return "generic"
+
+
+def _wants_recent_context(question: str) -> bool:
+    lowered = question.lower()
+    return any(term in lowered for term in _RECENCY_QUERY_TERMS)
+
+
+def _trim_text(value: str, limit: int = 280) -> str:
+    text = " ".join((value or "").split())
+    if len(text) <= limit:
+        return text
+    return f"{text[: limit - 3]}..."
+
+
+def _file_query_hint(file_path: str | None) -> str:
+    if not file_path:
+        return ""
+    normalized = file_path.strip().lower().strip("/")
+    if not normalized:
+        return ""
+    parts = [p for p in re.split(r"[/_.-]+", normalized) if p and len(p) > 2]
+    hints = set(parts) | {p[:-1] for p in parts if p.endswith("s") and len(p) > 4}
+    return " ".join(sorted(hints))
+
+
+def _file_overlap(file_path: str | None, files: list[str]) -> float:
+    if not file_path:
+        return 0.0
+    normalized = file_path.strip().lower().lstrip("/")
+    if not normalized:
+        return 0.0
+    lowered = [str(path).strip().lower().lstrip("/") for path in files if str(path).strip()]
+    if normalized in lowered:
+        return 1.0
+    if any(path.endswith(normalized) or normalized.endswith(path) for path in lowered):
+        return 0.7
+    return 0.0

app/services/memory_similarity.py

@@ -0,0 +1,135 @@
+"""Similarity and matching heuristics for memory lifecycle decisions.
+
+Uses TYPE_CHECKING for MemoryRecord to avoid circular imports at runtime
+(memory_lifecycle imports these helpers, and MemoryRecord lives there).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from app.services.memory_extraction_normalize import MemoryCandidate
+
+if TYPE_CHECKING:
+    from app.services.memory_lifecycle import MemoryRecord
+
+_STOPWORDS = {
+    "a", "an", "and", "are", "as", "at", "be", "because", "for", "from",
+    "how", "if", "in", "into", "is", "it", "of", "on", "or", "that", "the",
+    "this", "to", "use", "using", "we", "with",
+}
+_NEGATIVE_HINTS = {"avoid", "reject", "deprecated", "legacy", "superseded", "replace", "replaced", "drop"}
+_POSITIVE_HINTS = {"choose", "chosen", "use", "using", "adopt", "keep", "kept", "implement", "switch", "move"}
+_PROCEDURE_HINTS = {"first", "then", "next", "workflow", "runbook", "checklist", "repeatable", "repeat"}
+
+
+def _normalize_tokens(value: str) -> list[str]:
+    return [
+        token
+        for token in re.findall(r"[a-z0-9]+", value.lower())
+        if token and token not in _STOPWORDS and len(token) > 2
+    ]
+
+
+def _raw_tokens(value: str) -> set[str]:
+    return {token for token in re.findall(r"[a-z0-9]+", value.lower()) if token}
+
+
+def topic_key_for_text(*parts: str, limit: int = 4) -> str:
+    tokens: list[str] = []
+    seen: set[str] = set()
+    for part in parts:
+        for token in _normalize_tokens(part):
+            if token in seen:
+                continue
+            tokens.append(token)
+            seen.add(token)
+            if len(tokens) >= limit:
+                return " ".join(tokens)
+    return " ".join(tokens)
+
+
+def _similarity(left: str, right: str) -> float:
+    left_tokens = set(_normalize_tokens(left))
+    right_tokens = set(_normalize_tokens(right))
+    if not left_tokens or not right_tokens:
+        return 0.0
+    overlap = len(left_tokens & right_tokens)
+    return overlap / max(1, min(len(left_tokens), len(right_tokens)))
+
+
+def _candidate_text(candidate: MemoryCandidate) -> str:
+    return f"{candidate.summary} {candidate.rationale}".strip()
+
+
+def _record_text(record: MemoryRecord) -> str:
+    return f"{record.summary} {record.rationale}".strip()
+
+
+def _has_any_hint(text: str, hints: set[str]) -> bool:
+    return bool(_raw_tokens(text) & hints)
+
+
+def _is_repeatable_procedure(summary: str, rationale: str) -> bool:
+    return _has_any_hint(f"{summary} {rationale}".strip(), _PROCEDURE_HINTS)
+
+
+def _is_conflict(candidate: MemoryCandidate, record: MemoryRecord) -> bool:
+    if candidate.memory_type != record.memory_type:
+        return False
+    similarity = _similarity(_candidate_text(candidate), _record_text(record))
+    topic_similarity = _similarity(candidate.summary, record.summary)
+    if max(similarity, topic_similarity) < 0.3:
+        return False
+    candidate_negative = _has_any_hint(_candidate_text(candidate), _NEGATIVE_HINTS)
+    record_negative = _has_any_hint(_record_text(record), _NEGATIVE_HINTS)
+    candidate_positive = _has_any_hint(_candidate_text(candidate), _POSITIVE_HINTS)
+    record_positive = _has_any_hint(_record_text(record), _POSITIVE_HINTS)
+    return (candidate_negative and record_positive) or (candidate_positive and record_negative)
+
+
+def _should_supersede(candidate: MemoryCandidate, record: MemoryRecord) -> bool:
+    if record.status != "active":
+        return False
+    if _similarity(_candidate_text(candidate), _record_text(record)) < 0.45:
+        return False
+    if candidate.confidence + 0.05 < record.confidence:
+        return False
+    return _has_any_hint(
+        _candidate_text(candidate),
+        {"replace", "replaced", "switch", "superseded", "migrate", "deprecated"},
+    )
+
+
+def _should_merge(candidate: MemoryCandidate, record: MemoryRecord) -> bool:
+    if candidate.memory_type != record.memory_type:
+        return False
+    if candidate.kind != record.kind:
+        return False
+    similarity = _similarity(_candidate_text(candidate), _record_text(record))
+    if similarity >= 0.7:
+        return True
+    if candidate.kind == "decision":
+        summary_similarity = _similarity(candidate.summary, record.summary)
+        rationale_similarity = _similarity(candidate.rationale, record.rationale)
+        topic_similarity = _similarity(
+            topic_key_for_text(candidate.summary, candidate.rationale),
+            topic_key_for_text(record.summary, record.rationale),
+        )
+        return max(summary_similarity, rationale_similarity, topic_similarity) >= 0.4
+    return False
+
+
+def _best_matching_record(
+    candidate: MemoryCandidate, records: list[MemoryRecord]
+) -> MemoryRecord | None:
+    best: MemoryRecord | None = None
+    best_score = 0.0
+    ctext = _candidate_text(candidate)
+    for record in records:
+        score = _similarity(ctext, _record_text(record))
+        if score > best_score:
+            best_score = score
+            best = record
+    return best

app/services/privacy.py

@@ -0,0 +1,72 @@
+"""Privacy and redaction: detect and redact secrets before persistence."""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_REDACT_PATTERNS = {
+    "EMAIL": r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',
+    "API_KEY": r"(?i)(api[_-]?key|token|secret|password|auth)['\"]?\s*[:=]\s*['\"]?([a-zA-Z0-9_\-]{20,})['\"]?",
+    "JWT": r'ey[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*',
+    "GROQ": r'gsk_[a-zA-Z0-9]{20,}',
+    "OPENAI": r'sk-[a-zA-Z0-9\-_]{20,}',
+    "GITHUB": r'gh[pousr]_[a-zA-Z0-9]{36}',
+}
+
+# High-confidence blocking patterns — used to fail-closed before persistence.
+_BLOCKING_PATTERNS: dict[str, str] = {
+    "openai_like_key": r"\bsk-[A-Za-z0-9_\-]{20,}\b",
+    "groq_key": r"\bgsk_[A-Za-z0-9]{20,}\b",
+    "github_pat": r"\bgh[pousr]_[A-Za-z0-9]{20,}\b",
+    "huggingface_token": r"\bhf_[A-Za-z0-9]{20,}\b",
+    "aws_access_key": r"\bAKIA[0-9A-Z]{16}\b",
+    "private_key_block": r"-----BEGIN [A-Z ]+PRIVATE KEY-----",
+    "credential_assignment": (
+        r"(?i)\b(api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password|passwd|authorization)\b"
+        r"\s*[:=]\s*[\"']?(?:bearer\s+)?[A-Za-z0-9._\-]{16,}[\"']?"
+    ),
+}
+
+
+def _scan_text_for_blocking_secret(text: str) -> list[str]:
+    return [label for label, pattern in _BLOCKING_PATTERNS.items() if re.search(pattern, text)]
+
+
+def _walk_payload_for_secrets(value: Any, path: str, findings: list[str], max_hits: int) -> None:
+    if len(findings) >= max_hits:
+        return
+    if isinstance(value, str):
+        labels = _scan_text_for_blocking_secret(value)
+        if labels:
+            findings.append(f"{path} ({', '.join(sorted(set(labels)))})")
+    elif isinstance(value, dict):
+        for key, nested in value.items():
+            _walk_payload_for_secrets(nested, f"{path}.{key}", findings, max_hits)
+            if len(findings) >= max_hits:
+                return
+    elif isinstance(value, list):
+        for idx, nested in enumerate(value):
+            _walk_payload_for_secrets(nested, f"{path}[{idx}]", findings, max_hits)
+            if len(findings) >= max_hits:
+                return
+
+
+def detect_blocking_secret_fields(data: dict[str, Any], max_hits: int = 8) -> list[str]:
+    """Return payload paths containing high-confidence secret material."""
+    findings: list[str] = []
+    _walk_payload_for_secrets(data, "payload", findings, max_hits=max_hits)
+    return findings
+
+
+def redact_text(text: str) -> str:
+    """Redact PII and secrets from a string."""
+    if not text:
+        return text
+    redacted = text
+    redacted = re.sub(_REDACT_PATTERNS["GROQ"], "[REDACTED_GROQ_KEY]", redacted)
+    redacted = re.sub(_REDACT_PATTERNS["OPENAI"], "[REDACTED_OPENAI_KEY]", redacted)
+    redacted = re.sub(_REDACT_PATTERNS["GITHUB"], "[REDACTED_GITHUB_TOKEN]", redacted)
+    redacted = re.sub(_REDACT_PATTERNS["API_KEY"], lambda m: f"{m.group(1)}: [REDACTED_SECRET]", redacted)
+    redacted = re.sub(_REDACT_PATTERNS["EMAIL"], "[REDACTED_EMAIL]", redacted)
+    redacted = re.sub(_REDACT_PATTERNS["JWT"], "[REDACTED_JWT]", redacted)
+    return redacted

app/services/promoted_memory_answer.py

@@ -0,0 +1,157 @@
+"""Promoted-memory answer helpers."""
+from __future__ import annotations
+
+from app.services.auto_promote_sessions import (
+    AutoPromotionPolicy,
+    AutoPromotionRunReport,
+    auto_promote_captured_sessions,
+)
+from app.services.capture_core import LocalCaptureBuffer
+from app.services.internal_memory_agent import MemoryModelProvider
+from app.services.memory_providers import resolve_provider
+from app.services.memory_lifecycle import build_event_evidence_id
+from app.services.memory_retrieval import (
+    RetrievalAnswer,
+    apply_retrieval_feedback,
+    synthesize_retrieval_answer,
+)
+from app.services.promoted_memory_store import DEFAULT_PROMOTED_ROOT, LocalPromotedMemoryStore
+
+
+def _compact_files(paths: list[str], *, limit: int = 6) -> list[str]:
+    compacted: list[str] = []
+    seen: set[str] = set()
+    for raw in paths:
+        path = str(raw).strip()
+        if not path or path in seen:
+            continue
+        seen.add(path)
+        compacted.append(path)
+        if len(compacted) >= limit:
+            break
+    return compacted
+
+
+def events_from_memory(
+    records,
+    *,
+    buffer_dir: str = ".cherrydocs/capture",
+) -> list[dict]:
+    """Load raw capture events referenced by promoted memory records."""
+    evidence_ids = {
+        ev_id
+        for record in records
+        for ev_id in record.evidence
+        if ":" in ev_id
+    }
+    if not evidence_ids:
+        return []
+
+    events: list[dict] = []
+    capture_buffer = LocalCaptureBuffer(buffer_dir)
+    loaded_sessions: set[str] = set()
+    for record in records:
+        session_id = str(record.session_id or "").strip()
+        if not session_id or session_id in loaded_sessions:
+            continue
+        loaded_sessions.add(session_id)
+        for event in capture_buffer.read(session_id):
+            if build_event_evidence_id(event) not in evidence_ids:
+                continue
+            events.append(
+                {
+                    "event_type": str(event.get("event_type") or "unknown"),
+                    "timestamp": event.get("timestamp"),
+                    "text": str(event.get("text") or "").strip(),
+                    "files": _compact_files(
+                        [str(p) for p in (event.get("files") or []) if str(p).strip()]
+                    ),
+                    "branch": event.get("branch"),
+                    "commit": event.get("commit"),
+                }
+            )
+    return events
+
+
+def answer_from_promoted_memory(
+    *,
+    project_id: str,
+    question: str,
+    branch: str | None = None,
+    file_path: str | None = None,
+    buffer_dir: str = ".cherrydocs/capture",
+    promoted_root: str = DEFAULT_PROMOTED_ROOT,
+) -> RetrievalAnswer:
+    store = LocalPromotedMemoryStore(promoted_root)
+    all_records = store.load_records(project_id)
+    records = [r for r in all_records if not branch or not r.branch or r.branch == branch]
+    answer = synthesize_retrieval_answer(
+        question,
+        records,
+        events_from_memory(records, buffer_dir=buffer_dir),
+        branch=branch,
+        file_path=file_path,
+    )
+    if answer.memories:
+        updated_records = apply_retrieval_feedback(records, answer.memories, answer.evidence)
+        try:
+            store.upsert_records(project_id, updated_records)
+        except Exception:
+            pass
+    return answer
+
+
+def _should_refresh_answer(answer: RetrievalAnswer) -> bool:
+    """Only refresh when no memories at all or the top match is inactive."""
+    if not answer.memories:
+        return True
+    return answer.memories[0].memory.status != "active"
+
+
+def answer_from_promoted_memory_with_refresh(
+    *,
+    project_id: str,
+    question: str,
+    branch: str | None = None,
+    file_path: str | None = None,
+    auto_promote_if_empty: bool = True,
+    project_hint: str | None = None,
+    buffer_dir: str = ".cherrydocs/capture",
+    promoted_root: str = DEFAULT_PROMOTED_ROOT,
+    provider: MemoryModelProvider | None = None,
+    policy: AutoPromotionPolicy | None = None,
+    memory_profile: str | None = None,
+) -> tuple[RetrievalAnswer, AutoPromotionRunReport | None]:
+    answer = answer_from_promoted_memory(
+        project_id=project_id,
+        question=question,
+        branch=branch,
+        file_path=file_path,
+        buffer_dir=buffer_dir,
+        promoted_root=promoted_root,
+    )
+    if not _should_refresh_answer(answer) or not auto_promote_if_empty:
+        return answer, None
+
+    report = auto_promote_captured_sessions(
+        project_id=project_id,
+        buffer_dir=buffer_dir,
+        promoted_root=promoted_root,
+        provider=provider or resolve_provider(),
+        project_hint=project_hint,
+        memory_profile=memory_profile,
+        branch=branch,
+        policy=policy or AutoPromotionPolicy(max_sessions=3, min_event_count=3, min_candidate_confidence=0.8),
+    )
+    if not report.processed:
+        return answer, report
+
+    refreshed = answer_from_promoted_memory(
+        project_id=project_id,
+        question=question,
+        branch=branch,
+        file_path=file_path,
+        buffer_dir=buffer_dir,
+        promoted_root=promoted_root,
+    )
+    return refreshed, report

app/services/promoted_memory_pipeline.py

@@ -0,0 +1,194 @@
+"""End-to-end capture -> distill -> promote pipeline for AI-facing session memory."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from app.services.internal_memory_agent import (
+    MemoryExtractionResult,
+    MemoryModelProvider,
+    build_recent_capture_window,
+    extract_memory_candidates,
+)
+from app.services.memory_lifecycle import (
+    MemoryPromotionResult,
+    MemoryRecord,
+    build_existing_memory_context,
+    collect_candidate_context,
+    collect_candidate_evidence_refs,
+    promote_memory_candidates,
+)
+from app.services.promoted_memory_store import DEFAULT_PROMOTED_ROOT, LocalPromotedMemoryStore
+
+
+class DistillationTrace(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    memory_profile: str
+    provider_label: str
+    input_event_count: int = 0
+    extracted_candidate_count: int = 0
+    extracted_store_count: int = 0
+    extracted_noise_count: int = 0
+    promoted_record_count: int = 0
+    stored_record_count: int = 0
+    extracted_kind_counts: dict[str, int] = Field(default_factory=dict)
+    extracted_memory_type_counts: dict[str, int] = Field(default_factory=dict)
+
+
+class SessionPromotionReport(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    session_id: str
+    project_id: str
+    extracted: MemoryExtractionResult
+    promotion: MemoryPromotionResult
+    session_records: list[MemoryRecord] = Field(default_factory=list)
+    stored_records: list[MemoryRecord] = Field(default_factory=list)
+    distillation_trace: DistillationTrace
+
+
+def _increment_count(bucket: dict[str, int], key: str) -> None:
+    normalized = " ".join(str(key or "").split()).strip().lower() or "unknown"
+    bucket[normalized] = bucket.get(normalized, 0) + 1
+
+
+def _provider_label(provider: MemoryModelProvider) -> str:
+    model = " ".join(str(getattr(provider, "model", "") or "").split()).strip()
+    if model:
+        return model
+    return provider.__class__.__name__
+
+
+def _build_distillation_trace(
+    *,
+    memory_profile: str | None,
+    provider: MemoryModelProvider,
+    events: list[dict],
+    extraction: MemoryExtractionResult,
+    session_records: list[MemoryRecord],
+    stored_records: list[MemoryRecord],
+) -> DistillationTrace:
+    kind_counts: dict[str, int] = {}
+    memory_type_counts: dict[str, int] = {}
+    store_count = 0
+    noise_count = 0
+    for candidate in extraction.candidates:
+        _increment_count(kind_counts, candidate.kind)
+        _increment_count(memory_type_counts, candidate.memory_type)
+        if candidate.memory_type == "noise":
+            noise_count += 1
+        if candidate.should_store and candidate.memory_type != "noise":
+            store_count += 1
+
+    return DistillationTrace(
+        memory_profile=" ".join(str(memory_profile or "").split()).strip() or "default",
+        provider_label=_provider_label(provider),
+        input_event_count=len(events),
+        extracted_candidate_count=len(extraction.candidates),
+        extracted_store_count=store_count,
+        extracted_noise_count=noise_count,
+        promoted_record_count=len(session_records),
+        stored_record_count=len(stored_records),
+        extracted_kind_counts=kind_counts,
+        extracted_memory_type_counts=memory_type_counts,
+    )
+
+
+def _apply_candidate_context(
+    extracted: MemoryExtractionResult,
+    promoted: MemoryPromotionResult,
+    events: list[dict],
+) -> None:
+    evidence_window = build_recent_capture_window(events, limit=48)
+    evidence_refs_by_candidate = {
+        index: collect_candidate_evidence_refs(candidate, evidence_window)
+        for index, candidate in enumerate(extracted.candidates)
+    }
+    context_by_candidate = {
+        index: collect_candidate_context(candidate, evidence_window, evidence_refs=evidence_refs_by_candidate.get(index, []))
+        for index, candidate in enumerate(extracted.candidates)
+    }
+
+    record_refs_by_id: dict[str, list[str]] = {}
+    for index, decision in enumerate(promoted.decisions):
+        record = decision.resulting_record
+        if not record:
+            continue
+        refs = evidence_refs_by_candidate.get(index, [])
+        context = context_by_candidate.get(index, {})
+        merged = list(dict.fromkeys([*record.evidence, *refs]))
+        record.evidence = merged
+        record.repo = str(context.get("repo") or record.repo or "") or record.repo
+        record.commit = str(context.get("commit") or record.commit or "") or record.commit
+        ctx_files = context.get("files")
+        if isinstance(ctx_files, list):
+            record.files = list(dict.fromkeys([*record.files, *ctx_files]))
+        record_refs_by_id[record.memory_id] = merged
+
+    for record in promoted.records:
+        stored_refs = record_refs_by_id.get(record.memory_id)
+        if stored_refs:
+            record.evidence = stored_refs
+
+
+def run_session_promotion(
+    *,
+    events: list[dict],
+    session_id: str,
+    project_id: str,
+    provider: MemoryModelProvider,
+    project_hint: str | None = None,
+    branch: str | None = None,
+    commit: str | None = None,
+    existing_records: list[MemoryRecord] | None = None,
+    source: str = "capture-session",
+    min_confidence: float = 0.0,
+    memory_profile: str | None = None,
+) -> SessionPromotionReport:
+    prior_records = list(existing_records or [])
+    extraction = extract_memory_candidates(
+        events,
+        provider=provider,
+        project_hint=project_hint,
+        existing_context=build_existing_memory_context(prior_records),
+        profile=memory_profile,
+    )
+    eligible_candidates = [
+        candidate
+        for candidate in extraction.candidates
+        if candidate.should_store and candidate.memory_type != "noise" and candidate.confidence >= min_confidence
+    ]
+    promoted = promote_memory_candidates(
+        eligible_candidates,
+        existing_records=prior_records,
+        project_id=project_id,
+        source=source,
+        session_id=session_id,
+        branch=branch,
+        commit=commit,
+        evidence=[session_id],
+    )
+    _apply_candidate_context(extraction, promoted, events)
+    session_records = [decision.resulting_record for decision in promoted.decisions if decision.resulting_record]
+    stored_records = promoted.records
+    distillation_trace = _build_distillation_trace(
+        memory_profile=memory_profile,
+        provider=provider,
+        events=events,
+        extraction=extraction,
+        session_records=session_records,
+        stored_records=stored_records,
+    )
+    return SessionPromotionReport(
+        session_id=session_id,
+        project_id=project_id,
+        extracted=extraction,
+        promotion=promoted,
+        session_records=session_records,
+        stored_records=stored_records,
+        distillation_trace=distillation_trace,
+    )
+
+
+__all__ = ["DistillationTrace", "SessionPromotionReport", "run_session_promotion"]