stemma-graph 0.3.0__py3-none-any.whl

stemma_graph/__init__.py

@@ -0,0 +1,6 @@
+"""Reusable genealogy core. This package alone is sufficient; Python standard library only."""
+
+from .contracts import GraphError, GraphView, Node, RevisionRef, Succession
+from .genealogy import Genealogy
+
+__all__ = ["GraphError", "RevisionRef", "Node", "Succession", "GraphView", "Genealogy"]

stemma_graph/contracts.py

@@ -0,0 +1,108 @@
+"""Shared value objects used by the portable graph package.
+
+Read this module first: RevisionRef identifies text, Node participates in questions,
+and Succession records the author-approved direction between documents.
+These objects carry no file locations, rendering instructions, or publication policy."""
+
+from dataclasses import dataclass
+
+
+class GraphError(ValueError):
+    """A caller-supplied graph violates a semantic invariant."""
+
+    pass
+
+
+def require(condition, message):
+    if not condition:
+        raise GraphError(message)
+
+
+def identifier(value):
+    require(isinstance(value, str) and bool(value.strip()), "Expected nonempty string identifier")
+
+
+@dataclass(frozen=True, order=True)
+class RevisionRef:
+    """Identify one immutable revision of a document.
+
+    Document identity survives editing; revision identity identifies the exact text.
+    Ordering is lexical and exists for deterministic output, not historical chronology."""
+
+    document: str
+    revision: str
+
+    def __post_init__(self):
+        identifier(self.document)
+        identifier(self.revision)
+
+
+@dataclass(frozen=True)
+class Node:
+    """Describe only the document information needed to validate a lineage.
+
+    A document may participate in several questions and retain several revisions.
+    A draft node can be stored, but does not enter a confirmed question view.
+    Archived ends future use globally; it does not remove any historical graph fact."""
+
+    id: str
+    revisions: tuple
+    questions: tuple = ()
+    confirmed: bool = True
+    archived: bool = False
+
+    def __post_init__(self):
+        """Copy sequence inputs and validate local fields before a graph checks references."""
+        identifier(self.id)
+        # frozen=True prevents later assignment; copying also isolates caller-owned lists.
+        object.__setattr__(self, "revisions", tuple(self.revisions))
+        object.__setattr__(self, "questions", tuple(self.questions))
+        require(bool(self.revisions), "Node requires at least one revision")
+        for value in self.revisions + self.questions:
+            identifier(value)
+        require(len(set(self.revisions)) == len(self.revisions), "Duplicate revision")
+        require(len(set(self.questions)) == len(self.questions), "Duplicate participation")
+        require(type(self.confirmed) is bool, "Expected boolean confirmed")
+        require(type(self.archived) is bool, "Expected boolean archived")
+        require(not self.archived or self.confirmed, "Only confirmed documents can end use")
+
+
+@dataclass(frozen=True)
+class Succession:
+    """Record parent -> child across one or more questions, with both text revisions pinned.
+
+    The note describes what changed. Succession does not imply agreement.
+    A proposed edge is valid data but does not retire its parent as a terminal."""
+
+    id: str
+    parent: RevisionRef
+    child: RevisionRef
+    questions: tuple
+    note: str
+    confirmed: bool = True
+
+    def __post_init__(self):
+        require(not isinstance(self.questions, str), "Questions must be a sequence, not a string")
+        object.__setattr__(self, "questions", tuple(self.questions))
+        require(bool(self.questions), "Succession requires a question scope")
+        require(len(set(self.questions)) == len(self.questions), "Duplicate question scope")
+        for value in (self.id, self.note) + self.questions:
+            identifier(value)
+        require(
+            isinstance(self.parent, RevisionRef) and isinstance(self.child, RevisionRef), "Expected revision references"
+        )
+        require(type(self.confirmed) is bool, "Expected boolean confirmed")
+
+
+@dataclass(frozen=True)
+class GraphView:
+    """Return the confirmed graph for one question, including its global boundaries.
+
+    Nodes, roots, and terminals contain document IDs; edges contain Succession values.
+    A terminal is structural, not an automatic declaration of a representative position."""
+
+    question: str
+    nodes: tuple
+    edges: tuple
+    roots: tuple
+    terminals: tuple

stemma_graph/genealogy.py

@@ -0,0 +1,242 @@
+"""Validate and query immutable, question-scoped document lineage.
+
+Construction enforces invariants once for each new value. Read queries filter to
+confirmed relationships; add/confirm operations build a new validated value.
+There is no database, file access, publication policy, or UI dependency here."""
+
+from dataclasses import asdict, dataclass, replace
+
+from .contracts import GraphView, Node, RevisionRef, Succession, identifier, require
+
+
+@dataclass(frozen=True)
+class Genealogy:
+    """Hold all document nodes and question-labeled succession edges.
+
+    Each document pair has at most one edge, carrying a set of question scopes.
+    The union of all scopes must be acyclic, including proposed edges."""
+
+    nodes: tuple
+    questions: tuple
+    edges: tuple = ()
+
+    def __post_init__(self):
+        """Validate local membership, edge references, uniqueness, and the global DAG."""
+        for field in ("nodes", "questions", "edges"):
+            object.__setattr__(self, field, tuple(getattr(self, field)))
+        for q in self.questions:
+            identifier(q)
+        require(len(set(self.questions)) == len(self.questions), "Duplicate question")
+        require(all(isinstance(n, Node) for n in self.nodes), "Expected nodes")
+        nodes = {n.id: n for n in self.nodes}
+        require(len(nodes) == len(self.nodes), "Duplicate node")
+        for n in self.nodes:
+            require(set(n.questions) <= set(self.questions), "Unknown question")
+        # A relationship is unique by document pair, regardless of its question scopes.
+        ids, pairs = set(), set()
+        adjacency = {n: set() for n in nodes}
+        for e in self.edges:
+            require(isinstance(e, Succession), "Expected succession")
+            require(e.id not in ids, "Duplicate edge ID")
+            ids.add(e.id)
+            require(e.parent.document != e.child.document, "Self succession is not allowed")
+            require(set(e.questions) <= set(self.questions), "Unknown question")
+            for ref in (e.parent, e.child):
+                require(ref.document in nodes, "Unknown edge endpoint")
+                n = nodes[ref.document]
+                require(ref.revision in n.revisions, "Unknown edge revision")
+                require(set(e.questions) <= set(n.questions), "Endpoint must participate in every scope")
+                require(not e.confirmed or n.confirmed, "Confirmed edge needs confirmed endpoints")
+            pair = (e.parent.document, e.child.document)
+            require(pair not in pairs, "Only one succession per document pair is allowed")
+            pairs.add(pair)
+            # Question overlap never creates another edge between this document pair.
+            adjacency[e.parent.document].add(e.child.document)
+        # Kahn traversal avoids recursion limits on long corpora. Proposals also must be acyclic.
+        degree = {n: 0 for n in nodes}
+        for children in adjacency.values():
+            for child in children:
+                degree[child] += 1
+        # Repeatedly remove nodes with no remaining predecessors. A cycle leaves
+        # nodes that can never become ready, so the visited count will be too small.
+        ready = [n for n, d in degree.items() if d == 0]
+        count = 0
+        while ready:
+            n = ready.pop()
+            count += 1
+            for child in adjacency[n]:
+                degree[child] -= 1
+                if degree[child] == 0:
+                    ready.append(child)
+        require(count == len(nodes), "Genealogy must be acyclic")
+
+    def view(self, question):
+        """Derive roots and terminals from confirmed edges for exactly one question.
+
+        Sorting makes output deterministic; it does not rank importance or recency."""
+        require(question in self.questions, "Unknown question")
+        nodes = tuple(sorted(n.id for n in self.nodes if n.confirmed and question in n.questions))
+        edges = tuple(sorted((e for e in self.edges if e.confirmed and question in e.questions), key=lambda e: e.id))
+        # Compute boundaries after filtering by question and confirmation state.
+        # The same document can therefore be historical in one question and current in another.
+        incoming = {e.child.document for e in edges}
+        outgoing = {e.parent.document for e in edges}
+        return GraphView(
+            question,
+            nodes,
+            edges,
+            tuple(n for n in nodes if n not in incoming),
+            tuple(n for n in nodes if n not in outgoing),
+        )
+
+    def _walk(self, document, question, direction, depth=None):
+        """Traverse the confirmed question graph breadth-first.
+
+        The starting document is excluded from the result. A finite depth counts hops;
+        None means all reachable nodes. The visited set prevents duplicate work at merges."""
+        view = self.view(question)
+        require(document in view.nodes, "Document not in confirmed question graph")
+        require(depth is None or (type(depth) is int and depth >= 0), "Invalid depth")
+        adjacency = {n: set() for n in view.nodes}
+        for e in view.edges:
+            p, c = e.parent.document, e.child.document
+            if direction in ("forward", "both"):
+                adjacency[p].add(c)
+            if direction in ("backward", "both"):
+                adjacency[c].add(p)
+        # frontier is one hop layer; subtracting seen handles converging branches.
+        seen, frontier, level = {document}, {document}, 0
+        while frontier and (depth is None or level < depth):
+            frontier = set().union(*(adjacency[n] for n in frontier)) - seen
+            seen.update(frontier)
+            level += 1
+        return tuple(sorted(seen - {document}))
+
+    def ancestors(self, document, question):
+        """Return every confirmed predecessor reachable within the question."""
+        return self._walk(document, question, "backward")
+
+    def descendants(self, document, question):
+        """Return every confirmed successor reachable within the question."""
+        return self._walk(document, question, "forward")
+
+    def neighborhood(self, document, question, radius=1):
+        """Return nearby nodes and the edges between them, walking in both directions.
+
+        This is an induced local slice. Its boundary nodes are not necessarily the roots
+        or terminals of the full question graph."""
+        nodes = tuple(sorted((document,) + self._walk(document, question, "both", radius)))
+        edges = tuple(e for e in self.view(question).edges if e.parent.document in nodes and e.child.document in nodes)
+        # This is a local slice, not a claim that its boundary nodes are global roots/terminals.
+        return {"question": question, "nodes": nodes, "edges": edges}
+
+    def connected_components(self, documents, include_proposed=False):
+        """Return complete weak components touched by the selected document IDs.
+
+        Direction is ignored for reachability only; original edges retain direction.
+        All questions participate. Archived nodes remain; unconfirmed edges are
+        excluded by default, so a selected draft may be an isolated component.
+        """
+        require(not isinstance(documents, str), "Document IDs must be a sequence")
+        selected = set(documents)
+        adjacency = {node.id: set() for node in self.nodes}
+        require(selected <= set(adjacency), "Unknown document")
+        edges = tuple(e for e in self.edges if include_proposed or e.confirmed)
+        for edge in edges:
+            parent, child = edge.parent.document, edge.child.document
+            adjacency[parent].add(child)
+            adjacency[child].add(parent)
+        visited, result = set(), []
+        for start in sorted(selected):
+            if start in visited:
+                continue
+            component, frontier = {start}, [start]
+            while frontier:
+                current = frontier.pop()
+                for neighbor in adjacency[current] - component:
+                    component.add(neighbor)
+                    frontier.append(neighbor)
+            visited.update(component)
+            result.append(
+                {"nodes": tuple(sorted(component)), "edges": tuple(e for e in edges if e.parent.document in component)}
+            )
+        return tuple(result)
+
+    def add_node(self, node):
+        """Return a new graph with this node; validation runs again during replacement."""
+        return replace(self, nodes=self.nodes + (node,))
+
+    def add_edge(self, edge):
+        """Return a new graph with this relationship, rejecting invalid references or cycles."""
+        parent = next((n for n in self.nodes if n.id == edge.parent.document), None)
+        require(parent is not None and not parent.archived, "Archived document cannot be a new parent")
+        return replace(self, edges=self.edges + (edge,))
+
+    def set_archived(self, document, archived=True):
+        """Explicitly end or restore future use without changing historical lineage."""
+        require(any(n.id == document for n in self.nodes), "Unknown document")
+        require(type(archived) is bool, "Expected boolean archived")
+        return replace(self, nodes=tuple(replace(n, archived=archived) if n.id == document else n for n in self.nodes))
+
+    def available_documents(self):
+        """Return document IDs eligible for new use, independently of question terminals."""
+        return tuple(sorted(n.id for n in self.nodes if not n.archived))
+
+    def confirm_document(self, document, revision, archive_parents=()):
+        """Confirm a document and its incoming proposals at the selected revision.
+
+        Newly confirmed edges pin the chosen child revision. Already confirmed edges keep
+        the historical revision they originally referenced. The input graph is unchanged."""
+        node = next((n for n in self.nodes if n.id == document), None)
+        require(node is not None and revision in node.revisions, "Unknown document/revision")
+        require(not node.archived, "Restore an archived document before confirming new use")
+        require(not isinstance(archive_parents, str), "Parent IDs must be a sequence")
+        archive_parents = tuple(archive_parents)
+        require(len(set(archive_parents)) == len(archive_parents), "Duplicate archive parent")
+        incoming = tuple(e for e in self.edges if e.child.document == document)
+        require(
+            set(archive_parents) <= {e.parent.document for e in incoming}, "Can only archive direct succession parents"
+        )
+        archived = {n.id for n in self.nodes if n.archived}
+        require(
+            not any(not e.confirmed and e.parent.document in archived for e in incoming),
+            "Archived document cannot be used by a pending succession; restore it first",
+        )
+        # dataclasses.replace constructs a new instance and re-runs __post_init__,
+        # so confirmation cannot bypass reference or cycle validation.
+        return replace(
+            self,
+            nodes=tuple(
+                replace(n, confirmed=True)
+                if n.id == document
+                else replace(n, archived=True)
+                if n.id in archive_parents
+                else n
+                for n in self.nodes
+            ),
+            edges=tuple(
+                replace(e, confirmed=True, child=RevisionRef(document, revision) if not e.confirmed else e.child)
+                if e.child.document == document
+                else e
+                for e in self.edges
+            ),
+        )
+
+    def to_dict(self):
+        """Produce detached, JSON-serializable values with an explicit schema version."""
+        return {"schema_version": 3, **asdict(self)}
+
+    @classmethod
+    def from_dict(cls, data):
+        """Rebuild value objects from decoded JSON and run constructor validation."""
+        require(data.get("schema_version") in (2, 3), "Unsupported genealogy schema")
+        if data["schema_version"] == 3:
+            require(all("archived" in n for n in data["nodes"]), "Missing document use state")
+        return cls(
+            tuple(Node(**n) for n in data["nodes"]),
+            tuple(data["questions"]),
+            tuple(
+                Succession(**{**e, "parent": RevisionRef(**e["parent"]), "child": RevisionRef(**e["child"])})
+                for e in data["edges"]
+            ),
+        )

stemma_graph-0.3.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: stemma-graph
+Version: 0.3.0
+Summary: Portable question-scoped genealogy graphs: a stemma for your own writing
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# stemma-graph
+
+A standalone Python package for question-scoped genealogy graphs. The import
+name is `stemma_graph`.
+
+It has no runtime dependencies and needs no Stemma, Git, files, data or
+interface — if all you want is the graph, this is the only piece you need.
+
+```sh
+python3.12 -m venv .venv
+.venv/bin/pip install ./packages/stemma_graph
+```
+
+Install into a virtual environment rather than a global interpreter. Once the
+package is published this becomes `pip install stemma-graph`; until then,
+install the directory as above. It is self-contained, so it can also be copied
+into another project and installed from there.
+
+To try it without installing anything, from the repository root:
+
+```sh
+python3.12 -B scripts/dev.py example
+```
+
+## The model
+
+A `Genealogy` is a directed acyclic graph with **one edge per parent/child
+pair**; the questions that succession covers live in that edge's `questions`
+list, so adding finer questions never multiplies edges. Self-edges and cycles
+are refused.
+
+`Node.archived` marks a document retired from future use as material.
+`Genealogy.set_archived` returns a new graph, and `confirm_document` takes
+`archive_parents` so a parent can be retired as a succession is confirmed.
+Retired documents remain in past lineage and in terminal calculations;
+`available_documents` lists the ones still usable.
+
+Every change returns a new immutable graph. Nothing is modified in place.
+
+## Versions
+
+The package version is 0.3.0 and the genealogy JSON schema is v3; they version
+different things. Similarity graphs and exploration were removed in 0.3.0.
+
+See the repository [README](https://github.com/byeongsuyu/stemma/blob/main/README.md) and
+[design notes](https://github.com/byeongsuyu/stemma/blob/main/docs/design.md).

stemma_graph-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+stemma_graph/__init__.py,sha256=ue_xBkD0g7ZJ42RzTRptLZzg2YaCUDgwg4wnFnn1KCc,294
+stemma_graph/contracts.py,sha256=Njea6FDF69T_t3QELC8GHWtk18ckZXO5sZVcLe3Q-8k,4028
+stemma_graph/genealogy.py,sha256=H8ZwwLU-dRWeLTVNf_FBsKDKYwPCCzesz1EVRyHlXy0,12357
+stemma_graph-0.3.0.dist-info/licenses/LICENSE,sha256=ApJA0qNZXt4SRjI02D7p_ZJkumbsv1ZVKf_31vVgqdc,1068
+stemma_graph-0.3.0.dist-info/METADATA,sha256=G_kcI4vqnPIkYcpf7uiBS0Km339AoWHT-RHgvPc7uIw,2027
+stemma_graph-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+stemma_graph-0.3.0.dist-info/top_level.txt,sha256=pwWqC_XPy79PUD1i8duxBqv6zNfrnImKIrf0EMUW0Nc,13
+stemma_graph-0.3.0.dist-info/RECORD,,

stemma_graph-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stemma_graph-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Byeongsu Yu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stemma_graph-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stemma_graph