graphitect 0.2.0__py3-none-any.whl

graphitect/ground/__init__.py

@@ -0,0 +1,5 @@
+"""Three grounding sources, picked per repo - plan.md §02."""
+
+from . import describe_source, fullread_source, graphify_source
+
+__all__ = ["describe_source", "fullread_source", "graphify_source"]

graphitect/ground/describe_source.py

@@ -0,0 +1,27 @@
+"""Grounding via a plain-language description - fastest, no repo access
+needed, weakest evidence (plan.md §02). Everything from this source is
+inherently `inferred` (technically `user`-sourced but unverified against
+code), since nothing here is checked against real code.
+"""
+
+from __future__ import annotations
+
+from ..models import Claim, Confidence, Evidence
+
+
+def ground(description: str) -> list[Claim]:
+    """Wrap the user's own description as a single unverified claim per
+    paragraph. A real implementation would still run this through an LLM to
+    extract structured claims; this stub keeps the boundary explicit: nothing
+    from Describe-it is ever `confirmed` by construction, since there's
+    nothing to check it against.
+    """
+    paragraphs = [p.strip() for p in description.split("\n\n") if p.strip()]
+    return [
+        Claim(
+            text=p,
+            confidence=Confidence.INFERRED,
+            cites=[Evidence(source="user", note="Describe-it mode - not verified against code")],
+        )
+        for p in paragraphs
+    ]

graphitect/ground/fullread_source.py

@@ -0,0 +1,56 @@
+"""Grounding via a full LLM read of the repo - README, git log, commit
+messages, existing docs (plan.md §02). Where rationale actually comes from:
+Graphify can tell you two modules are connected, not why Redis sits between
+them.
+
+This is the one grounding source that fundamentally needs an LLM, which is
+also the one place the skill and CLI surfaces genuinely diverge in
+capability (plan.md §05):
+  - as a skill, the host IS the LLM - `read_fn` dispatches the host's own
+    subagents (e.g. Claude Code's Agent tool), same pattern Graphify itself
+    uses for semantic extraction when no GEMINI_API_KEY is set.
+  - standalone, `read_fn` must be backed by the caller's own
+    ANTHROPIC_API_KEY / GEMINI_API_KEY - there's no host LLM to borrow.
+
+Nothing here performs the read itself; ReadFn is the seam both surfaces
+implement differently while everything downstream (rubric, questions,
+GroundedUnderstanding) stays identical.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from ..models import Claim
+
+
+class ReadFn(Protocol):
+    """One full-read pass over a repo, returning extracted claims.
+
+    Implementations differ by surface (host subagent dispatch vs. a direct
+    API call) but must return the same shape: raw claims with confidence
+    already assessed against what was actually found, ready for the rubric
+    in graphitect.synthesize.rubric to mine further or queue a question.
+    """
+
+    def __call__(self, repo_path: Path, sources: list[Path]) -> list[Claim]: ...
+
+
+def default_sources(repo_path: Path) -> list[Path]:
+    """README, CHANGELOG, and any docs/specs - the rubric's own search order
+    (plan.md §03), collected once so both a skill subagent and a standalone
+    LLM call read the same files.
+    """
+    candidates = [
+        repo_path / "README.md",
+        repo_path / "CHANGELOG.md",
+    ]
+    docs_dir = repo_path / "docs"
+    if docs_dir.is_dir():
+        candidates.extend(sorted(docs_dir.rglob("*.md")))
+    return [p for p in candidates if p.exists()]
+
+
+def ground(repo_path: Path, read_fn: ReadFn) -> list[Claim]:
+    return read_fn(repo_path, default_sources(repo_path))

graphitect/ground/graphify_source.py

@@ -0,0 +1,107 @@
+"""Grounding via Graphify's structure graph - most accurate, cheapest per
+file, works offline (plan.md §02). Reuses an existing graphify-out/graph.json
+if present; otherwise shells out to run graphify first.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def ground(
+    repo_path: Path,
+    *,
+    graphify_bin: str | None = None,
+    force_rebuild: bool = False,
+    output_dir: Path | None = None,
+) -> dict:
+    """Return {"nodes": [...], "edges": [...], "communities": {...}} from
+    graphify's own graph.json export, running graphify first if needed.
+
+    Never overwrites an existing graphify-out/ blindly - always prefers
+    `graphify <path> --update` over a fresh build when a graph already
+    exists, learned the hard way running Phase 1 against a live repo
+    that already had its own Graphify setup (plan.md §06, Phase 1 risk).
+    """
+    graph_output = output_dir.resolve() if output_dir else repo_path / "graphify-out"
+    graph_json = graph_output / "graph.json"
+    bundled_spec = None
+    if graphify_bin:
+        bin_cmd = [graphify_bin]
+    elif (bundled_spec := importlib.util.find_spec("graphify")) is not None:
+        # Graphify ships inside the Graphitect wheel. Use the current Python
+        # interpreter so no separate `graphify` installation or PATH entry is
+        # required.
+        bin_cmd = [sys.executable, "-m", "graphify"]
+    else:
+        on_path = shutil.which("graphify")
+        bin_cmd = [on_path] if on_path else None
+
+    if not graph_json.exists() or force_rebuild:
+        if not bin_cmd:
+            raise FileNotFoundError(
+                "bundled Graphify runtime is missing and no existing "
+                "graphify-out/graph.json can be reused"
+            )
+        # Graphitect uses Graphify for deterministic source structure. README
+        # and docs are read by Graphitect's own optional LLM pass, so Graphify
+        # must never require a second API key just to build the mandatory
+        # no-LLM diagram.
+        cmd = [*bin_cmd, str(repo_path), "--code-only"]
+        if graph_json.exists():
+            cmd.append("--update")  # incremental, safe - never a blind full rebuild
+        env = os.environ.copy()
+        env["GRAPHIFY_EMBEDDED"] = "1"
+        if bundled_spec is not None and getattr(bundled_spec, "origin", None):
+            # Editable/source installs may only expose Graphify because the
+            # checkout is the current directory. The analyzer runs with the
+            # target repository as cwd, so preserve the discovered package
+            # root for that child process. A normal wheel install already has
+            # it on sys.path; this is harmless there.
+            package_root = str(Path(bundled_spec.origin).resolve().parent.parent)
+            existing_pythonpath = env.get("PYTHONPATH")
+            env["PYTHONPATH"] = (
+                package_root + os.pathsep + existing_pythonpath
+                if existing_pythonpath
+                else package_root
+            )
+        if output_dir:
+            # The product-level `build` command uses a temporary Graphify
+            # directory so the report really is its only persistent output.
+            env["GRAPHIFY_OUT"] = str(graph_output)
+        subprocess.run(cmd, check=True, cwd=repo_path, env=env)
+
+    data = json.loads(graph_json.read_text(encoding="utf-8"))
+    return {
+        "nodes": data.get("nodes", []),
+        "edges": data.get("links", data.get("edges", [])),  # graph.json uses networkx "links"
+        "communities": _labels_by_community(data),
+        # Plain-language community names, if a real graphify run produced
+        # them (graphify-out/.graphify_labels.json). Used to name aggregated
+        # diagram boxes ("MF Catalog Review Triage") instead of a bare
+        # "Community 42" when a large graph gets collapsed to community
+        # level - see archify_adapter._aggregate_by_community.
+        "community_labels": _read_community_labels(graph_output),
+    }
+
+
+def _labels_by_community(graph_json_data: dict) -> dict[int, list[str]]:
+    by_community: dict[int, list[str]] = {}
+    for node in graph_json_data.get("nodes", []):
+        cid = node.get("community")
+        if cid is not None:
+            by_community.setdefault(cid, []).append(node["id"])
+    return by_community
+
+
+def _read_community_labels(graph_output: Path) -> dict[str, str]:
+    labels_path = graph_output / ".graphify_labels.json"
+    if not labels_path.exists():
+        return {}
+    return json.loads(labels_path.read_text(encoding="utf-8"))

graphitect/models.py

@@ -0,0 +1,118 @@
+"""Shared model for graphitect - see plan.md sections 03/04.
+
+One internal structure produced by Synthesize, mapped two ways downstream:
+into archify's own typed IR for the diagram, and into a sourced doc outline
+for the write-up. Every claim traces to evidence or is explicitly labeled a
+guess - never presented as confident prose either way.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Confidence(str, Enum):
+    CONFIRMED = "confirmed"  # direct code fact, or the author said so
+    INFERRED = "inferred"    # plausible - must be labeled as such
+
+
+class Evidence(BaseModel):
+    source: Literal["code", "readme", "git_log", "docs", "user"]
+    file: str | None = None
+    line: int | None = None
+    note: str | None = None  # e.g. commit message excerpt, or the user's own answer
+
+
+class Claim(BaseModel):
+    text: str  # "chose FastAPI for async support"
+    confidence: Confidence
+    cites: list[Evidence] = Field(default_factory=list)
+    # "descriptive" = a fact about a past decision, askable via the rubric.
+    # "prescriptive" = the tool's own recommendation/suggestion, never askable -
+    # asking "did you really mean this suggestion" doesn't make sense (plan.md §03).
+    kind: Literal["descriptive", "prescriptive"] = "descriptive"
+
+
+class Tradeoff(BaseModel):
+    """A real pros/cons comparison for one architectural/technical decision -
+    what "Tradeoffs & alternatives considered" is actually for, beyond a
+    flat claim bullet (Naman's request, 12 Sep 2026, for a more in-depth,
+    explanatory doc). `decision`/`pros`/`cons` are full Claims - confidence
+    tag + citations, exactly like anything else in the doc - so a table row
+    can never quietly carry an unverified assertion the rest of the doc
+    wouldn't allow; engine.synthesize() re-verifies all three the same way
+    it verifies section.claims. `decision` may restate or elaborate a claim
+    already present in this section's own `claims` list - the flat list is
+    the quick-scan version, this is the detailed one.
+
+    Not currently wired into the interactive Q&A/pending-question flow
+    (scoped out deliberately - see plan.md): an inferred, unresolved
+    tradeoff still displays honestly labeled, it just isn't independently
+    askable via --answers the way a flat section.claims entry is.
+    """
+
+    decision: Claim
+    alternatives_considered: list[str] = Field(default_factory=list)
+    pros: list[Claim] = Field(default_factory=list)
+    cons: list[Claim] = Field(default_factory=list)
+
+
+class DesignDocSection(BaseModel):
+    heading: str  # "Technology choices"
+    claims: list[Claim] = Field(default_factory=list)
+    related_node_ids: list[str] = Field(default_factory=list)  # cross-links into the archify IR
+    tradeoffs: list[Tradeoff] = Field(default_factory=list)
+
+
+class QuestionOption(BaseModel):
+    label: str  # short label, e.g. "Type-hints + Rich dashboards"
+    becomes_text: str  # exact confirmed claim text if this option is chosen
+
+
+class RationaleQuestion(BaseModel):
+    """One askable gap, per plan.md §03.
+
+    Only descriptive claims with zero evidence from the mining rubric AND
+    load-bearing enough to matter (landed in Technology Choices or Tradeoffs)
+    become a RationaleQuestion. Renders identically whether the surface is an
+    agent host's structured-question tool or a bare terminal prompt - see
+    graphitect.synthesize.questions.
+    """
+
+    claim_id: str
+    question: str
+    options: list[QuestionOption]  # options[0] is always Synthesize's own best guess
+    allow_free_text: bool = True
+
+
+class GroundedUnderstanding(BaseModel):
+    diagram_kind: Literal["architecture", "workflow", "sequence", "dataflow", "lifecycle"]
+    nodes: list[dict] = Field(default_factory=list)  # mapped into archify's own node schema
+    edges: list[dict] = Field(default_factory=list)
+    doc: list[DesignDocSection] = Field(default_factory=list)
+    pending_questions: list[RationaleQuestion] = Field(default_factory=list)
+    # Plain-language Graphify community names (community id -> label), when
+    # grounding came from a real graphify run that produced them. Used to
+    # name aggregated diagram boxes when there are too many raw nodes for a
+    # readable diagram - see archify_adapter._aggregate_by_community. Naman's
+    # point (12 Sep 2026): a large codebase's full graph either won't render
+    # or renders unreadably, so the diagram falls back to Graphify's own
+    # community-detection output instead of an LLM re-inventing a summary.
+    community_labels: dict[str, str] = Field(default_factory=dict)
+
+
+class AgentNarrative(BaseModel):
+    """The only portion an installed agent may author.
+
+    Graphitect joins this with deterministic Graphify structure during
+    ``graphitect agent compile``. The schema deliberately excludes nodes and
+    edges, so a host model cannot alter the diagram it explains.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal[1] = 1
+    doc: list[DesignDocSection] = Field(default_factory=list)

graphitect/skill/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: graphitect
+description: Generate an evidence-grounded, self-contained interactive architecture report for an existing repository. Use for codebase diagrams, architecture walkthroughs, technical-choice or trade-off explanations, and interview-preparation artifacts; do not use for greenfield architecture proposals.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Graphitect
+
+Use Graphitect for a repository the user already has when they want a codebase
+diagram, project walkthrough, technical-choice explanation, or
+interview-preparation artifact.
+
+Do not use it to invent an architecture for a project that does not yet exist.
+
+## Installed-agent mode — no separate API key
+
+When this skill runs inside Codex, Claude Code, or another agent host, use the
+host's selected model for Section 2. Graphitect makes no LLM network call in
+this mode.
+
+```bash
+graphitect agent prepare <path> -o .graphitect-agent
+```
+
+Read `.graphitect-agent/agent-context.md`,
+`.graphitect-agent/narrative.schema.json`, and any source files needed to
+check a claim. Edit only `.graphitect-agent/narrative.json` with detailed
+`doc` sections for the project explanation, technical choices, mechanisms,
+and trade-offs.
+
+- Graphitect owns the diagram: never add, remove, or rename nodes or edges.
+- Mark a claim `confirmed` only with real evidence. A code citation needs a
+  repository-relative `file` and a `note` that is a full phrase from that file.
+- Do not use `user` evidence in `narrative.json`; only `--answers` may add a
+  direct user answer to the final report.
+- Mark interpretation, unstated rationale, and recommendations as `inferred`.
+- Use only real `related_node_ids` from the prepared grounding.
+
+```bash
+graphitect agent compile .graphitect-agent --title <project> -o <project>-graphitect.html
+```
+
+This validates host-written citations and writes the single self-contained
+HTML artifact. If `.graphitect-agent/graphitect-questions.json` contains
+unanswered entries, ask the user, fill each `answer`, then rerun `agent
+compile --answers` with that same file. The first compile is still useful:
+unresolved claims remain honestly labeled as inferred.
+
+Only use `--no-diagram` when the user explicitly opts out. A diagram-rendering
+failure is a command failure because Section 1 is mandatory by default.
+
+## Standalone CLI mode
+
+```bash
+graphitect build <path> -o <project>-graphitect.html
+```
+
+This single command runs the bundled Graphify analyzer, renders with the
+bundled Archify viewer, and writes one HTML file. Do not install or invoke
+Graphify or Archify separately.
+
+Outside an agent host, an API key is optional. With `ANTHROPIC_API_KEY`,
+`GEMINI_API_KEY`, `GOOGLE_API_KEY`, or `OLLAMA_API_KEY`, Section 2 includes
+the detailed project explanation. Without a key, Section 1 still renders and
+Section 2 honestly states that the narrative was skipped.
+
+## Verify
+
+Confirm that the output contains both named sections and that the embedded
+Archify viewer opens, pans/zooms, switches theme, exposes per-block hover
+details, and exposes its route and guided-view controls.
+
+Keep claims labeled as confirmed or inferred; never invent a citation,
+technology rationale, runtime trace, or provider relationship. A workflow
+arrow is a direct static Graphify relationship. A sequence appears only when
+Graphify observed consecutive `calls` or `invokes` edges; it is not runtime
+telemetry. Preserve the source symbol in hover details when a legacy function
+name could be mistaken for provider topology.

graphitect/skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Graphitect"
+  short_description: "Generate a grounded interactive codebase architecture report"
+  default_prompt: "Use Graphitect's host-model workflow to create an evidence-grounded, self-contained architecture report for this repository without a separate API key."

graphitect/synthesize/__init__.py

@@ -0,0 +1,5 @@
+"""The rationale-mining rubric and its Q&A follow-up - plan.md §03."""
+
+from . import engine, llm_backend, questions, rubric
+
+__all__ = ["engine", "llm_backend", "questions", "rubric"]