POC: Graphify backend with FastAPI semantic overlay

[shaggitza]

Goal

Evaluate Graphify (Graphify-Labs/graphify; PyPI package graphifyy) as an opt-in code-graph backend. Graphify should extract the generic code graph; this project should overlay FastAPI/custom-surface discovery, dependency reachability, confidence and effect semantics.

Architecture hypothesis

1. Build isolated target and baseline graph.json snapshots offline from code only.
2. Parse Graphify nodes/edges into an internal versioned graph adapter.
3. Seed the graph with established/conditional FastAPI handlers from secure discovery.
4. Traverse only evidence-bearing call/import/inheritance/reference edges.
5. Apply our framework surface, DI, lifecycle and state/effect contracts above the generic graph.
6. Preserve Graphify EXTRACTED/INFERRED/AMBIGUOUS provenance separately from our HIGH/MEDIUM/LOW confidence.

Safety and reproducibility

• Explicit --graphify; mypy remains default; no silent fallback.
• Pin Graphify package/version and graph schema; reject unsupported schemas.
• External command uses argv arrays, no shell interpolation.
• Code-only local extraction: no semantic LLM/backend, docs/media, MCP/HTTP server, query logging, hooks, or repo mutation.
• Separate target/baseline output directories with immutable snapshot hashes.
• Never treat communities, natural-language query results, or inferred similarity as blast-radius evidence.

POC gates

• Document exact graph.json schema, node IDs, edge directions and source ranges
• Verify Python call/import/inheritance resolution, aliases, methods, deletion and cross-file behavior
• Implement read-only Graphify adapter and explicit CLI failure modes
• Overlay FastAPI route/DI semantics without modifying Graphify output
• Run controlled fixtures and frozen verification corpus
• Report exact/normalized HIGH+MEDIUM and LOW diagnostics, latency/RSS, tool failures and graph size
• Require candidate gain, bounded FP, no primary regression and acceptable runtime
• Record BUILD/ADOPT/HYBRID/STOP decision

Non-goals

Graphify communities and broad knowledge-graph proximity are not endpoint reachability. This POC must not replace source-backed route discovery or promote inferred edges without calibration.

Reference: https://github.com/Graphify-Labs/graphify

[shaggitza]

Initial source review confirms Graphify is suitable only for a bounded POC, not yet as a trusted compiler API. The documented integration boundary is the pinned graphify CLI plus graphify-out/graph.json; code extraction is local tree-sitter, while docs/media/semantic passes must be disabled. Before implementation we must inspect and freeze the exact graph schema at an immutable release, verify source spans/IDs/edge directions, run network-denied deterministic fixtures, and preserve Graphify EXTRACTED/INFERRED/AMBIGUOUS provenance separately from detector confidence. Current observed upstream release during research: v0.9.15 / package graphifyy; do not adopt that pin until schema fixtures and package/tag correspondence are independently verified.

[shaggitza]

Merged the independently reviewed offline-only snapshot importer in PR #306. CI passed across Python 3.10–3.12, lint/type checks, minimum FastAPI compatibility, and package build. Graphify was not installed or executed, and no dependency, CLI, or default-analyzer wiring was added. #110 remains open: isolated invocation, FastAPI overlay, frozen-corpus calibration, performance measurement, and BUILD/ADOPT/HYBRID/STOP adjudication remain gated on the trusted #101 sandbox.