How to Use Graphify's Semantic Deep Mode for Extraction

Graphify's semantic deep mode adds an LLM-driven semantic pass to the deterministic AST extraction, inferring implicit relationships and design rationale that static analysis alone cannot capture.

The Graphify-Labs/graphify repository provides a knowledge graph extraction pipeline that supports two distinct modes of operation. While standard AST extraction parses code structure deterministically, the semantic deep mode for extraction leverages large language models to identify cross-file concepts, implied design patterns, and high-level domain knowledge. This guide covers the implementation details, configuration options, and practical usage based on the source code in graphify/ingest.py and graphify/llm.py.

What Semantic Deep Mode Does

Semantic deep mode transforms the extraction pipeline from a single-pass parser into a two-stage hybrid system. According to the repository's implementation, this mode sends document chunks to an LLM using an extended system prompt that requests richer semantic relationships.

The Two-Phase Pipeline

The deep mode operates through distinct phases defined in the codebase:

1. AST Extraction – A deterministic pass using tree-sitter parsing that builds a code-only graph. This step requires no LLM and runs in parallel controlled by GRAPHIFY_MAX_WORKERS.
2. Semantic Extraction – An LLM-driven pass implemented in graphify/llm.py that processes each document-type chunk sequentially. The prompt includes a "deep" flag that instructs the model to output inferred edges beyond explicit code relationships.

Merging Explicit and Inferred Edges

After both passes complete, graphify/ingest.py merges the results into a unified graph structure. This merge logic preserves explicit (EXTRACTED) edges from the AST while adding inferred (INFERRED) edges discovered during the semantic pass. The resulting graph contains relationships that static analysis cannot detect, such as "semantically similar to" links or rationale nodes explaining design decisions.

How to Enable Deep Mode via CLI

The command-line interface provides direct access to semantic deep mode through the --mode flag. All deep mode invocations route through the extraction pipeline in graphify/ingest.py.

Basic CLI Usage

Activate deep mode on any documentation or source folder:

graphify extract ./docs --mode deep

This command triggers both the AST parsing and the LLM semantic pass, producing a graph that combines structural and semantic relationships.

Configuring Token Budgets and Limits

Deep mode consumes significantly more tokens than AST-only extraction because each chunk requires an LLM call. The repository provides two mechanisms to control resource usage:

Configuration	Type	Effect
--token-budget N	CLI flag	Limits the max output tokens the LLM may emit per chunk
GRAPHIFY_MAX_OUTPUT_TOKENS	Environment variable	Raises the hard output-token ceiling for dense corpora
GRAPHIFY_MAX_WORKERS	Environment variable	Controls parallel AST parsing (note: deep mode still runs LLM calls sequentially per chunk)

For local LLM deployments with constrained memory:

GRAPHIFY_MAX_OUTPUT_TOKENS=16384 graphify extract ./docs \
    --mode deep --token-budget 4000

Incremental Updates with Deep Mode

When working with evolving codebases, use the --update flag to re-extract only changed files. Deep mode works on the delta without rebuilding the entire graph:

graphify update ./src --mode deep

This is equivalent to graphify extract ./src --mode deep --update and preserves existing AST data while re-running the semantic pass on modified content.

Python API Implementation

Embed Graphify directly in Python scripts using the GraphifyExtractor class:

from graphify.ingest import GraphifyExtractor

# Initialise the extractor (uses env-vars for backend/config)

extractor = GraphifyExtractor(
    corpus_path="./docs",
    mode="deep",                # Enables semantic deep pass

    token_budget=5000,
)

graph = extractor.run()
graph.save("graphify-out/graph.json")

The mode="deep" parameter triggers the extended system prompt in graphify/llm.py, ensuring the LLM returns the richer relationship set used for downstream analysis.

Combining with Community Detection

Deep mode extraction pairs with community labeling to organize inferred concepts. First extract with deep mode, then label communities using the same LLM backend:

# Extract with deep mode

graphify extract ./src --mode deep

# Optional: Name the communities using an LLM

graphify label ./src --backend openai --model gpt-4o

The benchmarks documented in BENCHMARKS.md show that enabling deep mode significantly improves QA accuracy and recall compared to AST-only extraction, though it requires more processing time and token consumption.

Summary

• Semantic deep mode in Graphify adds an LLM-driven pass to the standard AST extraction pipeline, enabling extraction of implicit relationships and design rationale.
• Implementation relies on graphify/ingest.py for pipeline orchestration and graphify/llm.py for the extended "deep" system prompt that generates inferred edges.
• Configuration uses --mode deep and --token-budget flags, plus GRAPHIFY_MAX_OUTPUT_TOKENS environment variable to manage resource constraints.
• Performance characteristics include sequential LLM processing per chunk (despite parallel AST parsing) and higher recall metrics documented in the repository benchmarks.
• Integration works with incremental updates (--update) and community detection workflows for complete knowledge graph construction.

Frequently Asked Questions

What is the difference between standard extraction and semantic deep mode?

Standard extraction uses only tree-sitter AST parsing to build code relationships, while semantic deep mode adds a second pass that sends document chunks to an LLM. According to the source code in graphify/llm.py, the deep mode uses an extended system prompt that instructs the model to identify inferred relationships, design rationale, and cross-file concepts that static analysis cannot detect.

How do I prevent deep mode from exceeding my LLM token limits?

Set the GRAPHIFY_MAX_OUTPUT_TOKENS environment variable to define a hard ceiling, and use the --token-budget CLI flag to limit per-chunk output. For example, GRAPHIFY_MAX_OUTPUT_TOKENS=16384 combined with --token-budget 4000 ensures even dense documentation stays within model constraints. The repository notes that deep mode runs LLM calls sequentially per chunk, which helps manage rate limits even if AST parsing runs in parallel.

Can I update an existing graph with new deep mode extractions without rebuilding everything?

Yes. Use the graphify update command with --mode deep or the equivalent graphify extract ./src --mode deep --update. This functionality, implemented in graphify/ingest.py, re-extracts only changed files and re-runs the semantic pass on the delta while preserving the existing AST graph structure.

Why does deep mode improve QA accuracy according to the benchmarks?

The BENCHMARKS.md file documents that deep mode discovers relationships unavailable to AST-only parsing, such as implied design patterns and semantic similarities across files. By merging explicit (EXTRACTED) edges from the AST with inferred (INFERRED) edges from the LLM, the resulting knowledge graph contains richer contextual information that improves downstream question-answering tasks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}