grammatike

36class Token(BaseModel):
37    """A single pre-segmented token with a stable id.
38
39    `citation` is optional so this model still works for citation-free
40    callers -- e.g. a test fixture built directly from a canned tokengraph,
41    with no CitedText source at all -- as well as for the citation-aware
42    segmentation stage (segmentation.py), which is the only thing that
43    actually populates it, knowing which CitedText source unit each token
44    came from."""
45
46    id: str = Field(description="Stable token id, globally unique and sequential across the whole input, e.g. 't0', 't1', ...")
47    text: str = Field(description="The token's surface text, exactly as it appears in the source.")
48    citation: Optional[str] = Field(
49        default=None,
50        description="Citation label of the source unit this token came from (e.g. 'Lysias 1.1'), if known.",
51    )

24class CitedText(BaseModel):
25    """One citable unit of source text -- e.g. one line of poetry, one
26    section of prose -- paired with its citation label. A sequence of
27    these is segmentation.py's input: sentence boundaries do NOT need
28    to respect CitedText boundaries (one sentence may span several units),
29    but every resulting token still records which unit it came from via
30    Token.citation."""
31
32    citation: str = Field(description="Citation label for this unit, e.g. 'Lysias 1.1'.")
33    text: str = Field(description="This unit's raw text, exactly as written.")

54class Sentence(BaseModel):
55    """One sentence's worth of tokens, in reading order, as produced by the
56    deterministic segmentation stage (segmentation.py). Token ids are
57    global across the whole passage -- numbering continues across sentence
58    boundaries rather than restarting at t0 for each sentence -- so a
59    Sentence is a contiguous slice of the passage's id sequence, not an
60    independently-numbered unit."""
61
62    tokens: List[Token] = Field(
63        description="This sentence's tokens, in reading order, using the passage's global token ids."
64    )

 67class VerbalExpression(BaseModel):
 68    """One entry in the table of verbal expressions (syntax_model.md, 'Basic
 69    model' / verbal-expression sections). Three constructions count as a
 70    verbal expression: finite verbs, infinitives (only when part of indirect
 71    speech), and participles -- but only some participles: an *attributive*
 72    participle (e.g. ὁ ἀνὴρ ὁ ὑβρίζων εἰς σέ, "the man who is insulting
 73    you") and a *circumstantial* participle (e.g. χρόνου μεταξὺ
 74    διαγενομένου, "when some time had passed") each constitute a verbal
 75    expression of their own, as does a participle expressing indirect
 76    speech after a verb of perception or thinking (εἶδε τὴν βασίλειαν
 77    φεύγουσαν, "he saw the queen fleeing"). A *supplementary* participle
 78    (e.g. ὁ ἀνὴρ ἐχθρὸς ὢν ἡμῖν τυγχάνει, where ὤν supplements τυγχάνει) is
 79    NOT a verbal expression at all -- it does not get its own entry here.
 80
 81    Each construction has its own set of allowed `syntactic_type` values,
 82    given explicitly by syntax_model.md rather than left to convention:
 83    a finite verb is 'independent', 'dependent', 'direct quote' (occurring
 84    in directly quoted speech, e.g. πειρᾷς in '"ἵνα σύ γε" ἔφη "πειρᾷς
 85    ἐνταῦθα τὴν παιδίσκην"'), or 'aside' (a verbal expression that
 86    interrupts the surrounding syntax, e.g. δεῖ in 'δεῖ γὰρ καὶ ταῦθ᾽
 87    ὑμῖν διηγήσασθαι'); an infinitive or participle anchoring an indirect
 88    statement is always 'indirect statement'; an attributive participle is
 89    'attributive'; a circumstantial participle is 'circumstantial'."""
 90
 91    id: str = Field(
 92        description=(
 93            "The token id (from the input `tokens` list) of the finite verb, "
 94            "infinitive, or participle that anchors this verbal expression. "
 95            "For a multi-word compound form with a conjugated form of εἰμί "
 96            "(e.g. the perfect passive/middle system, ὁ νόμος γεγραμμένος "
 97            "ἐστίν), use the id of the conjugated form of εἰμί, not the "
 98            "participle. For an implied/elided verbal expression (see "
 99            "TokenAnalysis's 'implied eimi'/'implied repetition' tokentypes, "
100            "IMPLIED_TOKENTYPES), use the new implied token's id instead -- "
101            "an implied token always anchors its own verbal expression."
102        )
103    )
104    syntactic_type: Literal[
105        "independent",
106        "dependent",
107        "direct quote",
108        "aside",
109        "indirect statement",
110        "attributive",
111        "circumstantial",
112    ] = Field(
113        description=(
114            "For a finite verb: 'independent' (main/principal), 'dependent' "
115            "(subordinate/secondary, introduced by a subordinating "
116            "conjunction or relative/interrogative pronoun), 'direct quote' "
117            "(occurring in directly quoted speech), or 'aside' (interrupts "
118            "the surrounding syntax). For an infinitive, or a participle "
119            "after a verb of perception/thinking, anchoring an indirect "
120            "statement: 'indirect statement'. For an attributive "
121            "participle: 'attributive'. For a circumstantial participle "
122            "(including a genitive absolute): 'circumstantial'."
123        )
124    )
125    semantic_type: Literal[
126        "transitive active", "transitive passive", "intransitive", "linking verb"
127    ] = Field(description="The verb's semantic/voice type.")

262class TokenAnalysis(BaseModel):
263    """One entry per token in the dependency graph (syntax_model.md,
264    'Token-level table of dependencies'). Not every token will have a
265    relation -- leave the relatedtoken*/relationship* fields unset when none
266    of the documented relations apply (e.g. an independent verb has no
267    relation2, and a punctuation token typically has none at all).
268
269    Most entries correspond 1:1 to an entry in the input `tokens` list. The
270    exceptions are the two IMPLIED_TOKENTYPES values below: syntax_model.md's
271    'understood or implied verbal expressions' section documents two
272    DIFFERENT situations where a verbal expression exists grammatically but
273    has no surface realization at all in the passage, and this codebase
274    distinguishes them with two distinct tokentype values rather than one
275    generic 'implied':
276
277    - 'implied eimi': an elided form of εἰμί ("to be") in a predicate
278      expression. Example: ταύτην τὴν ὕβριν ἅπαντες ἄνθρωποι δεινοτάτην
279      ἡγοῦνται has an implied infinitive of εἰμί governing the predicate
280      ταύτην τὴν ὕβριν ... δεινοτάτην in indirect statement after
281      ἡγοῦνται.
282    - 'implied repetition': a verb elided from a later verbal expression in
283      a coordinated series because it repeats the verb of an earlier one.
284      Example: ἐγὼ μὲν ἄνω διῃτώμην, αἱ δὲ γυναῖκες κάτω elides a second
285      διῃτώμην after γυναῖκες.
286
287    For either, add a NEW entry here -- with a NEW id, not present in
288    `tokens` -- rather than skipping the construction entirely; see
289    greek_syntax_dspy.SyntaxAnalysis's docstring for the full rules and the
290    id-naming convention."""
291
292    id: str = Field(
293        description=(
294            "For an ordinary entry, must match the id of the corresponding "
295            "entry in the input `tokens` list. For an implied token "
296            "(tokentype in IMPLIED_TOKENTYPES -- 'implied eimi' or "
297            "'implied repetition'), a NEW id not used by any entry in "
298            "`tokens` or elsewhere in this tokengraph -- see "
299            "SyntaxAnalysis's docstring for the naming convention."
300        )
301    )
302    token: Optional[str] = Field(
303        default=None,
304        description=(
305            "The token's surface text; should match the `text` of the input "
306            "token with this id. Leave as None ONLY for an implied token "
307            "(tokentype 'implied eimi' or 'implied repetition') -- one with "
308            "no surface realization in the passage at all; every other "
309            "tokentype must have real text."
310        ),
311    )
312    tokentype: Literal[
313        "lexical", "enclitic", "punctuation", "numeral",
314        "implied eimi", "implied repetition",
315    ] = Field(
316        description=(
317            "'numeral' is a number written NUMERICALLY (e.g. in Milesian "
318            "notation) rather than spelled out as a word; a number spelled "
319            "out as an ordinary word (e.g. δύω for 'two') is 'lexical' "
320            "instead, even though it's semantically a number -- e.g. in "
321            "'Ἀτρεΐδα δὲ μάλιστα δύω', δύω is 'lexical', not 'numeral'. "
322            "'enclitic' tokenization must consider context -- syntax_model.md's "
323            "tokenization section documents this. "
324            "'implied eimi' and 'implied repetition' each mark a token with "
325            "NO surface realization at all (see this model's own docstring "
326            "for the distinction) -- the only two tokentypes whose `token` "
327            "field is None and whose `id` is not one of the input `tokens`' "
328            "own ids."
329        )
330    )
331
332    lemma: Optional[str] = Field(default=None, description="Dictionary headword, for lexical tokens. Omit for punctuation.")
333    verbalunitid: Optional[str] = Field(
334        default=None,
335        description="If this token anchors a verbal expression in `verbalunits`, repeat its own id here; otherwise omit.",
336    )
337
338    relatedtoken1: Optional[str] = Field(
339        default=None,
340        description=(
341            "Token id this token relates to (primary relation). For an "
342            "INDEPENDENT verb's own 'unit verb' relation, use the special "
343            "sentinel string 'root' instead of a token id -- 'root' is "
344            "reserved and must never be assigned as an actual token's id."
345        ),
346    )
347    relationship1: Optional[RelationLabel] = Field(default=None, description="The primary relation type, if any.")
348
349    relatedtoken2: Optional[str] = Field(default=None, description="Token id this token relates to (secondary relation, used when relation1 is already occupied -- e.g. a relative pronoun's function inside its own clause).")
350    relationship2: Optional[RelationLabel] = Field(default=None, description="The secondary relation type, if any.")

114def tokengraph_to_mermaid(
115    tokengraph: List[TokenAnalysis],
116    orientation: str = "BT",
117    color_by_verbal_unit: bool = True,
118) -> Tuple[str, List[str]]:
119    """Build a Mermaid `graph` diagram from a tokengraph.
120
121    `orientation` is Mermaid's own flowchart orientation code -- `BT`
122    (bottom-to-top, the default here), `TB`, `LR`, or `RL` -- used verbatim
123    in the diagram's opening line (`graph BT`, `graph LR`, etc.). See
124    https://mermaid.js.org/syntax/flowchart.html for what each value looks
125    like; this function doesn't validate it, so a typo just becomes invalid
126    Mermaid syntax in the output rather than an error here.
127
128    `color_by_verbal_unit` (default True) colors every node by the verbal
129    unit it belongs to, per verbal_units.assign_verbal_units() -- so each
130    clause is visually distinguishable. Verbal units are assigned colors
131    from `_VERBAL_UNIT_PALETTE` in the order their tokens first appear in
132    `tokengraph`; a token assigned to no verbal unit is left with Mermaid's
133    default node styling. The one exception is an implied/elided token
134    (models.py's IMPLIED_TOKENTYPES) -- it always gets its own dedicated
135    `implied` class, colored with `verbal_units._IMPLIED_TOKEN_COLOR`,
136    instead of whatever `_VERBAL_UNIT_PALETTE` color its own verbal unit
137    would otherwise get (see this module's own docstring for why). Pass
138    False to skip coloring and get a plain diagram, as before this
139    parameter existed.
140
141    Returns (diagram_text, warnings). `warnings` lists any edges that were
142    skipped because they referenced a punctuation token or an id not present
143    in `tokengraph` -- worth checking, since it usually means the id came
144    from a validation problem upstream (see greek_syntax_dspy.validate) --
145    plus, if `color_by_verbal_unit` is True and the passage has more than 8
146    verbal units, one warning that colors are repeating rather than staying
147    distinct (the palette has 8 slots; see _VERBAL_UNIT_PALETTE).
148    """
149    node_ids = {tok.id for tok in tokengraph if tok.tokentype != "punctuation"}
150
151    lines = [f"graph {orientation}"]
152    for tok in tokengraph:
153        if tok.id not in node_ids:
154            continue
155        # An implied/elided token (see models.py's IMPLIED_TOKENTYPES) has
156        # no surface text at all -- tok.token is None -- so it needs a
157        # placeholder label rather than crashing _escape_label() on None.
158        # _IMPLIED_TOKEN_LABELS supplies that ("elided eimi" for "implied
159        # eimi", "implied repetition" verbatim); the node's color (below)
160        # is what actually marks it as an implied token, not the label
161        # text. token_label() is the shared helper dot.py's
162        # tokengraph_to_dot() also uses, so both renderers agree on this.
163        label = token_label(tok)
164        lines.append(f'    {tok.id}["{_escape_label(label)}"]')
165
166    warnings = []
167    for tok in tokengraph:
168        if tok.id not in node_ids:
169            continue
170        for related_field, label_field in (
171            ("relatedtoken1", "relationship1"),
172            ("relatedtoken2", "relationship2"),
173        ):
174            related_id = getattr(tok, related_field)
175            label = getattr(tok, label_field)
176            if related_id is None or label is None:
177                continue
178            if related_id == "root":
179                # An independent verb's own unit-verb relation, per
180                # syntax_model.md -- intentionally not a real node, so not
181                # a warning-worthy gap. Just draw no edge for it.
182                continue
183            if related_id not in node_ids:
184                warnings.append(
185                    f"skipped edge {tok.id} -[{label}]-> {related_id}: "
186                    f"target is punctuation or not in tokengraph"
187                )
188                continue
189            lines.append(f'    {tok.id} -->|{_escape_label(label)}| {related_id}')
190
191    if color_by_verbal_unit:
192        assignment = assign_verbal_units(tokengraph)
193        colors, color_warnings = assign_verbal_unit_colors(tokengraph, assignment=assignment)
194        warnings.extend(color_warnings)
195
196        # Implied tokens (models.py's IMPLIED_TOKENTYPES) always get a
197        # dedicated "caution" amber (_IMPLIED_TOKEN_COLOR) instead of
198        # whatever color their own verbal unit would otherwise get --
199        # regardless of which unit they anchor -- so they're excluded from
200        # every per-unit `member_ids` group below and given their own
201        # classDef/class pair instead. See rendering.py's
202        # tokengraph_to_html() docstring for the matching HTML behavior.
203        implied_ids = [
204            tok.id
205            for tok in tokengraph
206            if tok.id in node_ids and tok.tokentype in IMPLIED_TOKENTYPES
207        ]
208
209        # A token whose relationship1 is specifically "sentence connector"
210        # (e.g. γάρ tying this sentence back to the previous one -- see
211        # rendering.py's identical carve-out, and models.py's RelationLabel
212        # docstring for the distinction from the more general "connecting
213        # word") always gets its own dedicated `sentenceconnector` class --
214        # a neon-yellow fill with a strong black border -- instead of
215        # whatever color its own verbal unit would otherwise get,
216        # regardless of which unit it's assigned to. Excluded from
217        # implied_ids (in the never-really-expected case a token is somehow
218        # both) so the two classes never compete for the same node.
219        connector_ids = [
220            tok.id
221            for tok in tokengraph
222            if tok.id in node_ids
223            and tok.id not in implied_ids
224            and tok.relationship1 == "sentence connector"
225        ]
226
227        if colors or implied_ids or connector_ids:
228            lines.append("")
229            class_names = {}
230            for i, (unit_id, (fill, stroke, text)) in enumerate(colors.items()):
231                class_name = f"vu{i}"
232                class_names[unit_id] = class_name
233                lines.append(
234                    f"    classDef {class_name} fill:{fill},stroke:{stroke},color:{text};"
235                )
236            for unit_id in colors:
237                member_ids = [
238                    tok.id
239                    for tok in tokengraph
240                    if tok.id in node_ids
241                    and assignment.get(tok.id) == unit_id
242                    and tok.id not in implied_ids
243                    and tok.id not in connector_ids
244                ]
245                if member_ids:
246                    lines.append(f"    class {','.join(member_ids)} {class_names[unit_id]};")
247            if implied_ids:
248                fill, stroke, text = _IMPLIED_TOKEN_COLOR
249                lines.append(
250                    f"    classDef implied fill:{fill},stroke:{stroke},color:{text};"
251                )
252                lines.append(f"    class {','.join(implied_ids)} implied;")
253            if connector_ids:
254                lines.append(
255                    "    classDef sentenceconnector fill:#ffff00,stroke:#000000,stroke-width:4px,color:#000000;"
256                )
257                lines.append(f"    class {','.join(connector_ids)} sentenceconnector;")
258
259    return "\n".join(lines), warnings

262def save_mermaid(
263    tokengraph: List[TokenAnalysis],
264    path: str,
265    orientation: str = "BT",
266    color_by_verbal_unit: bool = True,
267) -> List[str]:
268    """Write the diagram to `path` (e.g. 'analysis.mmd') and return any
269    warnings from tokengraph_to_mermaid."""
270    diagram, warnings = tokengraph_to_mermaid(
271        tokengraph, orientation=orientation, color_by_verbal_unit=color_by_verbal_unit
272    )
273    with open(path, "w", encoding="utf-8") as f:
274        f.write(diagram + "\n")
275    return warnings

161def assign_verbal_units(tokengraph: List[TokenAnalysis]) -> Dict[str, Optional[str]]:
162    """Return {token id: verbal unit id or None}, one entry per token in
163    `tokengraph` (including punctuation and unrelated tokens, so every id
164    is accounted for -- callers that only care about assigned tokens can
165    filter out the None values themselves).
166
167    A verbal unit's own anchor token is assigned to itself (its
168    `verbalunitid`). Every other token is assigned to the verbal unit its
169    relations resolve to, per this module's docstring; a token with no
170    resolvable relation (e.g. a bare accusative of time, an enclitic left
171    unrelated) gets None.
172
173    A true genitive-absolute noun (its own outgoing relation is "genitive
174    absolute", not some normal clause role) is redirected to the verbal
175    unit of the circumstantial participle it agrees with, rather than to
176    the verb its own relatedtoken1 points at -- see this module's
177    docstring for the full "προϊόντος δὲ τοῦ χρόνου ... ἧκον" example.
178    Anything that in turn chains through that noun (an adjective, an
179    appositive) follows it into the participle's unit too, since this
180    redirect happens once, at the noun itself, and every other resolution
181    is unchanged.
182
183    Attributive participles need NO analogous redirect: the noun/pronoun
184    they agree with always keeps its ordinary syntactic role (there is no
185    "attributive absolute" construction), so it resolves correctly via the
186    plain fallback chase below without any special-casing -- see this
187    module's docstring for why.
188    """
189    by_id = {tok.id: tok for tok in tokengraph}
190
191    # Reverse index: for every token that some OTHER token points at via a
192    # "unit verb" relation, record who points at it. Per syntax_model.md,
193    # a "unit verb" target is always either the literal sentinel 'root'
194    # (from an independent verb -- never a real token) or a subordinating
195    # conjunction/relative (or interrogative) pronoun's id (from a
196    # dependent verb) -- so a hit here always means "this token introduces
197    # the pointing verb's clause."
198    introduces_clause_for: Dict[str, str] = {}
199    # Reverse index: for every token that some OTHER token points at via a
200    # "circumstantial participle" relation, record who points at it (the
201    # participle -- real or implied -- that agrees with it). Used below to
202    # redirect a TRUE genitive-absolute noun to that participle's own
203    # verbal unit instead of the verb it otherwise points at; a noun a
204    # circumstantial participle agrees with that fits normally into the
205    # clause (its own outgoing relation isn't "genitive absolute") is left
206    # alone and keeps resolving normally, so this index is consulted but
207    # not always used.
208    #
209    # There is deliberately NO analogous reverse index for "attributive
210    # participle": the noun/pronoun an attributive participle agrees with
211    # never needs redirecting (see this module's docstring), so building
212    # one here would just be dead code.
213    circumstantial_participle_for: Dict[str, str] = {}
214    for tok in tokengraph:
215        for related_field, label_field in (
216            ("relatedtoken1", "relationship1"),
217            ("relatedtoken2", "relationship2"),
218        ):
219            related = getattr(tok, related_field)
220            label = getattr(tok, label_field)
221            if related is None or related == "root":
222                continue
223            if label == _UNIT_VERB:
224                introduces_clause_for[related] = tok.id
225            elif label == _CIRCUMSTANTIAL_PARTICIPLE:
226                circumstantial_participle_for[related] = tok.id
227
228    resolved: Dict[str, Optional[str]] = {}
229    in_progress: set = set()
230
231    def resolve(tid: str) -> Optional[str]:
232        if tid in resolved:
233            return resolved[tid]
234        tok = by_id.get(tid)
235        if tok is None:
236            return None
237
238        if tok.verbalunitid is not None:
239            resolved[tid] = tok.verbalunitid
240            return tok.verbalunitid
241
242        if tid in in_progress:
243            # A cycle in the relation graph (malformed LM output) -- bail
244            # out on this token rather than recursing forever.
245            return None
246        in_progress.add(tid)
247
248        result = None
249
250        clause_verb_id = introduces_clause_for.get(tid)
251        if clause_verb_id is not None:
252            result = resolve(clause_verb_id)
253
254        if result is None:
255            participle_id = circumstantial_participle_for.get(tid)
256            is_genitive_absolute = (
257                tok.relationship1 == _GENITIVE_ABSOLUTE
258                or tok.relationship2 == _GENITIVE_ABSOLUTE
259            )
260            if participle_id is not None and is_genitive_absolute:
261                result = resolve(participle_id)
262
263        if result is None:
264            for related_field in ("relatedtoken1", "relatedtoken2"):
265                related = getattr(tok, related_field)
266                if related is None or related == "root":
267                    continue
268                result = resolve(related)
269                if result is not None:
270                    break
271
272        in_progress.discard(tid)
273        resolved[tid] = result
274        return result
275
276    for tid in by_id:
277        resolve(tid)
278
279    return resolved

282def assign_verbal_unit_colors(
283    tokengraph: List[TokenAnalysis],
284    assignment: Optional[Dict[str, Optional[str]]] = None,
285) -> Tuple[Dict[str, Tuple[str, str, str]], List[str]]:
286    """Assign each verbal unit found in `tokengraph` a stable (fill, stroke,
287    text) triple from `_VERBAL_UNIT_PALETTE`, using the exact ordering rule
288    `tokengraph_to_mermaid()` uses for its node coloring -- so any other
289    caller wanting "the same colors as the mermaid graph" (currently
290    rendering.py's `tokengraph_to_html()`) gets an identical mapping without
291    re-deriving the rule itself.
292
293    Order is by first appearance of each verbal unit among tokengraph's
294    *non-punctuation* tokens, since those are the only tokens that become
295    mermaid nodes at all -- a verbal unit whose earliest token happens to be
296    punctuation (it can't be: punctuation tokens aren't assigned to a
297    verbal unit's anchor, but could in principle inherit one from a
298    relation) still gets ordered by its first non-punctuation member.
299
300    Pass `assignment` (the result of `assign_verbal_units(tokengraph)`) if
301    the caller already computed it, to avoid re-deriving it here; otherwise
302    it's computed internally.
303
304    Returns `({verbal unit id: (fill, stroke, text)}, warnings)` --
305    `warnings` holds one entry, with the same wording
306    `tokengraph_to_mermaid()` uses, if there are more distinct verbal units
307    than palette slots (colors repeat past the 8th unit). A verbal unit id
308    absent from the returned dict was never assigned to any non-punctuation
309    token -- callers should treat that the same as "no verbal unit" (no
310    coloring), same as `tokengraph_to_mermaid()` does.
311    """
312    if assignment is None:
313        assignment = assign_verbal_units(tokengraph)
314
315    non_punctuation_ids = {tok.id for tok in tokengraph if tok.tokentype != "punctuation"}
316
317    unit_order: List[str] = []
318    seen_units = set()
319    for tok in tokengraph:
320        if tok.id not in non_punctuation_ids:
321            continue
322        unit_id = assignment.get(tok.id)
323        if unit_id is not None and unit_id not in seen_units:
324            seen_units.add(unit_id)
325            unit_order.append(unit_id)
326
327    warnings: List[str] = []
328    if len(unit_order) > len(_VERBAL_UNIT_PALETTE):
329        warnings.append(
330            f"{len(unit_order)} verbal units but only {len(_VERBAL_UNIT_PALETTE)} "
331            "distinct colors -- colors repeat and may be ambiguous between units"
332        )
333
334    colors = {
335        unit_id: _VERBAL_UNIT_PALETTE[i % len(_VERBAL_UNIT_PALETTE)]
336        for i, unit_id in enumerate(unit_order)
337    }
338    return colors, warnings

341def compute_subordination_depths(
342    tokengraph: List[TokenAnalysis],
343) -> Tuple[Dict[str, Optional[int]], List[str]]:
344    """Compute each verbal expression's *depth of subordination*: the
345    number of verbal expressions it is removed from an independent ("root")
346    clause. An independent verb is depth 0; a verb it introduces (a
347    dependent clause, a direct quote, an aside) is depth 1; a verbal
348    expression THAT verb in turn introduces (e.g. an indirect statement
349    inside a dependent clause) is depth 2; and so on.
350
351    A "verbal expression" here is any token that anchors one -- i.e. any
352    token with `verbalunitid` set to its own id (the same convention
353    `assign_verbal_units()` relies on). For each anchor, this function
354    finds its *parent* anchor -- the verbal expression it's subordinate to
355    -- by following the anchor's own relatedtoken1 (falling back to
356    relatedtoken2), through as many intermediate non-anchor tokens as
357    necessary, until it lands on another anchor. This one chase handles
358    every documented case uniformly, without needing to special-case by
359    relationship label, because they all eventually resolve to another
360    anchor via forward pointers already in the graph:
361
362    - unit verb (independent): relatedtoken1 == 'root' -> no parent, depth 0.
363    - unit verb (dependent): relatedtoken1 -> a subordinating conjunction or
364      relative/interrogative pronoun (not itself an anchor) -> ITS
365      relatedtoken1 -> the superior verb (a conjunction) or an antecedent
366      noun (a relative pronoun), the latter requiring one more hop through
367      the noun's own relation to reach the verb it depends on. Example:
368      "ἐπειδὴ δὲ ἦν πρὸς ἡμέραν, ἧκεν ἐκείνη" -- ἦν's relatedtoken1 is
369      ἐπειδὴ, whose own relatedtoken1 is ἧκεν.
370    - direct quote / aside / indirect statement: relatedtoken1 -> the verb
371      of the clause it interrupts, is framed by, or (for an indirect-
372      statement infinitive or participle) governs it, directly (no
373      intermediate token). Examples: πειρᾷς -> ἔφη (direct quote); δεῖ ->
374      ἔστι (aside); ἀποσβεσθῆναι -> ἔφασκε (indirect statement, an
375      infinitive); φεύγουσαν -> εἶδε (indirect statement, a participle
376      after a verb of perception).
377    - circumstantial participle: relatedtoken1 -> the noun/pronoun it
378      agrees with (not itself an anchor) -> that noun's own relation,
379      either its normal role in the surrounding clause (one more hop to a
380      verb, e.g. παραλείπων/λέγων -> ἐγώ -> ἐπιδείξω via "subject") or, for
381      a true genitive absolute, 'genitive absolute' pointing directly at
382      the main verb (e.g. προϊόντος -> χρόνου -> ἧκον).
383    - attributive participle: structurally identical to the circumstantial
384      case above, just with a different relationship label and no
385      "absolute" variant -- relatedtoken1 -> the noun/pronoun it agrees
386      with (not itself an anchor) -> that noun's own ordinary relation,
387      one more hop to the governing verb. Example: "ὁ γὰρ ἀνὴρ ὁ ὑβρίζων
388      εἰς σὲ ... τυγχάνει" -- ὑβρίζων's relatedtoken1 is ἀνήρ, whose own
389      relatedtoken1 (relationship1 "subject") is τυγχάνει. This is the one
390      construction with no Latin precedent at all (Latin's scheme never
391      treats an attributive participle as a verbal expression), but it
392      needs no new code here: the same generic hop-through-the-noun chase
393      that already handles circumstantial participles handles it too.
394
395    Returns `({anchor id: depth or None}, warnings)`. A depth of `None`
396    means the chase from that anchor never reached another anchor (a
397    malformed or genuinely disconnected verbal expression) or a cycle was
398    detected; `warnings` names which anchor(s) and why, mirroring
399    `tokengraph_to_mermaid()`'s warnings-list convention rather than
400    raising.
401    """
402    by_id = {tok.id: tok for tok in tokengraph}
403    anchor_ids = {tok.id for tok in tokengraph if tok.verbalunitid == tok.id}
404
405    warnings: List[str] = []
406
407    def chase(token_id: str, visited: set) -> Optional[str]:
408        """Follow relatedtoken1 (then relatedtoken2) forward from
409        `token_id`, returning the first anchor id reached, or None if the
410        chain dead-ends or cycles before reaching one. `token_id` itself
411        counts as a hit if it's already an anchor (the direct-link cases:
412        direct quote, aside, indirect statement)."""
413        if token_id in visited:
414            return None
415        visited.add(token_id)
416        if token_id in anchor_ids:
417            return token_id
418        tok = by_id.get(token_id)
419        if tok is None:
420            return None
421        for field in ("relatedtoken1", "relatedtoken2"):
422            target = getattr(tok, field)
423            if target is None or target == "root":
424                continue
425            result = chase(target, visited)
426            if result is not None:
427                return result
428        return None
429
430    def parent_of(anchor_id: str) -> Optional[str]:
431        tok = by_id[anchor_id]
432        for field in ("relatedtoken1", "relatedtoken2"):
433            target = getattr(tok, field)
434            if target is None or target == "root":
435                continue
436            result = chase(target, visited=set())
437            if result is not None and result != anchor_id:
438                return result
439        return None
440
441    depths: Dict[str, Optional[int]] = {}
442    in_progress: set = set()
443
444    def depth_of(anchor_id: str) -> Optional[int]:
445        if anchor_id in depths:
446            return depths[anchor_id]
447        tok = by_id[anchor_id]
448        if tok.relatedtoken1 == "root":
449            depths[anchor_id] = 0
450            return 0
451
452        if anchor_id in in_progress:
453            warnings.append(
454                f"cycle detected resolving the governing verbal expression "
455                f"for {anchor_id!r} -- leaving its depth (and its parent's) "
456                f"unresolved"
457            )
458            return None
459        in_progress.add(anchor_id)
460
461        parent = parent_of(anchor_id)
462        if parent is None:
463            warnings.append(
464                f"could not find a governing verbal expression for "
465                f"{anchor_id!r} -- leaving its depth unresolved"
466            )
467            result = None
468        else:
469            parent_depth = depth_of(parent)
470            result = None if parent_depth is None else parent_depth + 1
471
472        in_progress.discard(anchor_id)
473        depths[anchor_id] = result
474        return result
475
476    for anchor_id in anchor_ids:
477        depth_of(anchor_id)
478
479    return depths, warnings

482def max_subordination_depth(
483    tokengraph: List[TokenAnalysis],
484    depths: Optional[Dict[str, Optional[int]]] = None,
485) -> Optional[int]:
486    """Return the deepest level of subordination reached anywhere in
487    `tokengraph` -- the highest value `compute_subordination_depths()`
488    assigns to any verbal expression. Root/independent clauses are depth
489    0, so this is also the upper end of the valid `depth` range for
490    `rendering.tokengraph_to_depth_html()`'s own `depth` parameter (whose
491    valid range is 0, root clauses only, through this function's return
492    value, everything).
493
494    Pass `depths` (the first element of `compute_subordination_depths()`'s
495    return value) if the caller already computed it, to avoid re-deriving
496    it here; otherwise it's computed internally (any resolution warnings
497    are silently dropped in that case -- call
498    `compute_subordination_depths()` directly first if the caller also
499    needs those).
500
501    Returns `None` if `tokengraph` has no verbal expressions at all (an
502    empty passage, or one with none of the five constructions
503    syntax_model.md counts as one), or if every anchor's own depth came
504    back unresolved (see `compute_subordination_depths()`'s own
505    warnings for why an anchor might be unresolved -- a relation cycle, or
506    a governing verbal expression that couldn't be found). Otherwise
507    returns the maximum of every RESOLVED anchor's depth, ignoring
508    unresolved ones rather than letting a single bad anchor blank out the
509    whole result.
510    """
511    if depths is None:
512        depths, _warnings = compute_subordination_depths(tokengraph)
513
514    resolved = [d for d in depths.values() if d is not None]
515    if not resolved:
516        return None
517    return max(resolved)

520def find_unanchored_coordinated_verbs(tokengraph: List[TokenAnalysis]) -> List[str]:
521    """Heuristic sanity check, adapted from arsgrammatica's original, for a
522    class of live-LM mistake: a "connecting word" correctly marks a series
523    of coordinate CLAUSES, but one of the later clauses' own verb never
524    gets flagged as its own verbal-unit anchor (no `verbalunitid` set) --
525    e.g. an explicit verb the LM forgot to add to `verbalunits`, or a
526    missing 'implied repetition' token for an elided one.
527
528    This check USED to need a coarse, imprecise proxy (does some OTHER
529    verbal expression merely exist at the same subordination depth as the
530    series' first member?), because an earlier version of syntax_model.md's
531    "connecting word" relation recorded only ONE id anywhere in the graph
532    -- "the id of the first item" in the series -- never the id of the
533    item the connecting word itself was attached to, so there was nothing
534    to name the second (or later) member directly and compare against.
535    (Latin's own "coordinating conjunction", by contrast, always named
536    both conjuncts, one on relatedtoken1 and one on relatedtoken2 of the
537    same token -- see gold_examples.py's
538    coordinating_conjunction_dedit_et_dixit_esse fixture for the original,
539    Latin-side observation this function is adapted from.)
540
541    syntax_model.md's current "connecting word" rules (its "other uses of
542    connecting words" section) removed that limitation: every connecting
543    word now names ITS OWN adjacent item on relation1 (never generically
544    "the first item"), and relation2 completes the pair or series, in one
545    of three shapes -- see SyntaxAnalysis's own docstring for the full
546    account with worked examples:
547      - a single connecting word joining a pair: relation1 = the first
548        item's id, relation2 = the second item's id, both directly on the
549        SAME token.
550      - a paired correlative (τε...καί, a repeated καὶ...καί, or a
551        within-sentence μέν...δέ pair): each connector's own relation1 =
552        its own adjacent item, relation2 = the id of the OTHER connector.
553      - a 3+-member series (e.g. οὔτε...οὔτε...οὔτε): each connector's own
554        relation1 = its own adjacent item again; relation2 chains the
555        connectors together instead of naming an item -- the first
556        connector's relation2 points forward to the second connector, and
557        every later connector's relation2 points backward to the one
558        immediately before it.
559
560    This function exploits that added precision. It first groups every
561    "connecting word" token into its own coordinate chain: a lone token by
562    itself for the single-pair shape, or several tokens linked together
563    (by relation2 pointing from one connecting word to another) for a
564    correlative pair or series. For each chain, it collects every member's
565    own coordinated ITEM -- relation1 always, plus relation2 whenever that
566    ISN'T itself another connecting word in the same chain (i.e. the
567    direct second-item pointer the single-pair shape uses). If ANY item in
568    a chain turns out to be a recognized verbal-unit anchor, the whole
569    chain is coordinating CLAUSES (not nouns/adjectives/adverbs), so every
570    OTHER item in that chain is expected to be an anchor too -- one that
571    isn't gets named directly in a warning, the same precision Latin's
572    original dual-linked check had. A lone connecting word whose relation1
573    already points at an anchor but that has no relation2 at all (and no
574    correlative partner pointing back at it either) is flagged separately:
575    it looks like one half of a pair whose other half was never recorded.
576
577    "sentence connector" is deliberately excluded from this check, exactly
578    as before: syntax_model.md defines it as pointing at "the verb of THIS
579    sentence" -- the sentence it introduces, not a cross-clause pairing
580    with whatever precedes it (a sentence connector never records a
581    cross-sentence link) -- so it never asserts "there are two coordinate
582    members" the way "connecting word" does, and there is nothing here for
583    it to be checked against.
584
585    Returns a list of warning strings (empty if nothing looks suspicious),
586    the same "degrade visibly, don't raise" convention every other
587    warnings-returning function in this codebase uses. This is a
588    heuristic, not a guarantee: a clean result here isn't a substitute for
589    validate() or a human read of the analysis, and a flagged result
590    deserves a look rather than an automatic "fix."
591    """
592    by_id = {tok.id: tok for tok in tokengraph}
593    anchor_ids = {tok.id for tok in tokengraph if tok.verbalunitid == tok.id}
594    connecting_word_ids = {
595        tok.id for tok in tokengraph if tok.relationship1 == _CONNECTING_WORD
596    }
597
598    # Union-find over connecting-word tokens: two are in the same
599    # coordinate chain if either's relatedtoken2 names the other -- the
600    # correlative-pair/series-chaining shape described above. A lone
601    # connecting word (the single-pair shape) ends up its own singleton
602    # chain.
603    parent: Dict[str, str] = {cid: cid for cid in connecting_word_ids}
604
605    def find(x: str) -> str:
606        while parent[x] != x:
607            parent[x] = parent[parent[x]]
608            x = parent[x]
609        return x
610
611    def union(a: str, b: str) -> None:
612        ra, rb = find(a), find(b)
613        if ra != rb:
614            parent[ra] = rb
615
616    for cid in connecting_word_ids:
617        partner = by_id[cid].relatedtoken2
618        if partner in connecting_word_ids:
619            union(cid, partner)
620
621    chains: Dict[str, List[str]] = {}
622    for cid in connecting_word_ids:
623        chains.setdefault(find(cid), []).append(cid)
624
625    warnings: List[str] = []
626    for members in sorted(chains.values(), key=lambda m: sorted(m)):
627        items: List[Tuple[str, str]] = []  # (connecting word id, item id)
628        for cid in sorted(members):
629            tok = by_id[cid]
630            for target in (tok.relatedtoken1, tok.relatedtoken2):
631                if target is None or target == "root" or target in connecting_word_ids:
632                    continue
633                items.append((cid, target))
634
635        if not any(target in anchor_ids for _cid, target in items):
636            continue  # not a clause-coordinating chain -- nouns/adjectives/etc.
637
638        for cid, target in items:
639            if target in anchor_ids:
640                continue
641            item_tok = by_id.get(target)
642            text = item_tok.token if item_tok is not None else target
643            connector_tok = by_id[cid]
644            warnings.append(
645                f"{cid} ({connector_tok.token!r}) is a 'connecting word' "
646                "coordinating clauses (another member of its chain points "
647                "at a recognized verbal-unit anchor), but its own item "
648                f"{target!r} ({text!r}) is not itself anchored -- it may "
649                "be missing its own verbalunitid (an explicit verb that "
650                "wasn't flagged, or a missing 'implied repetition' token "
651                "if the verb was elided)."
652            )
653
654        if len(members) == 1:
655            only_cid = members[0]
656            tok = by_id[only_cid]
657            if tok.relatedtoken1 in anchor_ids and tok.relatedtoken2 is None:
658                warnings.append(
659                    f"{only_cid} ({tok.token!r}) is a 'connecting word' "
660                    "whose relation1 points at a recognized verbal-unit "
661                    "anchor, but it has no relation2 and no correlative "
662                    "partner -- it looks like one half of a coordinated "
663                    "pair whose other member was never recorded."
664                )
665
666    return warnings

276def tokengraph_to_dot(
277    tokengraph: List[TokenAnalysis],
278    orientation: str = "BT",
279    color_by_verbal_unit: bool = True,
280    rank_by_depth: bool = True,
281    depth: Optional[int] = None,
282) -> Tuple[str, List[str]]:
283    """Build a Graphviz DOT `digraph` from a tokengraph -- the same diagram
284    tokengraph_to_mermaid() draws (same nodes, same edges, same coloring),
285    as DOT source instead of Mermaid source. See this module's own
286    docstring for why this exists alongside tokengraph_to_mermaid(), the
287    two adaptations from arsgrammatica's own dot.py, and what actually
288    rendering the result requires.
289
290    `orientation` maps directly onto DOT's `rankdir` graph attribute -- `BT`
291    (bottom-to-top, the default here, matching tokengraph_to_mermaid()'s
292    own default), `TB`, `LR`, or `RL`. Not validated here, same as
293    tokengraph_to_mermaid()'s `orientation` -- a typo just becomes an
294    attribute value Graphviz itself will reject.
295
296    `color_by_verbal_unit` (default True) colors every node by the verbal
297    unit it belongs to, per verbal_units.assign_verbal_units() -- the exact
298    same colors (and the same >8-verbal-units warning) as
299    tokengraph_to_mermaid(), just written as `fillcolor`/`color`/
300    `fontcolor` attributes directly on each node line instead of Mermaid's
301    separate `classDef`/`class` statements (DOT has no equivalent of a
302    named, reusable class -- inline per-node attributes are the idiomatic
303    way to do this). An implied/elided token (IMPLIED_TOKENTYPES) always
304    gets its own dedicated amber (verbal_units._IMPLIED_TOKEN_COLOR)
305    instead of whatever color its own verbal unit would otherwise get, and
306    a token whose relationship1 is "sentence connector" always gets its own
307    dedicated neon-yellow/strong-border color (_SENTENCE_CONNECTOR_COLOR),
308    both exactly mirroring tokengraph_to_mermaid()'s own precedence (see
309    that function's docstring). Pass False for a plain, uncolored diagram.
310
311    `rank_by_depth` (default True) is the reason this module exists
312    alongside tokengraph_to_mermaid() -- see the module docstring. Every
313    verbal-unit anchor node (any token with `verbalunitid` set to its own
314    id, implied tokens included) at the same depth in
315    verbal_units.compute_subordination_depths() -- grammatike's own
316    substitute for arsgrammatica's compute_aat_depths(), see "Two
317    adaptations" in this module's own docstring -- gets listed together in
318    one `{rank=same; id1; id2; ...}` subgraph statement, which *forces*
319    Graphviz's layout engine to place them on the same rank -- not a nudge,
320    a hard constraint. A depth with only one anchor gets no `rank=same`
321    statement (nothing to align it WITH); an anchor whose subordination
322    depth came back unresolved (None -- a relation cycle, or no governing
323    verbal expression found; see compute_subordination_depths()'s own
324    docstring) is excluded from every grouping, and its own warning about
325    why is folded into this function's returned warnings. Pass False to
326    skip this and let Graphviz's own layout heuristics place every node.
327
328    `depth`, if given, caps the diagram to nodes at or within that many
329    edges of a root/independent verbal-unit anchor -- compute_graph_depths()
330    above, a plain GRAPH distance along the same relatedtoken1/
331    relatedtoken2 edges drawn as `->` lines below, NOT
332    verbal_units.compute_subordination_depths() (`rank_by_depth` above, and
333    the CLAUSE-level notion behind tokengraph_to_depth_html()'s own
334    indented-HTML `depth` slider -- a whole clause's subject, object, and
335    other ordinary dependents share ONE subordination depth with their
336    verb, but each is its own hop of GRAPH depth). `depth=0` shows ONLY
337    root anchors -- an independent verb with no dependents at all;
338    `depth=1` adds every token one edge away from a root anchor (its
339    subject, object, adverbials, ...); and so on. A token farther than
340    `depth` is dropped entirely: omitted as a node, exactly as if it had
341    never been in `tokengraph`. Omit `depth` (or pass `None`, the default)
342    to show every node, same as before this parameter existed. A `depth` at
343    or beyond max_graph_depth()'s own return value for this `tokengraph`
344    shows everything too; a negative `depth` raises ValueError.
345
346    Dropping a node can leave a KEPT node's edge pointing at a now-excluded
347    one. Such an edge is skipped, with the same combined warning already
348    used for an edge targeting punctuation or a genuinely absent id (see
349    Returns below) -- `depth` filtering degrades visibly rather than
350    emitting a dangling `->` line Graphviz would reject.
351
352    Returns `(dot_source, warnings)` -- same shape and same warnings as
353    tokengraph_to_mermaid(): an edge skipped because it targets a
354    punctuation token, a token excluded by the `depth` cutoff, or an id not
355    present in `tokengraph` (except the 'root' sentinel, skipped silently,
356    same as there); if `color_by_verbal_unit` is True and the passage has
357    more than 8 verbal units, one warning that colors are repeating.
358    `depth` filtering itself never adds a warning (compute_graph_depths()
359    has no unresolved state -- an unrelated or cyclic token just defaults
360    to depth 0), but `rank_by_depth` CAN add one -- see above, and the "Two
361    adaptations" section of this module's own docstring for why this
362    differs from arsgrammatica's own version.
363    """
364    if depth is not None and depth < 0:
365        raise ValueError(f"depth must be >= 0 (root nodes only), got {depth!r}")
366
367    node_ids = {tok.id for tok in tokengraph if tok.tokentype != "punctuation"}
368
369    warnings: List[str] = []
370    if depth is not None:
371        graph_depths = compute_graph_depths(tokengraph)
372        depth_excluded_ids = {tok_id for tok_id, d in graph_depths.items() if d > depth}
373        node_ids -= depth_excluded_ids
374
375    colors_by_unit: Dict[str, Tuple[str, str, str]] = {}
376    assignment: Dict[str, Optional[str]] = {}
377    implied_ids: set = set()
378    connector_ids: set = set()
379    if color_by_verbal_unit:
380        assignment = assign_verbal_units(tokengraph)
381        colors_by_unit, color_warnings = assign_verbal_unit_colors(tokengraph, assignment=assignment)
382        warnings.extend(color_warnings)
383        implied_ids = {
384            tok.id
385            for tok in tokengraph
386            if tok.id in node_ids and tok.tokentype in IMPLIED_TOKENTYPES
387        }
388        # See this module's own docstring, "Two adaptations" (2) --
389        # grammatike-specific, no arsgrammatica counterpart. Excluded from
390        # implied_ids (in the never-really-expected case a token is somehow
391        # both) so the two colors never compete for the same node, matching
392        # mermaid.py's own connector_ids precedent exactly.
393        connector_ids = {
394            tok.id
395            for tok in tokengraph
396            if tok.id in node_ids
397            and tok.id not in implied_ids
398            and tok.relationship1 == "sentence connector"
399        }
400
401    lines = ["digraph tokengraph {", f"    rankdir={orientation};", "    node [shape=box];", ""]
402    for tok in tokengraph:
403        if tok.id not in node_ids:
404            continue
405        color = None
406        strong_border = False
407        if color_by_verbal_unit:
408            if tok.id in implied_ids:
409                color = _IMPLIED_TOKEN_COLOR
410            elif tok.id in connector_ids:
411                color = _SENTENCE_CONNECTOR_COLOR
412                strong_border = True
413            else:
414                unit_id = assignment.get(tok.id)
415                color = colors_by_unit.get(unit_id) if unit_id is not None else None
416        lines.append(f"    {tok.id} [{_node_attrs(tok, color, strong_border)}];")
417
418    lines.append("")
419    for tok in tokengraph:
420        if tok.id not in node_ids:
421            continue
422        for related_field, label_field in (
423            ("relatedtoken1", "relationship1"),
424            ("relatedtoken2", "relationship2"),
425        ):
426            related_id = getattr(tok, related_field)
427            label = getattr(tok, label_field)
428            if related_id is None or label is None:
429                continue
430            if related_id == "root":
431                # An independent verb's own unit-verb relation, per
432                # syntax_model.md -- intentionally not a real node, so not
433                # a warning-worthy gap. Just draw no edge for it.
434                continue
435            if related_id not in node_ids:
436                warnings.append(
437                    f"skipped edge {tok.id} -[{label}]-> {related_id}: "
438                    f"target is punctuation, excluded by the depth cutoff, "
439                    f"or not in tokengraph"
440                )
441                continue
442            lines.append(f'    {tok.id} -> {related_id} [label="{_escape_label(label)}"];')
443
444    if rank_by_depth:
445        sub_depths, depth_warnings = compute_subordination_depths(tokengraph)
446        warnings.extend(depth_warnings)
447
448        # Same grouping tokengraph_to_mermaid() would build for a `~~~`
449        # chain if it had one -- see this module's own docstring, "Two
450        # adaptations" (1), for why sub_depths.get() being None here means
451        # "unresolved" (a cycle, or no governing verbal expression found),
452        # unlike arsgrammatica's own compute_aat_depths(), which has no such
453        # state. Named sub_depths (not `depths`, and this loop's own
454        # variable not `depth`) to avoid shadowing the `depth` PARAMETER
455        # above -- a different depth notion entirely, see this function's
456        # own docstring.
457        depth_groups: dict = {}
458        for tok in tokengraph:
459            if tok.id not in node_ids:
460                continue
461            anchor_depth = sub_depths.get(tok.id)
462            if anchor_depth is None:
463                continue
464            depth_groups.setdefault(anchor_depth, []).append(tok.id)
465
466        rank_lines = [
467            "    {rank=same; " + "; ".join(ids) + ";}"
468            for anchor_depth in sorted(depth_groups)
469            for ids in (depth_groups[anchor_depth],)
470            if len(ids) > 1
471        ]
472        if rank_lines:
473            lines.append("")
474            lines.extend(rank_lines)
475
476    lines.append("}")
477    return "\n".join(lines), warnings

480def save_dot(
481    tokengraph: List[TokenAnalysis],
482    path: str,
483    orientation: str = "BT",
484    color_by_verbal_unit: bool = True,
485    rank_by_depth: bool = True,
486    depth: Optional[int] = None,
487) -> List[str]:
488    """Write the diagram to `path` (e.g. 'analysis.dot') and return any
489    warnings from tokengraph_to_dot()."""
490    diagram, warnings = tokengraph_to_dot(
491        tokengraph,
492        orientation=orientation,
493        color_by_verbal_unit=color_by_verbal_unit,
494        rank_by_depth=rank_by_depth,
495        depth=depth,
496    )
497    with open(path, "w", encoding="utf-8") as f:
498        f.write(diagram + "\n")
499    return warnings