`ai_chunk_semantic`

Split text into semantic chunks using embedding similarity to detect topic boundaries.

Parameters

source_keystringrequired: Context key holding the text to chunk
output_keystringdefault "semantic": Prefix for output context keys
providerstringdefault "openai": Embedding provider: "openai", "ollama", "oauth"
modelstringdefault per provider: Model name (same defaults as ai_embed)
timeoutnumberdefault 120: HTTP request timeout in seconds
sim_windownumberdefault 3: Cross-similarity window size (odd, >= 3)
sg_windownumberdefault 11: Savitzky-Golay smoothing window (odd)
poly_ordernumberdefault 3: Savitzky-Golay polynomial order
thresholdnumberdefault 0.5: Percentile of candidate boundary strengths kept as splits (0.0-1.0); higher admits more splits
min_distancenumberdefault 2: Minimum block gap between split points

Provider auth parameters

Same as ai_embed — api_key, base_url, ollama_host, token_url, client_id, client_secret, scope with identical environment variable fallbacks.

Context Output

Key	Type	Description
`{output_key}`	array	Array of semantic chunk strings
`{output_key}_count`	number	Number of chunks
`{output_key}_success`	boolean	`true` on success

Algorithm

Split text into sentences (boundary detection on .!? followed by whitespace)
Embed all sentences using the selected provider
Compute windowed cross-similarity (cosine distance between adjacent embedding windows)
Apply Savitzky-Golay smoothing to the distance curve
Detect local minima (topic boundaries) using first/second derivatives
Filter split points by percentile threshold and minimum distance
Group sentences at boundaries into chunks

Tuning

threshold is a percentile of candidate boundary strengths, not an absolute similarity cutoff. A split is kept when its value falls at or below the percentile, so a lower percentile admits fewer boundaries:

Lower threshold (e.g. 0.3) → fewer splits, larger chunks
Higher threshold (e.g. 0.7) → more splits, smaller chunks
Larger sg_window → smoother curve, fewer but more confident splits
Smaller min_distance → allow splits closer together

Examples

Semantic chunking with OpenAI

flow:step("chunk", nodes.ai_chunk_semantic({
    source_key = "document",
    output_key = "topics",
    provider = "openai",
    model = "text-embedding-3-small",
    threshold = 0.5
}))

Semantic chunking with Ollama (local)

flow:step("chunk", nodes.ai_chunk_semantic({
    source_key = "document",
    output_key = "topics",
    provider = "ollama",
    model = "nomic-embed-text"
}))

Fine-tuned splitting

flow:step("chunk", nodes.ai_chunk_semantic({
    source_key = "article",
    output_key = "sections",
    provider = "openai",
    threshold = 0.3,
    min_distance = 3,
    sg_window = 15
}))