# How to Use Graphify's Semantic Deep Mode for Extraction

> Unlock hidden insights with Graphify's semantic deep mode. Infer implicit relationships and design rationale beyond static analysis for advanced extraction.

- Repository: [Graphify Labs/graphify](https://github.com/Graphify-Labs/graphify)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/ingest.py) and [`graphify/llm.py`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/ingest.py).

### Basic CLI Usage

Activate deep mode on any documentation or source folder:

```bash
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:

```bash
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:

```bash
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:

```python
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`](https://github.com/Graphify-Labs/graphify/blob/main/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:

```bash

# 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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/ingest.py) for pipeline orchestration and [`graphify/llm.py`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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`](https://github.com/Graphify-Labs/graphify/blob/main/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.