ZerdaZerda

QueryPatternAnalyzer

On this page

Module: chunks.query_pattern_analyzer
Import: from zerda.chunks import QueryPatternAnalyzer

Table of Contents

Purpose

QueryPatternAnalyzer inspects a set of sample queries and selects the most appropriate chunking strategy (as a ChunkMode) for the document being processed.

It enables query-aware chunking: instead of fixing a strategy at configuration time, you provide representative queries and let the analyzer pick the right mode.

Built-In Strategies

Strategy NameChunkModeBest For
"faq"STRUCTURALQ&A documents, FAQ pages
"documentation"HYBRIDTechnical documentation, API references
"technical"SEMANTICResearch papers, technical reports
"narrative"CONTEXTUALBooks, blog posts, stories
"general"AUTOMixed-use / unknown document type

Constructor

Python · 3 lines
QueryPatternAnalyzer(
    config: Optional[ChunkConfig] = None,
)
ParameterTypeDefaultDescription
configChunkConfig | NoneNoneReads default_query_pattern as fallback strategy name

Public Methods

analyze

Python · 5 lines
def analyze(
    self,
    queries: List[str],
    text_sample: Optional[str] = None,
) -> ChunkMode

Analyzes the provided queries (and optionally a text sample) to select the best ChunkMode.

Parameters:

NameTypeRequiredDescription
queriesList[str]YesRepresentative sample queries for the document
text_samplestr | NoneNoOptional excerpt of the document (first 1000 chars) — improves structural hints

Returns: ChunkMode enum value.

Returns ChunkMode.AUTO when queries is empty.

get_strategy

Python
def get_strategy(self, strategy_name: str) -> Optional[ChunkingStrategy]

Returns the ChunkingStrategy dataclass for a given strategy name, or None if not found.

list_strategies

Python
def list_strategies(self) -> List[str]

Returns names of all registered strategies: ["faq", "documentation", "technical", "narrative", "general"].

Strategy Selection Logic

code · 8 lines
1. Normalize queries to lowercase.
2. Score each strategy by keyword match:
   - For each query, count keyword hits from strategy.query_patterns list.
   - Sum hits across all queries → raw_score per strategy.
3. Select strategy with highest raw_score.
4. Tie-break: use config.default_query_pattern.
5. No matches: return config.default_query_pattern strategy.
6. Return strategy.chunk_mode.

Strategy Keywords

StrategySample Keywords Matched
faq"how", "what", "why", "when", "which", "is", "are", "does", "can", "?"
documentation"install", "setup", "configure", "api", "reference", "function", "method", "class", "parameter", "usage"
technical"algorithm", "model", "training", "accuracy", "performance", "implementation", "architecture", "neural", "deep learning"
narrative"story", "chapter", "character", "plot", "scene", "describe", "happened", "said"
general(catches all; low weight default)

ChunkingStrategy Dataclass

Python · 7 lines
@dataclass
class ChunkingStrategy:
    name: str
    chunk_mode: ChunkMode
    description: str
    query_patterns: List[str]
    recommended_config: Dict[str, Any]
FieldDescription
nameStrategy identifier string
chunk_modeAssociated ChunkMode enum value
descriptionHuman-readable description
query_patternsKeyword list used for scoring
recommended_configSuggested ChunkConfig kwargs for this strategy

STRATEGIES Constant

Python · 4 lines
from zerda.chunks.query_pattern_analyzer import STRATEGIES

print(STRATEGIES.keys())
# dict_keys(['faq', 'documentation', 'technical', 'narrative', 'general'])

Examples

Basic Usage

Python · 9 lines
from zerda.chunks import QueryPatternAnalyzer

analyzer = QueryPatternAnalyzer()
mode = analyzer.analyze_queries([
    "How do I install this package?",
    "What are the API parameters?",
    "How to configure the server?",
])
print(mode)   # ChunkMode.HYBRID  (documentation pattern)

With Text Sample

Python · 5 lines
mode = analyzer.analyze_queries(
    queries=["What is the gradient descent algorithm?", "Explain backpropagation."],
    text_sample=document_text[:1000],
)
print(mode)   # ChunkMode.SEMANTIC  (technical pattern)

Listing Strategies

Python · 7 lines
analyzer = QueryPatternAnalyzer()
print(analyzer.list_strategies())
# ['faq', 'documentation', 'technical', 'narrative', 'general']

strategy = analyzer.get_strategy("technical")
print(strategy.chunk_mode)           # ChunkMode.SEMANTIC
print(strategy.recommended_config)   # {"use_semantic_chunking": True, ...}

Related pages