aatgraph 0.3.0__py3-none-any.whl

aat/__init__.py

@@ -0,0 +1,74 @@
+"""
+aat: a reductive Agent-Action-Target (AAT) model of natural-language
+syntax (see aat-model.md), plus a DSPy-based pipeline applying it to
+English (aat.english).
+
+This top-level module re-exports only aat.core -- the language-agnostic
+model itself -- so `import aat` never requires dspy to be installed.
+English-specific application code lives in aat.english and is imported
+separately:
+
+    from aat import CitableToken, AATNode, AATGraph, graph_to_mermaid   # always available
+    from aat.english import analyze_passage                              # needs the 'english' extra
+
+See README.md for the reasoning behind this split, and USAGE.md for
+worked examples of both.
+"""
+
+from .core import (
+    CitableToken,
+    CitedPassage,
+    AATGraph,
+    AATNode,
+    Role,
+    ROLES,
+    validate,
+    tokens_to_html,
+    serialize_nodes,
+    write_nodes,
+    read_nodes,
+    read_graph,
+    serialize_tokens,
+    write_tokens,
+    read_tokens,
+    serialize_analysis,
+    write_analysis,
+    read_analysis,
+    graph_to_mermaid,
+    save_mermaid,
+    graph_to_dot,
+    save_dot,
+    assign_action_colors,
+    parse_cex_ctsdata,
+    read_cex_passages,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CitableToken",
+    "CitedPassage",
+    "AATGraph",
+    "AATNode",
+    "Role",
+    "ROLES",
+    "validate",
+    "tokens_to_html",
+    "serialize_nodes",
+    "write_nodes",
+    "read_nodes",
+    "read_graph",
+    "serialize_tokens",
+    "write_tokens",
+    "read_tokens",
+    "serialize_analysis",
+    "write_analysis",
+    "read_analysis",
+    "graph_to_mermaid",
+    "save_mermaid",
+    "graph_to_dot",
+    "save_dot",
+    "assign_action_colors",
+    "parse_cex_ctsdata",
+    "read_cex_passages",
+]

aat/core/__init__.py

@@ -0,0 +1,61 @@
+"""
+aat.core: the Agent-Action-Target model itself (aat-model.md), with no
+dependency on any particular language or on dspy.
+
+Everything in this subpackage represents, validates, serializes, or
+renders an AAT graph; nothing here knows how to *produce* one from real
+text -- that's aat.english's job (or, eventually, another language-
+specific sibling subpackage). Keeping this boundary means aat.core can be
+imported and reused on its own by any downstream project that just wants
+the data model, the file format, and the Mermaid/Graphviz renderers,
+without pulling in dspy at all.
+"""
+
+from .tokens import CitableToken, CitedPassage
+from .graph import AATGraph, AATNode, Role, ROLES
+from .validate import validate
+from .serialization import (
+    serialize_nodes,
+    write_nodes,
+    read_nodes,
+    read_graph,
+    serialize_tokens,
+    write_tokens,
+    read_tokens,
+    serialize_analysis,
+    write_analysis,
+    read_analysis,
+)
+from .html import tokens_to_html
+from .mermaid import graph_to_mermaid, save_mermaid
+from .graphviz import graph_to_dot, save_dot
+from .coloring import assign_action_colors
+from .cex import parse_cex_ctsdata, read_cex_passages
+
+__all__ = [
+    "CitableToken",
+    "CitedPassage",
+    "AATGraph",
+    "AATNode",
+    "Role",
+    "ROLES",
+    "validate",
+    "serialize_nodes",
+    "write_nodes",
+    "read_nodes",
+    "read_graph",
+    "serialize_tokens",
+    "write_tokens",
+    "read_tokens",
+    "serialize_analysis",
+    "write_analysis",
+    "read_analysis",
+    "tokens_to_html",
+    "graph_to_mermaid",
+    "save_mermaid",
+    "graph_to_dot",
+    "save_dot",
+    "assign_action_colors",
+    "parse_cex_ctsdata",
+    "read_cex_passages",
+]

aat/core/cex.py

@@ -0,0 +1,93 @@
+"""
+Read a corpus of citable text passages from a CEX (CITE Exchange) file --
+an external plain-text interchange format from the CITE architecture
+(https://cite-architecture.github.io/citedx/CEX-spec-3.0.1/), not this
+project's own aat.core.serialization format (a different, purpose-built
+convention -- see that module's own docstring). A CEX file can carry many
+kinds of data in labelled '#!'-blocks ('#!citelibrary', '#!ctscatalog',
+'#!imagedata', ...); this module reads only the one block aat cares
+about -- '#!ctsdata' -- and ignores every other block type entirely, the
+same way aat.core.serialization's own readers ignore block types other
+than their own.
+
+A '#!ctsdata' block is two columns per line -- a CTS URN, then that
+node's own text -- separated by a delimiter the file's own author chose:
+per the CEX spec, the delimiter is never declared inside the file itself,
+just used consistently once picked. '#' is the most common convention in
+practice (and this module's own default) -- pass `delimiter` for a file
+that uses something else. Blank lines are ignored, and a line starting
+with '//' is a CEX comment and is also ignored -- both per the CEX spec.
+
+Splitting is done on the delimiter's *first* occurrence per line, not a
+strict two-column check (contrast aat.core.serialization's own readers,
+which require an exact column count) -- a CTS URN never contains '#'
+(or any other reasonable delimiter choice), but the citable text half of
+the line is real prose this module doesn't control, and (especially with
+the default '#' delimiter) can plausibly contain the delimiter character
+again somewhere in the text itself. Splitting on the first occurrence
+only keeps that text intact rather than raising over it.
+"""
+
+from typing import List
+
+from .tokens import CitedPassage
+
+CTSDATA_LABEL = "#!ctsdata"
+
+
+def parse_cex_ctsdata(text: str, delimiter: str = "#") -> List[CitedPassage]:
+    """Parse every '#!ctsdata' block in `text` (a CEX file's own full
+    contents, already read into a string) and return its rows,
+    concatenated in file order, as a list of CitedPassage -- `context` is
+    each row's own CTS URN, `text` is its citable text. Every other CEX
+    block type is ignored entirely, whether it appears before, between,
+    or after the '#!ctsdata' block(s); multiple '#!ctsdata' blocks in one
+    file are concatenated, in file order, same as
+    aat.core.serialization's own multi-block handling.
+
+    Raises ValueError, naming the offending line, for a '#!ctsdata' row
+    that has no `delimiter` in it at all -- most often a sign `delimiter`
+    is wrong for this particular file. Raises ValueError (not returning
+    an empty list) if the file has no '#!ctsdata' block at all, so a
+    caller can't mistake "wrong file" for "file with zero passages" --
+    same reasoning as aat.core.serialization.read_nodes()/read_tokens().
+    """
+    passages: List[CitedPassage] = []
+    in_ctsdata = False
+    seen = False
+
+    for line_no, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.strip("\r\n")
+        if line == "" or line.startswith("//"):
+            continue
+
+        if line.startswith("#!"):
+            in_ctsdata = line == CTSDATA_LABEL
+            if in_ctsdata:
+                seen = True
+            continue
+
+        if not in_ctsdata:
+            continue
+
+        urn, sep, passage_text = line.partition(delimiter)
+        if not sep:
+            raise ValueError(
+                f"line {line_no}: no {delimiter!r} delimiter found in a "
+                f"{CTSDATA_LABEL!r} row -- wrong --delimiter for this file? {line!r}"
+            )
+        passages.append(CitedPassage(context=urn, text=passage_text))
+
+    if not seen:
+        raise ValueError(f"file has no {CTSDATA_LABEL!r} block")
+
+    return passages
+
+
+def read_cex_passages(path: str, delimiter: str = "#") -> List[CitedPassage]:
+    """Read `path` as a CEX file and return parse_cex_ctsdata() of its
+    contents -- see that function's own docstring for the exact format
+    and error cases."""
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+    return parse_cex_ctsdata(text, delimiter=delimiter)

aat/core/coloring.py

@@ -0,0 +1,96 @@
+"""
+Shared color-by-action-cluster assignment.
+
+Every action node, plus every agent or target node whose `related_node`
+points at it, shares one color -- assigned from a small palette in the
+order each action first appears in a graph's own node list. This lives in
+its own module, separate from mermaid.py, so it can be reused wherever a
+token or node needs to be colored the same way it is in a Mermaid diagram
+without depending on Mermaid-specific rendering code -- e.g.
+aat.core.html's tokens_to_html(), which highlights passage text with
+these same colors. This mirrors why arsgrammatica's verbal_units.py is
+shared between its own mermaid.py and rendering.py.
+
+A dependent action gets its OWN color, not its governor's -- it's still
+its own cluster's anchor, even though something else (a Mermaid edge, an
+HTML border) may also point at or otherwise reference another cluster's
+anchor.
+"""
+
+from typing import Dict, List, Tuple
+
+from .graph import AATGraph, AATNode
+
+NodeKey = Tuple[str, str]
+ColorTriple = Tuple[str, str, str]
+
+# (fill, stroke, text) hex triples, chosen for readable contrast between
+# fill and text in both light- and dark-themed renderers. Cycles (with a
+# warning -- see assign_action_colors()'s own docstring) if a graph has
+# more distinct actions than this palette has slots.
+_ACTION_COLOR_PALETTE: List[ColorTriple] = [
+    ("#E3F2FD", "#1565C0", "#0D47A1"),  # blue
+    ("#FFF3E0", "#EF6C00", "#E65100"),  # orange
+    ("#E8F5E9", "#2E7D32", "#1B5E20"),  # green
+    ("#FCE4EC", "#AD1457", "#880E4F"),  # pink
+    ("#EDE7F6", "#5E35B1", "#4527A0"),  # purple
+    ("#FFFDE7", "#F9A825", "#F57F17"),  # yellow
+    ("#E0F7FA", "#00838F", "#006064"),  # cyan
+    ("#FBE9E7", "#D84315", "#BF360C"),  # deep orange
+]
+
+
+def _node_key(node: AATNode) -> NodeKey:
+    return (node.context, node.id)
+
+
+def assign_action_colors(graph: AATGraph) -> Tuple[Dict[NodeKey, ColorTriple], List[str]]:
+    """Return (color_of_node, warnings).
+
+    `color_of_node` maps every node's (context, id) to a (fill, stroke,
+    text) hex triple, for every node that clusters with some action: an
+    action node itself (dependent or not -- see this module's own
+    docstring), or an agent/target node whose `related_node` resolves to
+    an action node in the same context. A node with no resolvable cluster
+    (e.g. an agent/target with a broken related_node -- shouldn't happen
+    in a graph that's passed aat.core.validate.validate()) is simply
+    absent from the mapping.
+
+    Colors are assigned to actions in the order they first appear in
+    `graph.nodes`, cycling through the palette (currently 8 colors) if
+    there are more distinct actions than that -- in which case two
+    distinct actions (and their own agent/target nodes) end up sharing the
+    identical color. `warnings` has one entry naming this when it happens;
+    otherwise it's empty.
+    """
+    actions = [n for n in graph.nodes if n.role == "action"]
+
+    warnings: List[str] = []
+    if len(actions) > len(_ACTION_COLOR_PALETTE):
+        warnings.append(
+            f"{len(actions)} actions but only {len(_ACTION_COLOR_PALETTE)} palette "
+            "colors -- colors repeat and some distinct actions will share a color"
+        )
+
+    action_index: Dict[NodeKey, int] = {_node_key(a): i for i, a in enumerate(actions)}
+
+    by_key: Dict[NodeKey, AATNode] = {_node_key(n): n for n in graph.nodes}
+    cluster_of_node: Dict[NodeKey, NodeKey] = {}
+    for node in graph.nodes:
+        key = _node_key(node)
+        if node.role == "action":
+            cluster_of_node[key] = key
+        elif node.related_node is not None:
+            related_key = (node.context, node.related_node)
+            if related_key in by_key:
+                cluster_of_node[key] = related_key
+
+    color_of_node: Dict[NodeKey, ColorTriple] = {}
+    for node in graph.nodes:
+        key = _node_key(node)
+        cluster_key = cluster_of_node.get(key)
+        if cluster_key is None or cluster_key not in action_index:
+            continue
+        color_of_node[key] = _ACTION_COLOR_PALETTE[action_index[cluster_key] % len(_ACTION_COLOR_PALETTE)]
+
+    return color_of_node, warnings

aat/core/graph.py

@@ -0,0 +1,125 @@
+"""
+The AAT graph itself: the output side of the AAT model (aat-model.md, "The
+AAT graph for English" -- despite that section header, the graph *shape*
+it defines is not English-specific; only the rules for how to populate it
+from English text are English-specific. See aat.english for those rules.)
+
+An AATGraph is a selection of nodes drawn from a passage's citable tokens.
+Every node keeps the context/id/value of the token(s) it derives from (for
+a compound action, see AATNode's own docstring on id/value), and adds two
+fields the raw tokens don't have: `role` (agent/action/target) and
+`related_node`.
+"""
+
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+Role = Literal["agent", "action", "target"]
+
+ROLES: tuple = ("agent", "action", "target")
+
+
+class AATNode(BaseModel):
+    """One node in an AAT graph.
+
+    `context` and `id` identify the token this node is built from -- for a
+    single-token action, an agent, or a target, `id` is just that token's
+    own id. For a *compound* action (aat-model.md's "Actions" section --
+    e.g. "was eating"), `id` is instead the id of the *principal verb*
+    token within the compound (e.g. the token for "eating"), and `value`
+    is the space-joined text of every component token in surface order
+    (e.g. "was eating"), not just the principal verb's own text.
+
+    `related_node` is:
+      - `None`, for an *independent* action node (aat-model.md's
+        "Actions" section);
+      - another action node's `id`, for a *dependent* action node (the id
+        of the governing action it depends on);
+      - another action node's `id`, for an agent or target node (the id
+        of the action it's the agent/target of) -- agent and target nodes
+        always have a related_node; only an action node's related_node
+        can be `None`.
+    """
+
+    context: str = Field(description="Context reference this node belongs to.")
+    id: str = Field(
+        description=(
+            "Token id this node is built from -- the principal verb's id "
+            "for a compound action, otherwise the single underlying "
+            "token's id."
+        )
+    )
+    value: str = Field(
+        description=(
+            "This node's string value -- a single token's own text, or, "
+            "for a compound action, every component token's text joined "
+            "by spaces in surface order."
+        )
+    )
+    role: Role = Field(description="'agent', 'action', or 'target'.")
+    related_node: Optional[str] = Field(
+        default=None,
+        description=(
+            "For an action node: the id of the governing action node, if "
+            "this action is dependent/subordinate; None if independent. "
+            "For an agent or target node: the id of the action node it "
+            "relates to (always set)."
+        ),
+    )
+
+
+class AATGraph(BaseModel):
+    """A full AAT graph for one or more citable passages: an ordered list
+    of AATNode. Node order is not semantically significant -- the
+    convenience accessors below don't depend on it -- but callers that
+    built the graph from a specific passage will typically find document
+    order convenient for display."""
+
+    nodes: List[AATNode] = Field(default_factory=list)
+
+    def by_id(self, context: str, id: str) -> Optional[AATNode]:
+        """The node with this (context, id), or None. `id` alone isn't a
+        reliable key across contexts (CitableToken/AATNode ids are only
+        unique *within* one context -- see CitableToken's docstring), so
+        both are required here."""
+        for node in self.nodes:
+            if node.context == context and node.id == id:
+                return node
+        return None
+
+    def actions(self) -> List[AATNode]:
+        """Every action node, in list order."""
+        return [n for n in self.nodes if n.role == "action"]
+
+    def agents(self) -> List[AATNode]:
+        """Every agent node, in list order."""
+        return [n for n in self.nodes if n.role == "agent"]
+
+    def targets(self) -> List[AATNode]:
+        """Every target node, in list order."""
+        return [n for n in self.nodes if n.role == "target"]
+
+    def agents_for(self, action: AATNode) -> List[AATNode]:
+        """Every agent node whose related_node points at `action`'s id,
+        within the same context."""
+        return [
+            n for n in self.nodes
+            if n.role == "agent" and n.context == action.context and n.related_node == action.id
+        ]
+
+    def targets_for(self, action: AATNode) -> List[AATNode]:
+        """Every target node whose related_node points at `action`'s id,
+        within the same context."""
+        return [
+            n for n in self.nodes
+            if n.role == "target" and n.context == action.context and n.related_node == action.id
+        ]
+
+    def governing_action(self, action: AATNode) -> Optional[AATNode]:
+        """For a dependent action node, the action node it's subordinate
+        to; None if `action` is independent (related_node is None) or if
+        related_node doesn't resolve to any node in this graph."""
+        if action.related_node is None:
+            return None
+        return self.by_id(action.context, action.related_node)

aat/core/graphviz.py

@@ -0,0 +1,171 @@
+"""
+Render an AATGraph as a Graphviz DOT digraph -- the same graph
+aat.core.mermaid.graph_to_mermaid() renders as a Mermaid flowchart,
+translated into Graphviz's own syntax instead. The underlying node/edge/
+coloring model is identical (see that module's own docstring); only the
+target syntax differs:
+
+- Every node becomes a DOT node, labelled with its own `value` and
+  shaped by its `role`. Graphviz has no shape literally called
+  "stadium", so target's shape is chosen as the closest visual analogue
+  to Mermaid's `([...])` (fully rounded, no square corners at all):
+    - action: `shape=box` (plain rectangle, matches Mermaid's `[...]`)
+    - agent: `shape=box, style=rounded` (rounded-corner rectangle,
+      matches Mermaid's `(...)`)
+    - target: `shape=ellipse` (fully rounded oval, matches Mermaid's
+      `([...])`)
+- Every node with a `related_node` becomes a labelled edge FROM that node
+  TO the node it relates to, exactly as graph_to_mermaid() describes.
+- By default (`color_by_action=True`), every node is colored by the same
+  action-cluster assignment graph_to_mermaid() uses
+  (aat.core.coloring.assign_action_colors()) -- but applied as inline
+  `style=filled, fillcolor=..., color=..., fontcolor=...` attributes
+  directly on each node's own line. DOT has no equivalent to Mermaid's
+  separate classDef/class mechanism, so there's no separate "class"
+  grouping step here; each node just carries its own color attributes.
+
+Multiple contexts in one `graph` are all drawn into a single digraph,
+with no special separation between them -- same caveat as
+graph_to_mermaid(); filter `graph.nodes` first for one digraph per
+context.
+
+`orientation` (default "BT", bottom-to-top) is validated the same way
+graph_to_mermaid() validates it (aat.core.orientation, shared between
+both renderers) -- but Graphviz's `rankdir` graph attribute has no "TD"
+synonym of its own, so an orientation of "TD" (top-down) is mapped to
+Graphviz's "TB" (top-to-bottom -- the same direction, just Graphviz's own
+spelling of it) when it's written out; see graph_to_dot()'s own
+docstring.
+"""
+
+from typing import Dict, List, Tuple
+
+from .coloring import ColorTriple, assign_action_colors
+from .graph import AATGraph, AATNode
+from .orientation import normalize_orientation
+
+# Graphviz node shape/style, keyed by AATNode.role -- see this module's
+# own docstring for why target maps to shape=ellipse rather than a
+# "stadium" Graphviz has no name for. A role this module doesn't
+# recognize (shouldn't happen -- Role is a Literal of exactly these
+# three -- but AATNode itself doesn't enforce that at the type level for
+# a hand-built or deserialized node) falls back to a plain box, same
+# fallback graph_to_mermaid() uses for an unrecognized role.
+_ROLE_SHAPE = {
+    "action": "box",
+    "agent": "box",
+    "target": "ellipse",
+}
+
+# Extra `style=` keywords layered on top of a node's own shape, keyed the
+# same way -- only agent needs one of its own (rounded corners); a
+# color_by_action fill (see graph_to_dot()) adds "filled" to whatever's
+# here rather than overwriting it, so a colored agent node still ends up
+# rounded (style="rounded,filled"), not a plain filled rectangle.
+_ROLE_EXTRA_STYLES: Dict[str, List[str]] = {
+    "agent": ["rounded"],
+}
+
+
+def _node_key(node: AATNode) -> Tuple[str, str]:
+    return (node.context, node.id)
+
+
+def _escape_label(text: str) -> str:
+    """Escape `text` for use inside a DOT double-quoted string literal --
+    backslash first (so escaping the quote below doesn't get re-escaped
+    itself), then the quote character."""
+    return text.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def graph_to_dot(
+    graph: AATGraph,
+    orientation: str = "BT",
+    color_by_action: bool = True,
+) -> Tuple[str, List[str]]:
+    """Build a Graphviz DOT digraph from an AATGraph -- see this module's
+    own docstring for the node-shape/edge/coloring mapping, which mirrors
+    aat.core.mermaid.graph_to_mermaid() exactly except for the target
+    syntax.
+
+    `orientation` is validated exactly like graph_to_mermaid()'s (see
+    aat.core.orientation) -- `BT` (bottom-to-top, the default here),
+    `TB`/`TD` (top-down -- synonyms), `LR`, or `RL`. Written out as
+    Graphviz's own `rankdir` graph attribute; since `rankdir` has no
+    "TD" of its own, "TD" is mapped to "TB" here (same direction, just
+    Graphviz's own name for it) -- every other value is used verbatim.
+    Anything outside that vocabulary raises `ValueError` naming the
+    valid options, rather than silently producing invalid DOT syntax.
+
+    `color_by_action` (default True) -- see this module's own docstring.
+    Pass False for a plain, uncolored digraph.
+
+    Returns (dot_text, warnings) -- same warning cases as
+    graph_to_mermaid(): a node whose `related_node` doesn't resolve to
+    another node actually present in `graph` (same context) is still
+    drawn, but its edge is skipped and reported as a warning; and, if
+    `color_by_action` is True and the graph has more distinct actions
+    than the palette has colors (currently 8), one warning notes that
+    colors repeat.
+    """
+    orientation = normalize_orientation(orientation)
+    rankdir = "TB" if orientation == "TD" else orientation
+
+    by_key: Dict[Tuple[str, str], AATNode] = {_node_key(n): n for n in graph.nodes}
+
+    color_of_node: Dict[Tuple[str, str], ColorTriple] = {}
+    warnings: List[str] = []
+    if color_by_action:
+        color_of_node, color_warnings = assign_action_colors(graph)
+        warnings.extend(color_warnings)
+
+    lines = ["digraph aat {", f"    rankdir={rankdir};"]
+
+    for node in graph.nodes:
+        attrs = [f"shape={_ROLE_SHAPE.get(node.role, 'box')}"]
+        styles = list(_ROLE_EXTRA_STYLES.get(node.role, []))
+
+        color = color_of_node.get(_node_key(node))
+        if color is not None:
+            fill, stroke, text = color
+            styles.append("filled")
+            attrs.append(f'fillcolor="{fill}"')
+            attrs.append(f'color="{stroke}"')
+            attrs.append(f'fontcolor="{text}"')
+
+        if styles:
+            attrs.append(f'style="{",".join(styles)}"')
+        attrs.append(f'label="{_escape_label(node.value)}"')
+
+        lines.append(f'    {node.id} [{", ".join(attrs)}];')
+
+    for node in graph.nodes:
+        if node.related_node is None:
+            continue
+        target_key = (node.context, node.related_node)
+        if target_key not in by_key:
+            warnings.append(
+                f"skipped edge {node.id} -[{node.role}]-> {node.related_node}: "
+                "target is not a node in this graph"
+            )
+            continue
+        edge_label = "dependent" if node.role == "action" else node.role
+        lines.append(f'    {node.id} -> {node.related_node} [label="{edge_label}"];')
+
+    lines.append("}")
+    return "\n".join(lines), warnings
+
+
+def save_dot(
+    graph: AATGraph,
+    path: str,
+    orientation: str = "BT",
+    color_by_action: bool = True,
+) -> List[str]:
+    """Write the digraph to `path` (e.g. 'analysis.dot') and return any
+    warnings from graph_to_dot(). `orientation` is validated the same
+    way -- see graph_to_dot()'s own docstring."""
+    dot_text, warnings = graph_to_dot(graph, orientation=orientation, color_by_action=color_by_action)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(dot_text + "\n")
+    return warnings