lp2graph 0.3.0__py3-none-any.whl

lp2graph/mining/cluster/taxonomy.py

@@ -0,0 +1,268 @@
+"""Bottom-up multi-level taxonomy induction (M3).
+
+Runs the ``CN`` operator at each level of the method's bottom-up taxonomy:
+
+- **Level V** — decision variables and parameters, clustered on lexical
+  concepts + their type signatures.
+- **Level C** — constraints and the objective, clustered on lexical concepts
+  + type signatures *conditioned on Level-V membership*: each constraint's
+  referenced variables contribute a ``vcluster:<name>`` feature, so two
+  constraints that bind structurally-similar variable families are pulled
+  together.
+- **Level M** — whole models, clustered on family/type histograms, presence
+  flags, and bucketed structural metrics.
+
+Plus two text-only one-dimensional clusterings — **domain** and **solution
+approach** — over the model-level free text.
+
+The whole induction is deterministic given the versioned
+:class:`~lp2graph.mining.cluster.operator.ClusterConfig`.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from lp2graph.core.model import ConstraintTemplate, Formulation
+from lp2graph.metrics.flags import presence_flags
+from lp2graph.metrics.structural import model_completeness, structural_summary
+from lp2graph.mining.cluster.operator import CN, ClusterConfig, NamedClustering
+from lp2graph.mining.homologize.concept import concept_bag
+from lp2graph.mining.homologize.entity import (
+    Entity,
+    corpus_entities,
+    signature_documents,
+    text_dimension,
+)
+from lp2graph.mining.homologize.vectorize import (
+    ConceptVectorizer,
+    Vocabulary,
+    build_vocabulary,
+)
+from lp2graph.views.schema import schema
+
+
+@dataclass(frozen=True, slots=True)
+class LevelResult:
+    """One level's entities, vocabulary, and named clustering."""
+
+    level: str
+    entities: tuple[Entity, ...]
+    vocabulary: Vocabulary
+    clustering: NamedClustering
+
+    def named_partition(self) -> dict[str, tuple[str, ...]]:
+        """Map cluster name → the entity ids it contains (for reporting)."""
+        out: dict[str, tuple[str, ...]] = {}
+        for cid, idxs in self.clustering.members.items():
+            name = self.clustering.names[cid]
+            out[name] = tuple(self.entities[i].id for i in idxs)
+        return out
+
+
+@dataclass(frozen=True, slots=True)
+class Taxonomy:
+    """The full multi-level taxonomy over a corpus."""
+
+    level_v: LevelResult
+    level_c: LevelResult
+    level_m: LevelResult
+    domain: LevelResult
+    solution_approach: LevelResult
+
+    def summary(self) -> dict[str, int]:
+        """Cluster counts per level (a compact, diffable digest)."""
+        return {
+            "V": self.level_v.clustering.n_clusters,
+            "C": self.level_c.clustering.n_clusters,
+            "M": self.level_m.clustering.n_clusters,
+            "domain": self.domain.clustering.n_clusters,
+            "solution_approach": self.solution_approach.clustering.n_clusters,
+        }
+
+
+def _merge(*docs: dict[str, int]) -> dict[str, int]:
+    merged: Counter[str] = Counter()
+    for d in docs:
+        merged.update(d)
+    return dict(merged)
+
+
+def _run_pass(
+    level: str,
+    entities: Sequence[Entity],
+    documents: Sequence[dict[str, int]],
+    config: ClusterConfig,
+) -> LevelResult:
+    vocab = build_vocabulary(documents)
+    _vectorizer, vectors = ConceptVectorizer.fit_transform(documents, vocabulary=vocab)
+    clustering = CN(entities, vectors, vocab, config)
+    return LevelResult(
+        level=level,
+        entities=tuple(entities),
+        vocabulary=vocab,
+        clustering=clustering,
+    )
+
+
+def _referenced_variable_ids(f: Formulation) -> dict[str, list[str]]:
+    """Map each Level-C entity id of ``f`` to the variable entity ids it uses."""
+    out: dict[str, list[str]] = {}
+    for c in f.constraints:
+        cid = f"{f.id}::constraint::{c.name}"
+        refs = sorted({t.ref for t in (*c.lhs, *c.rhs) if t.ref_kind == "variable"})
+        out[cid] = [f"{f.id}::variable::{r}" for r in refs]
+    if f.objective is not None:
+        oid = f"{f.id}::objective::{f.objective.name}"
+        refs = sorted({t.ref for t in f.objective.terms if t.ref_kind == "variable"})
+        out[oid] = [f"{f.id}::variable::{r}" for r in refs]
+    return out
+
+
+_DENSITY_EDGES = (0.05, 0.15, 0.30)
+_CVR_EDGES = (0.75, 1.25, 2.0)
+
+
+def _bucket(value: float, edges: Sequence[float]) -> int:
+    for i, e in enumerate(edges):
+        if value < e:
+            return i
+    return len(edges)
+
+
+_SIZE_EDGES = (10.0, 50.0, 200.0, 1000.0)
+_DIAMETER_CAP = 12
+
+
+def model_feature_document(f: Formulation) -> dict[str, int]:
+    """Level-M structural feature document.
+
+    Covers the model-level channel of the paper's Level M: the presence-flag
+    vector ``φ`` and the structural metrics of Sec.~lp2graph — minimal size
+    ``S_min``, constraint/variable ratio ``R_C/V``, graph diameter ``D_G``,
+    edge density, and the two well-formedness indicators (coherence and
+    completeness) — each bucketed (or flagged) so it joins the
+    TF-IDF feature space. The raw declarative kind histograms are retained as
+    supplementary signal; the *induced* Level-V/Level-C cluster histograms are
+    added on top in :func:`induce` (they need the lower passes' output).
+    """
+    doc: Counter[str] = Counter()
+    doc[f"family:{f.family}"] += 1
+    for c in f.constraints:
+        doc[f"ckind:{c.kind}"] += 1
+        if c.domain_class:
+            doc[f"cdom:{c.domain_class}"] += 1
+    for v in f.variables:
+        doc[f"vdom:{v.domain}"] += 1
+        if v.domain_role:
+            doc[f"vrole:{v.domain_role}"] += 1
+    for name, result in presence_flags(f).items():
+        if bool(result.value):
+            doc[f"flag:{name}"] += 1
+    g = schema(f)
+    metrics = structural_summary(g)
+    density = float(metrics["edge_density"].value)
+    cvr = float(metrics["constraint_variable_ratio"].value)
+    size = float(metrics["minimal_size"].value)
+    diameter = int(metrics["graph_diameter"].value)
+    coherent = int(metrics["model_coherence"].value)
+    complete = int(model_completeness(f).value)
+    doc[f"density_bin:{_bucket(density, _DENSITY_EDGES)}"] += 1
+    doc[f"cvr_bin:{_bucket(cvr, _CVR_EDGES)}"] += 1
+    doc[f"size_bin:{_bucket(size, _SIZE_EDGES)}"] += 1
+    doc[f"diam:{min(diameter, _DIAMETER_CAP)}"] += 1
+    doc[f"coherent:{coherent}"] += 1
+    doc[f"complete:{complete}"] += 1
+    return dict(doc)
+
+
+def induce(formulations: Sequence[Formulation], config: ClusterConfig | None = None) -> Taxonomy:
+    """Induce the full multi-level taxonomy over ``formulations``."""
+    cfg = config or ClusterConfig()
+
+    # Level V -------------------------------------------------------------
+    v_entities = corpus_entities(formulations, "V")
+    v_sig = signature_documents(v_entities)
+    v_docs = [_merge(concept_bag(e.text), v_sig[i]) for i, e in enumerate(v_entities)]
+    level_v = _run_pass("V", v_entities, v_docs, cfg)
+    v_label_by_id = {e.id: level_v.clustering.name_of(i) for i, e in enumerate(v_entities)}
+
+    # Level C (conditioned on Level-V membership) -------------------------
+    c_entities = corpus_entities(formulations, "C")
+    c_sig = signature_documents(c_entities)
+    ref_map: dict[str, list[str]] = {}
+    con_by_id: dict[str, ConstraintTemplate] = {}
+    for f in formulations:
+        ref_map.update(_referenced_variable_ids(f))
+        for c in f.constraints:
+            con_by_id[f"{f.id}::constraint::{c.name}"] = c
+    c_docs: list[dict[str, int]] = []
+    for i, e in enumerate(c_entities):
+        cond: Counter[str] = Counter()
+        # Histogram of Level-V cluster membership over the coupled variables.
+        for vid in ref_map.get(e.id, []):
+            name = v_label_by_id.get(vid)
+            if name is not None:
+                cond[f"vcluster:{name}"] += 1
+        # Relevant per-constraint presence flags (paper Level C: big-M,
+        # aggregation). Comparator + quantifier/restriction pattern + referent
+        # multiset already arrive via the signature document (c_sig).
+        con = con_by_id.get(e.id)
+        if con is not None:
+            if con.kind == "big_m" or con.indicator is not None:
+                cond["cflag:big_m"] += 1
+            if any(t.operator != "none" for t in (*con.lhs, *con.rhs)):
+                cond["cflag:aggregation"] += 1
+        c_docs.append(_merge(concept_bag(e.text), c_sig[i], dict(cond)))
+    level_c = _run_pass("C", c_entities, c_docs, cfg)
+    c_label_by_id = {e.id: level_c.clustering.name_of(i) for i, e in enumerate(c_entities)}
+
+    # Level M (conditioned on the induced Level-V/Level-C partitions) ------
+    m_entities = corpus_entities(formulations, "M")
+    m_docs: list[dict[str, int]] = []
+    for f in formulations:
+        induced: Counter[str] = Counter()
+        # Histogram of induced Level-C families present in the model.
+        for c in f.constraints:
+            fam = c_label_by_id.get(f"{f.id}::constraint::{c.name}")
+            if fam is not None:
+                induced[f"cfamily:{fam}"] += 1
+        if f.objective is not None:
+            fam = c_label_by_id.get(f"{f.id}::objective::{f.objective.name}")
+            if fam is not None:
+                induced[f"cfamily:{fam}"] += 1
+        # Histogram of induced Level-V types (variables and parameters).
+        for v in f.variables:
+            vtype = v_label_by_id.get(f"{f.id}::variable::{v.name}")
+            if vtype is not None:
+                induced[f"vtype:{vtype}"] += 1
+        for p in f.parameters:
+            vtype = v_label_by_id.get(f"{f.id}::parameter::{p.name}")
+            if vtype is not None:
+                induced[f"vtype:{vtype}"] += 1
+        m_docs.append(_merge(model_feature_document(f), dict(induced)))
+    level_m = _run_pass("M", m_entities, m_docs, cfg)
+
+    # Text-only one-dimensional clusterings -------------------------------
+    domain_docs = [concept_bag(text_dimension(e, "domain")) for e in m_entities]
+    domain = _run_pass("domain", m_entities, [dict(d) for d in domain_docs], cfg)
+    sol_docs = [concept_bag(text_dimension(e, "solution_approach")) for e in m_entities]
+    solution = _run_pass("solution_approach", m_entities, [dict(d) for d in sol_docs], cfg)
+
+    return Taxonomy(
+        level_v=level_v,
+        level_c=level_c,
+        level_m=level_m,
+        domain=domain,
+        solution_approach=solution,
+    )
+
+
+__all__ = [
+    "LevelResult",
+    "Taxonomy",
+    "induce",
+    "model_feature_document",
+]

lp2graph/mining/corpusmgr/__init__.py

@@ -0,0 +1,70 @@
+"""M5 — corpus & provenance manager.
+
+The corpus manager makes the extracted corpus *regenerable from queries +
+freeze date* and makes representative selection a pure, reproducible
+function. It provides:
+
+- :class:`ProvenanceRecord` — bibliographic + categorization provenance for
+  one corpus entry (``citation_count`` is the count at the freeze date).
+- :class:`CorpusManifest` — the reproducible record of what was searched
+  (queries + frozen search date), round-trippable to/from a plain dict.
+- :func:`schema_graph_hash` / :func:`bibliographic_key` / :func:`deduplicate`
+  — deterministic dedup by schema-graph structure OR bibliographic key
+  (transitive), with a documented representative tie-break.
+- :func:`select_representatives` — reproducible per-cluster representative
+  choice with documented citation/quality fallbacks.
+- :class:`CorpusManager` — a thin facade tying the manifest and entries
+  together.
+
+Everything here is deterministic: identical inputs yield identical output.
+"""
+
+from __future__ import annotations
+
+from lp2graph.mining.corpusmgr.dedup import (
+    DedupResult,
+    bibliographic_key,
+    deduplicate,
+    schema_graph_hash,
+)
+from lp2graph.mining.corpusmgr.manager import CorpusManager
+from lp2graph.mining.corpusmgr.manifest import (
+    MANIFEST_SCHEMA_VERSION,
+    CorpusManifest,
+    manifest_from_dict,
+    manifest_to_dict,
+)
+from lp2graph.mining.corpusmgr.record import (
+    PRIORITY_CELLS,
+    QUALITY_TIERS,
+    PriorityCell,
+    ProvenanceRecord,
+    QualityTier,
+    quality_rank,
+)
+from lp2graph.mining.corpusmgr.select import (
+    RepresentativeChoice,
+    SelectionReason,
+    select_representatives,
+)
+
+__all__ = [
+    "MANIFEST_SCHEMA_VERSION",
+    "PRIORITY_CELLS",
+    "QUALITY_TIERS",
+    "CorpusManager",
+    "CorpusManifest",
+    "DedupResult",
+    "PriorityCell",
+    "ProvenanceRecord",
+    "QualityTier",
+    "RepresentativeChoice",
+    "SelectionReason",
+    "bibliographic_key",
+    "deduplicate",
+    "manifest_from_dict",
+    "manifest_to_dict",
+    "quality_rank",
+    "schema_graph_hash",
+    "select_representatives",
+]

lp2graph/mining/corpusmgr/dedup.py

@@ -0,0 +1,183 @@
+"""Deterministic deduplication of corpus formulations (M5).
+
+Two formulations are *duplicates* if they share either of two signals:
+
+- the **schema-graph hash** — a stable digest of the schema view's
+  *structure only* (node classes/subtypes/shapes + typed edges), ignoring
+  every cosmetic name, description, and id. Two structurally identical
+  formulations with different naming therefore collide.
+- the **bibliographic key** — a normalized ``venue + year + source_id`` key,
+  catching the same publication ingested twice.
+
+:func:`deduplicate` clusters items that share *either* signal, transitively
+(union-find), and picks a representative per group by citation count with
+documented, deterministic tie-breaks. Everything is sorted so repeated runs
+over the same input produce byte-identical output.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from lp2graph.core.graph import Graph
+from lp2graph.core.model import Formulation
+from lp2graph.mining.corpusmgr.record import ProvenanceRecord
+from lp2graph.views.schema import schema
+
+_PUNCT_RE = re.compile(r"[^\w]+")
+
+
+def _canonicalize_graph(g: Graph) -> str:
+    """Render ``g`` as a canonical, name-free, sorted structural string.
+
+    Node *ids* and *labels* (which carry user-chosen names) are dropped; we
+    map each node id to a structural signature ``(cls, subtype, shape)`` and
+    describe edges by the structural signatures of their endpoints plus the
+    edge ``type`` and ``role``. Sorting every component makes the result
+    invariant to insertion order and to cosmetic renaming.
+    """
+    sig: dict[str, str] = {}
+    for n in g.nodes:
+        sig[n.id] = f"{n.cls}|{n.subtype}|{','.join(n.shape)}"
+
+    node_lines = sorted(sig.values())
+    edge_lines = sorted(f"{sig[e.src]}->{sig[e.dst]}|{e.type}|{e.role}" for e in g.edges)
+
+    return "N\n" + "\n".join(node_lines) + "\nE\n" + "\n".join(edge_lines)
+
+
+def schema_graph_hash(f: Formulation) -> str:
+    """Return a stable hex digest of the schema-graph *structure* of ``f``.
+
+    The digest is derived from node classes/subtypes/shapes and typed edges
+    of the schema view only — never from names, descriptions, or ids — so
+    two structurally identical formulations hash equal regardless of
+    cosmetic naming. Uses SHA-256 and sorts all components for determinism.
+    """
+    canonical = _canonicalize_graph(schema(f))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _normalize(text: str) -> str:
+    """Casefold and collapse non-word runs to single spaces; strip ends."""
+    return _PUNCT_RE.sub(" ", text).casefold().strip()
+
+
+def bibliographic_key(record: ProvenanceRecord) -> str:
+    """Return a normalized bibliographic match key for ``record``.
+
+    Built from ``venue + year + source_id``, casefolded with punctuation and
+    whitespace normalized, so trivially different spellings of the same
+    citation collapse to one key.
+    """
+    year = "" if record.year is None else str(record.year)
+    parts = [_normalize(record.venue), year, _normalize(record.source_id)]
+    return "|".join(parts)
+
+
+@dataclass(frozen=True, slots=True)
+class DedupResult:
+    """The outcome of :func:`deduplicate`.
+
+    ``groups`` are the duplicate clusters as tuples of indices into the
+    input sequence; each group is sorted ascending, and the groups
+    themselves are sorted. ``representatives`` gives, positionally aligned
+    with ``groups``, the chosen representative index for each group.
+    """
+
+    groups: tuple[tuple[int, ...], ...]
+    representatives: tuple[int, ...]
+
+    def representative_index(self, group_position: int) -> int:
+        """Representative input-index of the group at ``group_position``."""
+        return self.representatives[group_position]
+
+
+class _UnionFind:
+    __slots__ = ("_parent",)
+
+    def __init__(self, n: int) -> None:
+        self._parent = list(range(n))
+
+    def find(self, x: int) -> int:
+        root = x
+        while self._parent[root] != root:
+            root = self._parent[root]
+        # path compression
+        while self._parent[x] != root:
+            self._parent[x], x = root, self._parent[x]
+        return root
+
+    def union(self, a: int, b: int) -> None:
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            # attach larger root index under smaller for stable representatives
+            lo, hi = (ra, rb) if ra < rb else (rb, ra)
+            self._parent[hi] = lo
+
+
+def _pick_representative(
+    members: Sequence[int],
+    records: Sequence[ProvenanceRecord],
+) -> int:
+    """Highest citation_count; tie -> best quality tier; tie -> lowest index."""
+    return min(
+        members,
+        key=lambda i: (
+            -records[i].citation_count,
+            records[i].quality_rank,
+            i,
+        ),
+    )
+
+
+def deduplicate(
+    items: Sequence[tuple[Formulation, ProvenanceRecord]],
+) -> DedupResult:
+    """Group ``items`` that share a schema-graph hash OR a bibliographic key.
+
+    Grouping is transitive (union-find): if A matches B structurally and B
+    matches C bibliographically, all three land in one group. Within each
+    group the representative is the item with the highest
+    ``citation_count``, ties broken by best quality tier then lowest input
+    index. Fully deterministic.
+    """
+    n = len(items)
+    uf = _UnionFind(n)
+
+    by_hash: dict[str, int] = {}
+    by_bib: dict[str, int] = {}
+
+    for i, (formulation, record) in enumerate(items):
+        h = schema_graph_hash(formulation)
+        if h in by_hash:
+            uf.union(i, by_hash[h])
+        else:
+            by_hash[h] = i
+
+        b = bibliographic_key(record)
+        if b in by_bib:
+            uf.union(i, by_bib[b])
+        else:
+            by_bib[b] = i
+
+    clusters: dict[int, list[int]] = {}
+    for i in range(n):
+        clusters.setdefault(uf.find(i), []).append(i)
+
+    records = [r for _, r in items]
+    groups = sorted(tuple(sorted(members)) for members in clusters.values())
+    representatives = tuple(_pick_representative(g, records) for g in groups)
+
+    return DedupResult(groups=tuple(groups), representatives=representatives)
+
+
+__all__ = [
+    "DedupResult",
+    "bibliographic_key",
+    "deduplicate",
+    "schema_graph_hash",
+]

lp2graph/mining/corpusmgr/manager.py

@@ -0,0 +1,79 @@
+"""Thin corpus & provenance manager facade (M5).
+
+:class:`CorpusManager` ties the pieces together: it holds the regeneration
+:class:`~lp2graph.mining.corpusmgr.manifest.CorpusManifest` plus the list of
+``(Formulation, ProvenanceRecord)`` entries, and exposes the deterministic
+operations (deduplicate, representative selection) and the manifest
+(de)serialization that make the corpus *"regenerable from queries + freeze
+date"*. It deliberately stays thin — all logic lives in the dedicated
+modules.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from lp2graph.core.model import Formulation
+from lp2graph.mining.corpusmgr.dedup import DedupResult, deduplicate
+from lp2graph.mining.corpusmgr.manifest import CorpusManifest
+from lp2graph.mining.corpusmgr.record import ProvenanceRecord
+from lp2graph.mining.corpusmgr.select import (
+    RepresentativeChoice,
+    select_representatives,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CorpusManager:
+    """A corpus = a regeneration manifest + provenance-tagged formulations."""
+
+    manifest: CorpusManifest
+    entries: tuple[tuple[Formulation, ProvenanceRecord], ...] = field(default_factory=tuple)
+
+    @classmethod
+    def build(
+        cls,
+        manifest: CorpusManifest,
+        entries: Iterable[tuple[Formulation, ProvenanceRecord]],
+    ) -> CorpusManager:
+        """Construct a manager from a manifest and an iterable of entries."""
+        return cls(manifest=manifest, entries=tuple(entries))
+
+    @property
+    def records(self) -> tuple[ProvenanceRecord, ...]:
+        """The provenance records, positionally aligned with :attr:`entries`."""
+        return tuple(r for _, r in self.entries)
+
+    def deduplicate(self) -> DedupResult:
+        """Deterministically deduplicate the corpus entries."""
+        return deduplicate(self.entries)
+
+    def representatives(
+        self,
+        clusters: Mapping[str, Sequence[int]],
+        *,
+        benchmark_fallback: Mapping[str, int] | None = None,
+    ) -> dict[str, RepresentativeChoice]:
+        """Pick a reproducible representative per named cluster."""
+        return select_representatives(clusters, self.records, benchmark_fallback=benchmark_fallback)
+
+    def to_manifest_dict(self) -> dict[str, Any]:
+        """Serialize the regeneration manifest to a plain dict."""
+        return self.manifest.to_dict()
+
+    @classmethod
+    def from_manifest_dict(
+        cls,
+        data: dict[str, Any],
+        entries: Iterable[tuple[Formulation, ProvenanceRecord]] = (),
+    ) -> CorpusManager:
+        """Rebuild a manager from a serialized manifest (+ optional entries)."""
+        return cls(
+            manifest=CorpusManifest.from_dict(data),
+            entries=tuple(entries),
+        )
+
+
+__all__ = ["CorpusManager"]

lp2graph/mining/corpusmgr/manifest.py

@@ -0,0 +1,82 @@
+"""The corpus regeneration manifest (M5).
+
+The acceptance criterion for the corpus manager is *"corpus regenerable from
+queries + freeze date"*. A :class:`CorpusManifest` is exactly that record:
+the literal query strings that were issued and the frozen search date they
+were issued against. Given the manifest, re-running the same queries at the
+same freeze date reproduces the same candidate set — so the manifest is the
+reproducible provenance of the whole corpus, not of any single entry.
+
+It is a dependency-free frozen dataclass with a plain-``dict`` (JSON
+round-trippable) serialization so it can be stored alongside the extracted
+JSON and diffed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+#: Bumped when the on-disk manifest dict layout changes.
+MANIFEST_SCHEMA_VERSION = "1"
+
+
+@dataclass(frozen=True, slots=True)
+class CorpusManifest:
+    """The reproducible record of *what was searched* to build the corpus.
+
+    ``frozen_search_date`` is the ISO-8601 date the searches were frozen at
+    (an input string, never ``today``). ``queries`` is the ordered, literal
+    tuple of query strings issued. Together they make the candidate set
+    regenerable.
+    """
+
+    frozen_search_date: str
+    queries: tuple[str, ...] = ()
+    notes: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.frozen_search_date:
+            raise ValueError("frozen_search_date must be a non-empty ISO date string")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain, JSON-round-trippable dict."""
+        return {
+            "manifest_schema_version": MANIFEST_SCHEMA_VERSION,
+            "frozen_search_date": self.frozen_search_date,
+            "queries": list(self.queries),
+            "notes": self.notes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CorpusManifest:
+        """Reconstruct a manifest from its :meth:`to_dict` form."""
+        version = data.get("manifest_schema_version", MANIFEST_SCHEMA_VERSION)
+        if version != MANIFEST_SCHEMA_VERSION:
+            raise ValueError(
+                f"unsupported manifest_schema_version {version!r} "
+                f"(expected {MANIFEST_SCHEMA_VERSION!r})"
+            )
+        return cls(
+            frozen_search_date=str(data["frozen_search_date"]),
+            queries=tuple(str(q) for q in data.get("queries", ())),
+            notes=str(data.get("notes", "")),
+        )
+
+
+def manifest_to_dict(manifest: CorpusManifest) -> dict[str, Any]:
+    """Free-function form of :meth:`CorpusManifest.to_dict`."""
+    return manifest.to_dict()
+
+
+def manifest_from_dict(data: dict[str, Any]) -> CorpusManifest:
+    """Free-function form of :meth:`CorpusManifest.from_dict`."""
+    return CorpusManifest.from_dict(data)
+
+
+__all__ = [
+    "MANIFEST_SCHEMA_VERSION",
+    "CorpusManifest",
+    "manifest_from_dict",
+    "manifest_to_dict",
+]