apsimo 1.3.0__py3-none-any.whl

apsimo/tom/exposure.py

@@ -0,0 +1,214 @@
+"""Tom2 exposure ledger + budgets (L2.3) — refs only, never content.
+
+Every level-2 rendering, when the system eventually wires one, must be
+written here FIRST and budgeted against what was already shown. The ledger
+slows aggregation (T6): a reader cannot harvest the epistemic map by asking
+often, because budgets bind per (reader, subject) pair, per reader, and
+globally per rolling 24h window.
+
+PRIVACY INVARIANT (same pin as Tom2Store, enforced at write time and
+regression-locked by a raw-DB regex test): a ledger row carries contact
+ids, an opaque fact ref, and an opaque conversation key — cross-contact
+fact TEXT never enters this table. A leak of the ledger reveals that
+topology was rendered, never what it said.
+
+Budget semantics are fail-closed: malformed env values read as budget 0
+(nothing renders), and any storage error answers "no budget".
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import sqlite3
+import threading
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional
+
+from apsimo.tom.tom2 import _validate_ref
+
+logger = logging.getLogger(__name__)
+
+#: Opaque conversation key: compact, no whitespace — prose is refused so
+#: message text cannot be smuggled through the key field.
+_CONV_KEY_RE = re.compile(r"^[A-Za-z0-9_.:+@-]{1,128}$")
+
+#: Shipped budget defaults — deliberately tight; a deployment widens them
+#: explicitly. Malformed values fail closed to 0.
+DEFAULT_PAIR_DAY = 1
+DEFAULT_READER_DAY = 3
+DEFAULT_GLOBAL_DAY = 10
+
+
+def _budget(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or not str(raw).strip():
+        return default
+    try:
+        return max(0, int(str(raw).strip()))
+    except (TypeError, ValueError):
+        logger.warning("%s=%r is malformed — failing closed to budget 0",
+                       name, raw)
+        return 0
+
+
+def budget_pair_day() -> int:
+    """COLONY_TOM2_BUDGET_PAIR_DAY (default 1): renderings per (reader,
+    subject) pair per rolling 24h."""
+    return _budget("COLONY_TOM2_BUDGET_PAIR_DAY", DEFAULT_PAIR_DAY)
+
+
+def budget_reader_day() -> int:
+    """COLONY_TOM2_BUDGET_READER_DAY (default 3): renderings per reader
+    per rolling 24h."""
+    return _budget("COLONY_TOM2_BUDGET_READER_DAY", DEFAULT_READER_DAY)
+
+
+def budget_global_day() -> int:
+    """COLONY_TOM2_BUDGET_GLOBAL_DAY (default 10): renderings across all
+    readers per rolling 24h."""
+    return _budget("COLONY_TOM2_BUDGET_GLOBAL_DAY", DEFAULT_GLOBAL_DAY)
+
+
+def _now() -> datetime:
+    return datetime.now(tz=timezone.utc)
+
+
+def _validate_conv_key(key: Any) -> str:
+    key = str(key or "").strip()
+    if not _CONV_KEY_RE.match(key):
+        raise ValueError(
+            f"exposure conversation key {key[:40]!r} is not an opaque id "
+            "(refs-not-content invariant)")
+    return key
+
+
+def _validate_cid(cid: Any, what: str) -> str:
+    cid = str(cid or "").strip()
+    if not _CONV_KEY_RE.match(cid):
+        raise ValueError(
+            f"exposure {what} {cid[:40]!r} is not an opaque contact id "
+            "(refs-not-content invariant)")
+    return cid
+
+
+class Tom2ExposureStore:
+    """SQLite-backed ledger of level-2 renderings (refs-not-content)."""
+
+    def __init__(self, db_path: Optional[str] = None) -> None:
+        self._lock = threading.RLock()
+        self._conn = sqlite3.connect(db_path or ":memory:",
+                                     check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        with self._lock:
+            self._conn.execute("""
+                CREATE TABLE IF NOT EXISTS tom2_exposures (
+                    id                 TEXT PRIMARY KEY,
+                    reader_contact_id  TEXT NOT NULL,
+                    subject_contact_id TEXT NOT NULL,
+                    fact_ref           TEXT NOT NULL,
+                    conversation_key   TEXT NOT NULL,
+                    created_at         TEXT NOT NULL
+                )""")
+            self._conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_tom2_exp_reader "
+                "ON tom2_exposures(reader_contact_id, created_at)")
+            self._conn.commit()
+
+    # -- writes -------------------------------------------------------------
+    def record_exposure(self, *, reader_contact_id: str,
+                        subject_contact_id: str, fact_ref: str,
+                        conversation_key: str) -> Dict[str, Any]:
+        """Append one rendering to the ledger. Raises on any privacy-pin
+        violation (prose in any field) — never best-effort."""
+        row = {
+            "id": str(uuid.uuid4()),
+            "reader_contact_id": _validate_cid(reader_contact_id, "reader"),
+            "subject_contact_id": _validate_cid(subject_contact_id,
+                                                "subject"),
+            "fact_ref": _validate_ref(fact_ref),
+            "conversation_key": _validate_conv_key(conversation_key),
+            "created_at": _now().isoformat(),
+        }
+        with self._lock:
+            self._conn.execute(
+                "INSERT INTO tom2_exposures (id, reader_contact_id, "
+                "subject_contact_id, fact_ref, conversation_key, created_at)"
+                " VALUES (?,?,?,?,?,?)", list(row.values()))
+            self._conn.commit()
+        return row
+
+    # -- budgets --------------------------------------------------------------
+    def _count(self, where: str, params: List[Any], hours: float) -> int:
+        cutoff = (_now() - timedelta(hours=hours)).isoformat()
+        with self._lock:
+            r = self._conn.execute(
+                f"SELECT COUNT(*) n FROM tom2_exposures WHERE {where} "
+                "AND created_at >= ?", params + [cutoff]).fetchone()
+        return int(r["n"])
+
+    def budget_ok(self, reader_contact_id: str, subject_contact_id: str,
+                  fact_ref: str = "") -> bool:
+        """True when rendering one more line for (reader, subject) stays
+        inside ALL budgets (pair, reader, global; rolling 24h). Any error
+        answers False — a broken ledger cannot vouch for capacity."""
+        try:
+            reader = str(reader_contact_id or "").strip()
+            subject = str(subject_contact_id or "").strip()
+            if not reader or not subject:
+                return False
+            if self._count(
+                    "reader_contact_id=? AND subject_contact_id=?",
+                    [reader, subject], 24.0) >= budget_pair_day():
+                return False
+            if self._count("reader_contact_id=?", [reader],
+                           24.0) >= budget_reader_day():
+                return False
+            if self._count("1=1", [], 24.0) >= budget_global_day():
+                return False
+            return True
+        except Exception:
+            logger.debug("exposure budget check failed (=> no budget)",
+                         exc_info=True)
+            return False
+
+    # -- owner reads ----------------------------------------------------------
+    def recent(self, *, reader_contact_id: Optional[str] = None,
+               subject_contact_id: Optional[str] = None,
+               limit: int = 50) -> List[Dict[str, Any]]:
+        clauses, params = ["1=1"], []
+        if reader_contact_id:
+            clauses.append("reader_contact_id=?")
+            params.append(reader_contact_id)
+        if subject_contact_id:
+            clauses.append("subject_contact_id=?")
+            params.append(subject_contact_id)
+        params.append(max(1, min(500, int(limit))))
+        with self._lock:
+            rows = self._conn.execute(
+                f"SELECT * FROM tom2_exposures WHERE {' AND '.join(clauses)}"
+                " ORDER BY created_at DESC LIMIT ?", params).fetchall()
+        return [dict(r) for r in rows]
+
+    def counts(self) -> Dict[str, Any]:
+        """Aggregate observability (numbers only)."""
+        with self._lock:
+            total = self._conn.execute(
+                "SELECT COUNT(*) n FROM tom2_exposures").fetchone()["n"]
+            readers = self._conn.execute(
+                "SELECT COUNT(DISTINCT reader_contact_id) n "
+                "FROM tom2_exposures").fetchone()["n"]
+            pairs = self._conn.execute(
+                "SELECT COUNT(*) n FROM (SELECT DISTINCT reader_contact_id,"
+                " subject_contact_id FROM tom2_exposures)").fetchone()["n"]
+        last24 = self._count("1=1", [], 24.0)
+        return {"total": int(total), "readers": int(readers),
+                "pairs": int(pairs), "last_24h": last24}
+
+    def close(self) -> None:
+        try:
+            self._conn.close()
+        except Exception:
+            pass

apsimo/tom/extractor.py

@@ -0,0 +1,306 @@
+"""LLM-backed extraction for Theory of Mind.
+
+Extracts affect signals and shared facts from conversation turns.
+Uses the LLM router (same as world model entity extraction) — Colony
+does NOT build its own LLM client.
+
+Throttled per contact and operation: max 1 extraction per
+COLONY_TOM_EXTRACTION_THROTTLE_MINUTES (default 5 minutes).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from apsimo.beliefs.promotion import PROMOTION_PROMPT, promotion_metadata
+from apsimo.util.model_output import final_text
+
+logger = logging.getLogger(__name__)
+
+MAX_INPUT_CHARS = 4_000
+MAX_RESPONSE_TOKENS = int(os.environ.get("COLONY_TOM_MAX_TOKENS", "2048"))  # reasoning models (mimo) need room; 512 returns empty content
+THROTTLE_MINUTES = int(os.environ.get("COLONY_TOM_EXTRACTION_THROTTLE_MINUTES", "5"))
+
+# ---------------------------------------------------------------------------
+# Affect extraction prompt
+# ---------------------------------------------------------------------------
+
+_AFFECT_SYSTEM_PROMPT = (
+    "You are an emotion analysis engine. Read the conversation and return a "
+    "JSON object with the speaker's emotional state. Keys: "
+    '"valence" (float -1.0 to 1.0, negative=unhappy, positive=happy), '
+    '"arousal" (float 0.0 to 1.0, 0=calm, 1=intense), '
+    '"trigger" (string, brief excerpt causing the reading), '
+    '"confidence" (float 0.0 to 1.0). '
+    "Return ONLY the JSON object. If the conversation is neutral, "
+    'return {"valence": 0.0, "arousal": 0.3, "trigger": null, "confidence": 0.5}. '
+    "Do not add prose, code fences, or explanation."
+)
+
+# ---------------------------------------------------------------------------
+# Fact extraction prompt
+# ---------------------------------------------------------------------------
+
+_FACT_SYSTEM_PROMPT = (
+    "You are a knowledge extraction engine. Read the conversation and identify "
+    "what the contact now KNOWS or BELIEVES as a result of this conversation. "
+    "Return a JSON array of objects. Each object has keys: "
+    '"evidence" (an exact contiguous quotation of at most 500 characters from the conversation), '
+    '"source" (one of: told_by_contact, told_to_contact, shared_context, inferred), '
+    '"confidence" (float 0.0 to 1.0). '
+    "Keep the speaker's actual words and attribution. This is an estimate of what "
+    "was communicated, not proof it is true or that the contact accepted it. "
+    "Do not infer that the contact knows something merely because it was in the "
+    "assistant's response. Return at most 6 items. "
+    "Return ONLY the JSON array. Return [] if no useful new knowledge. "
+    "Do not add prose, code fences, or explanation."
+) + '\n' + PROMOTION_PROMPT
+
+
+
+
+class TomExtractor:
+    """LLM-backed ToM extraction from conversation turns."""
+
+    def __init__(self, llm_router: Any) -> None:
+        self._router = llm_router
+        self._last_extraction: Dict[str, str] = {}  # contact_id → ISO timestamp
+        self._last_facts: Dict[str, str] = {}  # affect must not suppress fact extraction
+
+    async def extract_affect(
+        self,
+        conversation_text: str,
+        contact_id: str,
+        *,
+        session_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Extract affect from a conversation snippet.
+
+        Returns dict with valence, arousal, trigger, confidence or None.
+        Throttled per contact.
+        """
+        if not self._can_extract(contact_id):
+            return None
+
+        snippet = (conversation_text or "").strip()
+        if not snippet:
+            return None
+        if len(snippet) > MAX_INPUT_CHARS:
+            snippet = snippet[:MAX_INPUT_CHARS]
+
+        user_prompt = f"Conversation:\n---\n{snippet}\n---\n\nAnalyze the speaker's emotional state."
+
+        try:
+            resp = await self._router.complete(
+                messages=[
+                    {"role": "system", "content": _AFFECT_SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                ],
+                context={"task": "tom_affect_extraction", "max_tokens": MAX_RESPONSE_TOKENS},
+            )
+        except Exception as exc:
+            logger.warning("ToM affect extraction LLM call failed: %s", exc)
+            return None
+
+        try:
+            content = final_text(resp)
+        except ValueError:
+            return None
+        result = _parse_affect_json(content)
+        if result is not None:
+            self._mark_extracted(contact_id)
+            result["source"] = "inferred"
+            result["contact_id"] = contact_id
+            if session_id:
+                result["session_id"] = session_id
+        return result
+
+    async def extract_facts(
+        self,
+        conversation_text: str,
+        contact_id: str,
+        *,
+        session_id: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """Extract shared facts from a conversation snippet.
+
+        Returns list of dicts with fact, source, confidence.
+        Throttled per contact.
+        """
+        if not self._can_extract(contact_id, operation="facts"):
+            return []
+
+        snippet = (conversation_text or "").strip()
+        if not snippet:
+            return []
+        if len(snippet) > MAX_INPUT_CHARS:
+            snippet = snippet[:MAX_INPUT_CHARS]
+
+        user_prompt = f"Conversation:\n---\n{snippet}\n---\n\nWhat does the contact now know?"
+
+        try:
+            resp = await self._router.complete(
+                messages=[
+                    {"role": "system", "content": _FACT_SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                ],
+                context={"task": "tom_fact_extraction", "max_tokens": MAX_RESPONSE_TOKENS},
+            )
+        except Exception as exc:
+            logger.warning("ToM fact extraction LLM call failed: %s", exc)
+            return []
+
+        try:
+            content = final_text(resp)
+        except ValueError:
+            return []
+        results = _parse_fact_array(content, conversation_text=snippet)
+        self._mark_extracted(contact_id, operation="facts")
+        for r in results:
+            r["contact_id"] = contact_id
+            r['model_provenance'] = {
+                'function_role': getattr(resp, 'function_role', '') or 'extraction',
+                'model_id': getattr(resp, 'model_id', 'unknown'),
+                'config_revision': getattr(resp, 'config_revision', '') or 'unknown',
+                'weight_revision': getattr(resp, 'model_revision', '') or 'unknown'}
+        return results
+
+    async def extract_engagement(
+        self,
+        conversation_text: str,
+        contact_id: str,
+        *,
+        session_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Retired numeric personality pass; canonical appraisal worker owns this.
+
+        Retain the method for older host callers during a paired upgrade. It
+        makes no model call and never creates count-derived trait certainty.
+        """
+        return None
+
+    def _can_extract(self, contact_id: str, *, operation: str = "affect") -> bool:
+        """Check the operation's per-contact throttle."""
+        timestamps = self._last_facts if operation == "facts" else self._last_extraction
+        last = timestamps.get(contact_id)
+        if last is None:
+            return True
+        try:
+            last_dt = datetime.fromisoformat(last)
+            elapsed = (datetime.now(timezone.utc) - last_dt).total_seconds() / 60
+            return elapsed >= THROTTLE_MINUTES
+        except (ValueError, TypeError):
+            return True
+
+    def _mark_extracted(self, contact_id: str, *, operation: str = "affect") -> None:
+        timestamps = self._last_facts if operation == "facts" else self._last_extraction
+        timestamps[contact_id] = datetime.now(timezone.utc).isoformat()
+
+
+# ---------------------------------------------------------------------------
+# Parsing helpers
+# ---------------------------------------------------------------------------
+
+_CODE_FENCE = re.compile(r"^```(?:json)?\s*|\s*```$", re.MULTILINE)
+
+
+def _strip_code_fence(text: str) -> str:
+    return _CODE_FENCE.sub("", text)
+
+
+def _parse_affect_json(raw: str) -> Optional[Dict[str, Any]]:
+    """Parse LLM response into affect dict."""
+    if not raw:
+        return None
+    candidate = _strip_code_fence(raw).strip()
+    try:
+        parsed = json.loads(candidate)
+    except json.JSONDecodeError:
+        # Try to find JSON object in response
+        match = re.search(r"\{.*\}", candidate, re.DOTALL)
+        if not match:
+            return None
+        try:
+            parsed = json.loads(match.group(0))
+        except json.JSONDecodeError:
+            return None
+
+    if not isinstance(parsed, dict):
+        return None
+
+    valence = parsed.get("valence", 0.0)
+    arousal = parsed.get("arousal", 0.3)
+    confidence = parsed.get("confidence", 0.5)
+
+    try:
+        valence = max(-1.0, min(1.0, float(valence)))
+        arousal = max(0.0, min(1.0, float(arousal)))
+        confidence = max(0.0, min(1.0, float(confidence)))
+    except (TypeError, ValueError):
+        return None
+
+    # Skip neutral readings — not worth storing
+    if abs(valence) < 0.1 and abs(arousal - 0.3) < 0.1:
+        return None
+
+    return {
+        "valence": valence,
+        "arousal": arousal,
+        "trigger": parsed.get("trigger"),
+        "confidence": confidence,
+    }
+
+
+def _parse_fact_array(raw: str, *, conversation_text: str = "") -> List[Dict[str, Any]]:
+    """Accept useful quotations; unsupported output remains conversation history."""
+    if not raw:
+        return []
+    candidate = _strip_code_fence(raw).strip()
+    try:
+        parsed = json.loads(candidate)
+    except json.JSONDecodeError:
+        match = re.search(r"\[.*\]", candidate, re.DOTALL)
+        if not match:
+            return []
+        try:
+            parsed = json.loads(match.group(0))
+        except json.JSONDecodeError:
+            return []
+
+    if isinstance(parsed, dict):
+        parsed = parsed.get("facts") or parsed.get("items") or []
+    if not isinstance(parsed, list) or len(parsed) > 6:
+        return []
+
+    facts: List[Dict[str, Any]] = []
+    for item in parsed:
+        if not isinstance(item, dict):
+            continue
+        fact_text = item.get("evidence")
+        quality = promotion_metadata(item)
+        if (not isinstance(fact_text, str) or not fact_text.strip()
+                or len(fact_text) > 500 or fact_text not in conversation_text or quality is None):
+            continue
+        source = item.get("source", "inferred")
+        if source not in ("told_by_contact", "told_to_contact", "shared_context", "inferred"):
+            source = "inferred"
+        confidence = item.get("confidence", 0.7)
+        try:
+            confidence = max(0.0, min(1.0, float(confidence)))
+        except (TypeError, ValueError):
+            confidence = 0.7
+        facts.append({
+            "fact": fact_text.strip(),
+            "source": source,
+            "confidence": confidence,
+            "memory_quality": quality,
+        })
+    unique = {}
+    for fact in facts:
+        unique.setdefault((fact['source'], fact['fact']), fact)
+    return list(unique.values())

apsimo/tom/fact_adapters.py

@@ -0,0 +1,144 @@
+"""Pure P8 fact adapters with an explicit server-authority boundary.
+
+Models and request bodies may propose only fact content and confidence.  Fact
+identity, source, subject, audience, shareability, evidence, and freshness are
+accepted solely through the typed ``ServerFactAuthorityV1`` input.  Unknown
+untrusted fields are rejected rather than silently ignored so a future caller
+cannot accidentally make a body/model field authoritative during refactoring.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import math
+from typing import Any, Mapping
+
+from apsimo.tom.visibility import (
+    FactCandidateV1,
+    FactVisibilityV1,
+    content_digest,
+)
+
+
+class FactAuthorityBoundaryError(ValueError):
+    """Untrusted input attempted to cross the fact-authority boundary."""
+
+
+def _iso(value: datetime | str, *, field: str) -> str:
+    if isinstance(value, datetime):
+        parsed = value
+    else:
+        try:
+            parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"{field} must be an ISO-8601 timestamp") from exc
+    if parsed.tzinfo is None:
+        raise ValueError(f"{field} must include a timezone")
+    return parsed.astimezone(timezone.utc).isoformat()
+
+
+@dataclass(frozen=True, slots=True)
+class FactPayloadV1:
+    """The complete set of fields an untrusted fact producer may propose."""
+
+    content: str
+    confidence: float
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.content, str) or not self.content.strip():
+            raise ValueError("fact content is required")
+        if isinstance(self.confidence, bool):
+            raise ValueError("fact confidence must be finite and between zero and one")
+        try:
+            confidence = float(self.confidence)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                "fact confidence must be finite and between zero and one") from exc
+        if not math.isfinite(confidence) or not 0.0 <= confidence <= 1.0:
+            raise ValueError(
+                "fact confidence must be finite and between zero and one")
+        object.__setattr__(self, "confidence", confidence)
+
+    @classmethod
+    def from_untrusted(
+        cls,
+        fields: Mapping[str, Any],
+        *,
+        origin: str,
+    ) -> "FactPayloadV1":
+        """Whitelist content/confidence and reject every other input field."""
+
+        label = str(origin or "untrusted").strip().lower() or "untrusted"
+        if not isinstance(fields, Mapping):
+            raise FactAuthorityBoundaryError(
+                f"{label} fact payload must be a structured mapping")
+        allowed = {"content", "confidence"}
+        rejected = sorted(str(key) for key in fields if key not in allowed)
+        if rejected:
+            raise FactAuthorityBoundaryError(
+                f"{label} field {rejected[0]} cannot supply fact authority")
+        missing = sorted(allowed.difference(fields))
+        if missing:
+            raise ValueError(f"{label} fact payload is missing {missing[0]}")
+        return cls(
+            content=fields["content"],
+            confidence=fields["confidence"],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ServerFactAuthorityV1:
+    """Structured authority derived from authenticated server-side state."""
+
+    fact_ref: str
+    source_ref: str
+    subject_person_id: str
+    viewer_scope: str
+    shareability: str
+    observed_at: datetime | str
+    fresh_until: datetime | str
+    evidence_refs: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "observed_at", _iso(self.observed_at, field="observed_at"))
+        object.__setattr__(
+            self, "fresh_until", _iso(self.fresh_until, field="fresh_until"))
+        object.__setattr__(self, "evidence_refs", tuple(self.evidence_refs))
+
+
+def build_fact_candidate(
+    *,
+    authority: ServerFactAuthorityV1,
+    payload: FactPayloadV1,
+) -> FactCandidateV1:
+    """Combine typed server authority with a non-authoritative fact payload."""
+
+    if not isinstance(authority, ServerFactAuthorityV1):
+        raise FactAuthorityBoundaryError(
+            "fact visibility authority must be a server-derived structured input")
+    if not isinstance(payload, FactPayloadV1):
+        raise FactAuthorityBoundaryError(
+            "fact content must be a bounded FactPayloadV1 input")
+    visibility = FactVisibilityV1(
+        fact_ref=authority.fact_ref,
+        content_digest=content_digest(payload.content),
+        source_ref=authority.source_ref,
+        subject_person_id=authority.subject_person_id,
+        viewer_scope=authority.viewer_scope,
+        shareability=authority.shareability,
+        confidence=payload.confidence,
+        observed_at=authority.observed_at,
+        fresh_until=authority.fresh_until,
+        evidence_refs=authority.evidence_refs,
+    )
+    return FactCandidateV1(content=payload.content, visibility=visibility)
+
+
+__all__ = [
+    "FactAuthorityBoundaryError",
+    "FactPayloadV1",
+    "ServerFactAuthorityV1",
+    "build_fact_candidate",
+]