rememberstack 0.1.0__py3-none-any.whl

rememberstack/core/knowledge_fact_sheet.py

@@ -0,0 +1,210 @@
+"""Pure deterministic Plane-K fact-sheet rendering (D45, WP-6.3)."""
+
+from datetime import datetime
+from enum import StrEnum
+from uuid import UUID
+
+from pydantic import TypeAdapter
+
+from rememberstack.model import KnowledgeFactSheetFact
+from rememberstack.model import KnowledgeFactSheetSnapshot
+from rememberstack.model import KnowledgeRenderedFactSheet
+from rememberstack.model import UTCDateTime
+
+_UTC_ADAPTER = TypeAdapter(UTCDateTime)
+
+
+class KnowledgeFactLifecycle(StrEnum):
+    """A fact's literal state at the fixed evidence snapshot timestamp."""
+
+    CURRENT = "current"
+    ENDED = "ended"
+    INVALIDATED = "invalidated"
+    NOT_YET_VALID = "not yet valid"
+
+
+def render_knowledge_fact_sheet(
+    *,
+    snapshot: KnowledgeFactSheetSnapshot,
+    compiled_at: UTCDateTime,
+    citation_count: int,
+    candidate_count: int | None = None,
+) -> KnowledgeRenderedFactSheet:
+    """Render exact current relations, observation history, and open tensions."""
+    if citation_count < 0:
+        raise ValueError("citation_count must be non-negative")
+    if candidate_count is not None and candidate_count < 0:
+        raise ValueError("candidate_count must be non-negative")
+    compiled_at = _UTC_ADAPTER.validate_python(compiled_at)
+    current_relations = tuple(
+        sorted(
+            (
+                fact
+                for fact in snapshot.facts
+                if fact.kind == "relation"
+                and _lifecycle(fact=fact, evidence_as_of=snapshot.evidence_as_of)
+                is KnowledgeFactLifecycle.CURRENT
+            ),
+            key=lambda fact: (
+                -fact.evidence_count,
+                fact.label.casefold(),
+                str(fact.fact_id),
+            ),
+        )
+    )
+    observations = tuple(
+        sorted(
+            (fact for fact in snapshot.facts if fact.kind == "observation"),
+            key=lambda fact: (
+                _time_key(value=fact.valid_from),
+                _time_key(value=fact.ingested_at),
+                str(fact.fact_id),
+            ),
+        )
+    )
+    contradiction_groups = _open_contradiction_groups(facts=snapshot.facts)
+
+    lines = [
+        "## Fact sheet (generated)",
+        "",
+        "### Current relations",
+        "",
+        "| fact | valid since | evidence | reference |",
+        "|---|---|---:|---|",
+    ]
+    if current_relations:
+        lines.extend(
+            f"| {_cell(fact.label)} | {_timestamp(fact.valid_from)} | "
+            f"{fact.evidence_count} docs | `relation:{fact.fact_id}` |"
+            for fact in current_relations
+        )
+    else:
+        lines.append("| _None._ | — | 0 docs | — |")
+
+    lines.extend(
+        (
+            "",
+            "### Observation history",
+            "",
+            "| observation | valid from | valid until | state | evidence | reference |",
+            "|---|---|---|---|---:|---|",
+        )
+    )
+    if observations:
+        lines.extend(
+            f"| {_cell(fact.label)} | {_timestamp(fact.valid_from)} | "
+            f"{_timestamp(fact.valid_until)} | "
+            f"{_lifecycle(fact=fact, evidence_as_of=snapshot.evidence_as_of).value} | "
+            f"{fact.evidence_count} docs | `observation:{fact.fact_id}` |"
+            for fact in observations
+        )
+    else:
+        lines.append("| _None._ | — | — | — | 0 docs | — |")
+
+    lines.extend(("", "### Open contradictions", ""))
+    if contradiction_groups:
+        lines.extend(
+            (
+                "| group | fact | state | evidence | reference |",
+                "|---|---|---|---:|---|",
+            )
+        )
+        for group_id, members in contradiction_groups:
+            lines.extend(
+                f"| `{group_id}` | {_cell(fact.label)} | "
+                f"{_lifecycle(fact=fact, evidence_as_of=snapshot.evidence_as_of).value} | "
+                f"{fact.evidence_count} docs | `{fact.kind}:{fact.fact_id}` |"
+                for fact in members
+            )
+    else:
+        lines.append("_None._")
+
+    if candidate_count is None:
+        candidate_count = len(snapshot.input_snapshot.facts) + len(
+            snapshot.input_snapshot.claims
+        )
+    lines.extend(
+        (
+            "",
+            "---",
+            f"_compiled {_timestamp(compiled_at)} · "
+            f"evidence as of {_timestamp(snapshot.evidence_as_of)} · "
+            f"{candidate_count} candidates · {citation_count} citations_",
+            "",
+        )
+    )
+    return KnowledgeRenderedFactSheet(
+        markdown="\n".join(lines),
+        current_relation_count=len(current_relations),
+        observation_count=len(observations),
+        contradiction_group_count=len(contradiction_groups),
+    )
+
+
+def compose_knowledge_page(
+    *, prose_markdown: str | None, fact_sheet_markdown: str
+) -> str:
+    """Compose a two-band page, or the fact-sheet band alone with zero prose."""
+    fact_sheet = fact_sheet_markdown.strip()
+    if not fact_sheet:
+        raise ValueError("fact_sheet_markdown must be non-empty")
+    if prose_markdown is None or not prose_markdown.strip():
+        return f"{fact_sheet}\n"
+    return f"{prose_markdown.rstrip()}\n\n---\n{fact_sheet}\n"
+
+
+def _lifecycle(
+    *, fact: KnowledgeFactSheetFact, evidence_as_of: datetime
+) -> KnowledgeFactLifecycle:
+    """Classify one fact without confusing validity end with invalidation."""
+    if fact.invalidated_at is not None:
+        return KnowledgeFactLifecycle.INVALIDATED
+    if fact.valid_from is not None and fact.valid_from > evidence_as_of:
+        return KnowledgeFactLifecycle.NOT_YET_VALID
+    if fact.valid_until is not None and fact.valid_until <= evidence_as_of:
+        return KnowledgeFactLifecycle.ENDED
+    return KnowledgeFactLifecycle.CURRENT
+
+
+def _open_contradiction_groups(
+    *, facts: tuple[KnowledgeFactSheetFact, ...]
+) -> tuple[tuple[UUID, tuple[KnowledgeFactSheetFact, ...]], ...]:
+    """Group every non-invalidated selected side of an unresolved contradiction."""
+    grouped: dict[UUID, list[KnowledgeFactSheetFact]] = {}
+    for fact in facts:
+        if fact.contradiction_group is None or fact.invalidated_at is not None:
+            continue
+        grouped.setdefault(fact.contradiction_group, []).append(fact)
+    return tuple(
+        (
+            group_id,
+            tuple(
+                sorted(
+                    members,
+                    key=lambda fact: (
+                        fact.kind,
+                        fact.label.casefold(),
+                        str(fact.fact_id),
+                    ),
+                )
+            ),
+        )
+        for group_id, members in sorted(grouped.items(), key=lambda item: str(item[0]))
+    )
+
+
+def _timestamp(value: datetime | None) -> str:
+    """Render full UTC precision without locale or machine-timezone dependence."""
+    if value is None:
+        return "—"
+    return value.isoformat().replace("+00:00", "Z")
+
+
+def _time_key(*, value: datetime | None) -> tuple[int, str]:
+    """Sort unknown starts first, then aware timestamps in chronological order."""
+    return (0, "") if value is None else (1, value.isoformat())
+
+
+def _cell(value: str) -> str:
+    """Keep arbitrary fact labels inside one Markdown table cell."""
+    return " ".join(value.split()).replace("\\", "\\\\").replace("|", "\\|")

rememberstack/core/knowledge_hashing.py

@@ -0,0 +1,68 @@
+"""Canonical Plane-K input hashing (D45/D54)."""
+
+import hashlib
+import json
+
+from pydantic import JsonValue
+from pydantic import TypeAdapter
+
+from rememberstack.model import KnowledgeInputSnapshot
+
+_JSON_ADAPTER = TypeAdapter(JsonValue)
+
+
+def knowledge_inputs_hash(*, snapshot: KnowledgeInputSnapshot) -> str:
+    """Return the order-independent D45 staleness key for one page.
+
+    Relations and observations retain their state fingerprints. Claim-grain
+    candidates deliberately contain only ``(lineage, chunk_content_hash)``;
+    raw claim IDs and text are absent so a semantically unchanged extraction
+    generation cannot create a stale storm (D54).
+    """
+    payload = _JSON_ADAPTER.validate_python(
+        {
+            "facts": _sorted_unique(
+                values=[fact.model_dump(mode="json") for fact in snapshot.facts]
+            ),
+            "claims": _sorted_unique(
+                values=[claim.model_dump(mode="json") for claim in snapshot.claims]
+            ),
+            "rules": _sorted_unique(
+                values=[
+                    {"kind": rule.kind.value, "params": rule.params}
+                    for rule in snapshot.rules
+                ]
+            ),
+            "curation_hash": snapshot.curation_hash,
+            # Multiplicity is meaningful here: two children with identical
+            # summaries are still two DAG inputs, while candidate rules are a set.
+            "child_summary_hashes": sorted(snapshot.child_summary_hashes),
+            "shared_model_summary_hash": snapshot.shared_model_summary_hash,
+            "writer_version": snapshot.writer_version,
+        }
+    )
+    canonical = json.dumps(
+        payload, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+    )
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def knowledge_summary_hash(*, summary: str) -> str:
+    """Hash a child/model page summary for inclusion in a parent's manifest."""
+    return hashlib.sha256(summary.encode("utf-8")).hexdigest()
+
+
+def knowledge_content_hash(*, markdown: str) -> str:
+    """Hash the exact UTF-8 bytes of a compiled Markdown page."""
+    return hashlib.sha256(markdown.encode("utf-8")).hexdigest()
+
+
+def _sorted_unique(*, values: list[JsonValue]) -> list[JsonValue]:
+    """Sort JSON values canonically and remove set-union duplicates."""
+    by_json = {
+        json.dumps(
+            value, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+        ): value
+        for value in values
+    }
+    return [by_json[key] for key in sorted(by_json)]

rememberstack/core/knowledge_planner.py

@@ -0,0 +1,64 @@
+"""Pure Plane-K planning hashes, trigger selection, and D24-style banding."""
+
+from decimal import Decimal
+import hashlib
+import json
+
+from rememberstack.model import KnowledgeConvertKindProposal
+from rememberstack.model import KnowledgePageKind
+from rememberstack.model import KnowledgePlanBand
+from rememberstack.model import KnowledgePlanningSnapshot
+from rememberstack.model import KnowledgePlanProposal
+from rememberstack.model import KnowledgePlanRunKind
+from rememberstack.model import KnowledgePlanTrigger
+
+
+def knowledge_planning_input_hash(*, snapshot: KnowledgePlanningSnapshot) -> str:
+    """Hash one canonical planning snapshot for replay and cost attribution."""
+    payload = json.dumps(
+        snapshot.model_dump(mode="json"), sort_keys=True, separators=(",", ":")
+    ).encode()
+    return hashlib.sha256(payload).hexdigest()
+
+
+def primary_knowledge_plan_trigger(
+    *, snapshot: KnowledgePlanningSnapshot, run_kind: KnowledgePlanRunKind
+) -> KnowledgePlanTrigger:
+    """Choose one stable ledger trigger while retaining every input in the snapshot."""
+    if run_kind is KnowledgePlanRunKind.REFLECTION:
+        return KnowledgePlanTrigger.REFLECTION
+    if snapshot.orphan_aggregates:
+        return KnowledgePlanTrigger.ORPHAN_EVIDENCE
+    if snapshot.overflow_artifact_ids:
+        return KnowledgePlanTrigger.SIZE_OVERFLOW
+    if snapshot.community_ids:
+        return KnowledgePlanTrigger.COMMUNITY_CHANGE
+    if snapshot.writer_suggestions:
+        return KnowledgePlanTrigger.WRITER_SUGGESTION
+    return KnowledgePlanTrigger.HUMAN
+
+
+def route_knowledge_plan(
+    *,
+    proposal: KnowledgePlanProposal,
+    run_kind: KnowledgePlanRunKind,
+    blast_radius: int,
+    auto_apply_max_expected_impact: Decimal,
+) -> tuple[KnowledgePlanBand, Decimal]:
+    """Route a proposal mechanically from impact, with the two binding exceptions."""
+    if blast_radius < 0:
+        raise ValueError("blast_radius must be non-negative")
+    if auto_apply_max_expected_impact < 0:
+        raise ValueError("auto-apply threshold must be non-negative")
+    expected_impact = Decimal(blast_radius) * (Decimal("1") - proposal.confidence)
+    requires_author_confirmation = (
+        isinstance(proposal, KnowledgeConvertKindProposal)
+        and proposal.to_kind is KnowledgePageKind.COMPILED
+    )
+    if (
+        run_kind is KnowledgePlanRunKind.REFLECTION
+        or requires_author_confirmation
+        or expected_impact > auto_apply_max_expected_impact
+    ):
+        return KnowledgePlanBand.REVIEW, expected_impact
+    return KnowledgePlanBand.AUTO_APPLY, expected_impact

rememberstack/core/knowledge_writer.py

@@ -0,0 +1,175 @@
+"""Deterministic bundle capping, rendering, and completeness accounting."""
+
+from collections.abc import Collection
+import json
+from uuid import UUID
+
+from rememberstack.model import KnowledgeCitation
+from rememberstack.model import KnowledgeEvidenceRole
+from rememberstack.model import KnowledgeEvidenceTarget
+from rememberstack.model import KnowledgeWriterBundle
+from rememberstack.model import KnowledgeWriterClaimGroup
+from rememberstack.model import KnowledgeWriterCoverage
+
+
+def cap_knowledge_writer_bundle(
+    *,
+    bundle: KnowledgeWriterBundle,
+    exclusions: Collection[KnowledgeEvidenceTarget],
+    residue_claim_limit: int,
+    evidence_claims_per_fact: int,
+) -> KnowledgeWriterBundle:
+    """Filter curation exclusions and cap D54 claim coordinates deterministically."""
+    if residue_claim_limit < 0 or evidence_claims_per_fact < 0:
+        raise ValueError("writer claim limits must be non-negative")
+    excluded_relations = {
+        item.relation_id for item in exclusions if item.relation_id is not None
+    }
+    excluded_claim_coordinates = {
+        (item.claim_lineage_id, item.claim_chunk_content_hash)
+        for item in exclusions
+        if item.claim_lineage_id is not None
+    }
+    excluded_docs = {item.doc_id for item in exclusions if item.doc_id is not None}
+    facts = tuple(
+        fact
+        for fact in bundle.fact_sheet.facts
+        if fact.kind != "relation" or fact.fact_id not in excluded_relations
+    )
+    fact_keys = {(fact.kind, fact.fact_id) for fact in facts}
+    groups: list[KnowledgeWriterClaimGroup] = []
+    for group in bundle.claim_groups:
+        if (
+            group.lineage_id in excluded_docs
+            or _claim_group_key(group) in excluded_claim_coordinates
+        ):
+            continue
+        claims = []
+        for claim in group.claims:
+            references = tuple(
+                reference
+                for reference in claim.fact_references
+                if (reference.kind, reference.fact_id) in fact_keys
+            )
+            if claim.fact_references and not references:
+                # Evidence for an excluded fact must not silently re-enter as
+                # uncategorized residue after its fact reference is stripped.
+                continue
+            claims.append(claim.model_copy(update={"fact_references": references}))
+        if claims:
+            groups.append(group.model_copy(update={"claims": tuple(claims)}))
+
+    ordered = tuple(sorted(groups, key=_claim_group_key))
+    by_fact: dict[tuple[str, UUID], list[KnowledgeWriterClaimGroup]] = {}
+    residue: list[KnowledgeWriterClaimGroup] = []
+    for group in ordered:
+        references = {
+            (reference.kind, reference.fact_id)
+            for claim in group.claims
+            for reference in claim.fact_references
+        }
+        if not references:
+            residue.append(group)
+        for reference in references:
+            by_fact.setdefault(reference, []).append(group)
+
+    selected: dict[tuple[UUID, str], KnowledgeWriterClaimGroup] = {
+        _claim_group_key(group): group for group in residue[:residue_claim_limit]
+    }
+    for fact in sorted(
+        facts, key=lambda item: (-item.evidence_count, item.kind, str(item.fact_id))
+    ):
+        for group in by_fact.get((fact.kind, fact.fact_id), ())[
+            :evidence_claims_per_fact
+        ]:
+            selected[_claim_group_key(group)] = group
+    offered = tuple(selected[key] for key in sorted(selected, key=_sortable_group_key))
+    return KnowledgeWriterBundle(
+        fact_sheet=bundle.fact_sheet.model_copy(update={"facts": facts}),
+        claim_groups=offered,
+        claim_candidate_count=len(ordered),
+        claims_cut_count=len(ordered) - len(offered),
+    )
+
+
+def render_knowledge_writer_bundle(*, bundle: KnowledgeWriterBundle) -> str:
+    """Render only offered evidence into stable JSON with citation IDs inline."""
+    payload = {
+        "artifact_id": str(bundle.fact_sheet.artifact_id),
+        "deployment_id": str(bundle.fact_sheet.deployment_id),
+        "evidence_as_of": bundle.fact_sheet.evidence_as_of.isoformat(),
+        "facts": [item.model_dump(mode="json") for item in bundle.fact_sheet.facts],
+        "claim_groups": [item.model_dump(mode="json") for item in bundle.claim_groups],
+        "ledger": {
+            "fact_candidates_offered": len(bundle.fact_sheet.facts),
+            "claim_candidates_offered": len(bundle.claim_groups),
+            "claim_candidates_cut": bundle.claims_cut_count,
+        },
+    }
+    return f"{json.dumps(payload, sort_keys=True, indent=2)}\n"
+
+
+def knowledge_writer_coverage(
+    *, bundle: KnowledgeWriterBundle, citations: tuple[KnowledgeCitation, ...]
+) -> KnowledgeWriterCoverage:
+    """Count direct and support-claim coverage without trusting writer-reported totals."""
+    cited_relations = {
+        item.relation_id for item in citations if item.relation_id is not None
+    }
+    cited_claims = {
+        (item.claim_lineage_id, item.claim_chunk_content_hash)
+        for item in citations
+        if item.claim_lineage_id is not None
+    }
+    cited_docs = {item.doc_id for item in citations if item.doc_id is not None}
+    supporting_claims = {
+        (item.claim_lineage_id, item.claim_chunk_content_hash)
+        for item in citations
+        if item.claim_lineage_id is not None
+        and item.role in (KnowledgeEvidenceRole.SUPPORTS, KnowledgeEvidenceRole.CITES)
+    }
+    supporting_docs = {
+        item.doc_id
+        for item in citations
+        if item.doc_id is not None
+        and item.role in (KnowledgeEvidenceRole.SUPPORTS, KnowledgeEvidenceRole.CITES)
+    }
+
+    cited_groups: set[tuple[UUID, str]] = set()
+    supported_facts: set[tuple[str, UUID]] = set()
+    for group in bundle.claim_groups:
+        coordinate = _claim_group_key(group)
+        group_used = group.lineage_id in cited_docs or coordinate in cited_claims
+        for claim in group.claims:
+            if coordinate in supporting_claims or claim.lineage_id in supporting_docs:
+                supported_facts.update(
+                    (reference.kind, reference.fact_id)
+                    for reference in claim.fact_references
+                    if reference.stance == "supports"
+                )
+        if group_used:
+            cited_groups.add(_claim_group_key(group))
+
+    cited_facts = {
+        (fact.kind, fact.fact_id)
+        for fact in bundle.fact_sheet.facts
+        if (fact.kind == "relation" and fact.fact_id in cited_relations)
+        or (fact.kind, fact.fact_id) in supported_facts
+    }
+    candidate_count = len(bundle.fact_sheet.facts) + len(bundle.claim_groups)
+    cited_candidate_count = len(cited_facts) + len(cited_groups)
+    return KnowledgeWriterCoverage(
+        candidate_count=candidate_count,
+        cited_candidate_count=cited_candidate_count,
+        uncited_count=candidate_count - cited_candidate_count,
+    )
+
+
+def _claim_group_key(group: KnowledgeWriterClaimGroup) -> tuple[UUID, str]:
+    """Return one D54 coordinate in its typed form."""
+    return group.lineage_id, group.chunk_content_hash
+
+
+def _sortable_group_key(key: tuple[UUID, str]) -> tuple[str, str]:
+    """Convert one D54 coordinate to a stable total-order key."""
+    return str(key[0]), key[1]