graphitect 0.2.0__py3-none-any.whl

graphitect/deliver/archify_ir.py

@@ -0,0 +1,160 @@
+"""archify's real architecture-mode IR - checked directly against
+archify/references/authoring-contract.md and archify/renderers/architecture/grid.mjs
+(not inferred from its README). See plan.md section 04's "Correction" note.
+
+Deliberately narrower than archify's full schema: this covers what
+graphitect.deliver.archify_adapter needs to emit (grid-mode architecture
+diagrams), not every mode/field archify's authoring contract supports.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+def _drop_empty_lists(value):
+    if isinstance(value, dict):
+        return {k: _drop_empty_lists(v) for k, v in value.items() if not (isinstance(v, list) and not v)}
+    if isinstance(value, list):
+        return [_drop_empty_lists(v) for v in value]
+    return value
+
+ComponentType = Literal[
+    "frontend", "backend", "database", "cloud", "security", "messagebus", "external"
+]
+ConnectionVariant = Literal["default", "emphasis", "security", "dashed"]
+ConnectionSide = Literal["left", "right", "top", "bottom"]
+ConnectionRoute = Literal["auto", "straight", "orthogonal-h", "orthogonal-v"]
+
+
+class GridLayout(BaseModel):
+    mode: Literal["grid"] = "grid"
+    cols: int = 4
+    # archify's own DEFAULT_GRID (renderers/architecture/grid.mjs) is
+    # {cellW: 130, gapX: 30, gapY: 40} - fine for short labels, but confirmed
+    # live to produce "label wider than component" and label/connection
+    # overlap failures on a real graph with longer labels ("Schema
+    # Discoverer Agent") and vertically-adjacent connected components.
+    # graphitect widens these based on actual label length instead of
+    # leaving archify's short-label default in place - see
+    # archify_adapter.to_architecture_ir.
+    cell_w: int | None = Field(default=None, alias="cellW")
+    cell_h: int | None = Field(default=None, alias="cellH")
+    gap_x: int | None = Field(default=None, alias="gapX")
+    gap_y: int | None = Field(default=None, alias="gapY")
+
+    model_config = {"populate_by_name": True}
+
+
+class Component(BaseModel):
+    id: str
+    type: ComponentType
+    label: str
+    sublabel: str | None = None
+    row: int | None = None
+    col: int | None = None
+    pos: tuple[int, int] | None = None  # explicit pixel pos wins over row/col
+    size: tuple[int, int] | None = None
+    tag: str | None = None
+    sources: list[dict] = Field(default_factory=list)  # repo-evidence links, see authoring-contract.md
+
+
+class Boundary(BaseModel):
+    kind: str  # e.g. "region", "security-group"
+    label: str
+    wraps: list[str]  # component ids
+
+
+class Connection(BaseModel):
+    id: str
+    from_: str = Field(alias="from")
+    to: str
+    label: str | None = None
+    variant: ConnectionVariant = "default"
+    # Routing/label-position overrides - unused by archify_adapter's own
+    # deterministic layout (it never sets these), but archify_repair's LLM
+    # loop writes them to resolve real validator diagnostics like
+    # clean-flow/edge-through-node and layout/constraint (label overlaps
+    # component) - see archify/references/authoring-contract.md and
+    # archify/schemas/architecture.schema.json's Connection definition,
+    # confirmed against the real schema rather than guessed.
+    from_side: ConnectionSide | None = Field(default=None, alias="fromSide")
+    to_side: ConnectionSide | None = Field(default=None, alias="toSide")
+    route: ConnectionRoute | None = None
+    via: list[tuple[float, float]] | None = None
+    label_at: tuple[float, float] | None = Field(default=None, alias="labelAt")
+    label_dx: float | None = Field(default=None, alias="labelDx")
+    label_dy: float | None = Field(default=None, alias="labelDy")
+    label_segment: int | None = Field(default=None, alias="labelSegment")
+
+    model_config = {"populate_by_name": True}
+
+
+class Card(BaseModel):
+    dot: str
+    title: str
+    items: list[str]
+
+
+class GuidedView(BaseModel):
+    """One evidence-grounded chapter in Archify's guided-story rail."""
+
+    id: str
+    label: str
+    focus: list[str]
+    note: str | None = None
+
+
+class Meta(BaseModel):
+    title: str
+    # Architecture's schema supports an explicit [width, height] canvas.
+    # Graphitect uses it when a safe detour lane extends past the rightmost
+    # component; otherwise Archify's automatic component-only bounds clip
+    # the valid connection geometry.
+    view_box: tuple[int, int] | None = Field(default=None, alias="viewBox")
+    # "draft" was never a real archify value - confirmed against its own
+    # --help output (`--quality standard|showcase`) - and defaulting to
+    # "showcase" made every real multi-node graph fail archify's strict
+    # layout validator (labels wider than boxes, overlapping connections,
+    # crossing corridors) since graphitect's own grid layout is a simple
+    # heuristic, not hand-tuned for showcase-grade spacing rules. "standard"
+    # is the honest default until the layout heuristic itself improves
+    # (wider boxes for long labels, real connection routing) rather than
+    # just asking archify to be less strict about a still-rough auto-layout.
+    quality_profile: Literal["standard", "showcase"] = "standard"
+    # Story uses Archify's own focused chapter rail and optional trace
+    # motion. Overview and Full rollup stay still until the reader asks.
+    animation: Literal["none", "trace"] = "none"
+    visual_preset: Literal["classic", "signal-flow", "blueprint", "editorial"] | None = None
+    views: list[GuidedView] = Field(default_factory=list)
+
+    model_config = {"populate_by_name": True}
+
+
+class ArchitectureIR(BaseModel):
+    """A complete document for `archify validate` / `archify deliver`."""
+
+    schema_version: int = 1
+    diagram_type: Literal["architecture"] = "architecture"
+    meta: Meta
+    layout: GridLayout = Field(default_factory=GridLayout)
+    components: list[Component]
+    boundaries: list[Boundary] = Field(default_factory=list)
+    connections: list[Connection]
+    cards: list[Card] = Field(default_factory=list)
+
+    def model_dump_archify(self) -> dict:
+        """Serialize with `from`/`to` un-aliased back to archify's own field
+        names, and with empty-list fields dropped entirely rather than
+        emitted as `[]`.
+
+        Confirmed live (12 Sep 2026) against the real `archify validate`:
+        archify's schema requires `minItems: 1` on array fields like a
+        component's `sources` whenever the key is present at all - pydantic's
+        own `default_factory=list` means every Component always carries
+        `sources: []` unless explicitly stripped, which fails validation with
+        exactly the field populated by default and never actually used.
+        """
+        return _drop_empty_lists(self.model_dump(by_alias=True, exclude_none=True))

graphitect/deliver/archify_repair.py

@@ -0,0 +1,135 @@
+"""Agent-driven layout repair for archify diagrams.
+
+archify_adapter's grid layout is a simple topological-depth heuristic with
+no real connection routing - fine for small graphs, but archify's own
+strict layout validator rejects dense real-world graphs (edges crossing
+unrelated components, labels overlapping boxes - confirmed live against
+FundersAI's real 7,885-node graph). Rather than hand-writing a real graph
+layout/routing algorithm, this asks an LLM to patch the IR's own
+routing/label-position fields (fromSide/toSide/route/via/labelAt/labelDx/
+labelDy/labelSegment) against archify's exact structured diagnostics
+(`archify deliver --json`'s `diagnostics[]`: code, offending connection,
+obstacle, and often a concrete suggested fix), then re-validates - the
+"agent iterates against archify validate feedback" approach flagged as
+future work in plan.md, built as an LLM-backend loop (reusing the same
+Ollama/Anthropic/Gemini backends as Synthesize) so it works from the
+standalone CLI too, not only inside an agent host.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from ..synthesize.llm_backend import LLMBackend
+from .archify_ir import ArchitectureIR
+
+_REPAIR_TOOL_NAME = "emit_repaired_architecture_ir"
+
+
+class RepairUnavailableError(RuntimeError):
+    """The optional LLM layout-repair step could not produce a valid IR."""
+
+_REPAIR_SYSTEM_PROMPT = """\
+You are repairing an archify architecture diagram IR that failed archify's
+own layout validator. You will be given the current IR (JSON) and the exact
+list of validator diagnostics (each with a code, the offending connection or
+label, the obstacle it collides with, and often a suggested fix).
+
+Fix ONLY layout/routing/label-position fields on the existing connections:
+fromSide, toSide, route ("auto"|"straight"|"orthogonal-h"|"orthogonal-v"),
+via (a list of [x, y] waypoints), labelAt ([x, y]), labelDx, labelDy,
+labelSegment. You may also adjust a component's row/col/pos/size if a
+diagnostic specifically calls for moving it. Do NOT change any id, label,
+from/to endpoint, or add/remove any component or connection - every
+diagnostic must be resolved by adjusting geometry, not by altering what the
+diagram says. When a diagnostic's message includes a "Suggested fix" with
+concrete coordinates, prefer using those exact numbers over estimating your
+own.
+
+Return the complete corrected IR as a single JSON object matching the given
+schema exactly - every field from the input IR must still be present unless
+you are deliberately changing it.
+"""
+
+
+def run_deliver_json(
+    bin_cmd: list[str], ir_path: Path, out_path: Path, *, diagram_type: str = "architecture"
+) -> dict:
+    """Runs `archify deliver ... --json` and returns its parsed JSON report
+    regardless of exit code. Confirmed live: archify's own --json output
+    carries structured `diagnostics` (code/subject/evidence/supportedFixes)
+    on failure - the identical shape `archify validate --json` gives - so a
+    single deliver attempt is enough to both try rendering and get repair
+    feedback if it fails, with no separate validate call needed.
+
+    Not underscore-prefixed: also used by archify_adapter.render()'s
+    no-LLM-backend mechanical label-fix retry (_apply_suggested_label_fixes)
+    - both need the exact same structured diagnostics, LLM-driven repair or
+    not.
+    """
+    result = subprocess.run(
+        [*bin_cmd, "deliver", diagram_type, str(ir_path), str(out_path), "--json"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(
+            f"archify deliver --json produced non-JSON output (exit {result.returncode}): "
+            f"stdout={result.stdout[:500]!r} stderr={result.stderr[:500]!r}"
+        ) from exc
+
+
+def repair_and_deliver(
+    ir: ArchitectureIR,
+    bin_cmd: list[str],
+    ir_path: Path,
+    out_path: Path,
+    backend: LLMBackend,
+    *,
+    max_iterations: int = 3,
+) -> dict:
+    """Writes `ir`, attempts `archify deliver`, and if archify's validator
+    rejects it, asks `backend` to patch the IR against the real diagnostics
+    and retries - up to `max_iterations` total delivery attempts. Returns
+    the final JSON report (whatever the last attempt produced, success or
+    failure) - the caller decides what to do with a still-failing report.
+    """
+    if max_iterations < 1:
+        raise ValueError("max_iterations must be >= 1")
+
+    schema = ArchitectureIR.model_json_schema()
+
+    for attempt in range(1, max_iterations + 1):
+        ir_path.write_text(json.dumps(ir.model_dump_archify(), indent=2), encoding="utf-8")
+        report = run_deliver_json(bin_cmd, ir_path, out_path)
+        if report.get("ok"):
+            return report
+
+        diagnostics = report.get("diagnostics") or []
+        if not diagnostics or attempt == max_iterations:
+            return report
+
+        user_prompt = (
+            f"Current IR:\n{json.dumps(ir.model_dump_archify(), indent=2)}\n\n"
+            f"Validator diagnostics ({len(diagnostics)} issue(s)):\n"
+            f"{json.dumps(diagnostics, indent=2)}"
+        )
+        try:
+            patched = backend.complete_json(
+                _REPAIR_SYSTEM_PROMPT, user_prompt, schema, tool_name=_REPAIR_TOOL_NAME
+            )
+            ir = ArchitectureIR.model_validate(patched)
+        except Exception as exc:
+            # Layout repair is opportunistic. A provider quota/outage or an
+            # invalid structured response must leave render() free to use
+            # its deterministic, no-LLM fallback instead of crashing build.
+            raise RepairUnavailableError("optional LLM layout repair is unavailable") from exc
+
+    raise AssertionError("unreachable - loop always returns")  # pragma: no cover