Core

Core module for gllm-rag.

This module contains the foundational components for building RAG strategies.

CompositeStrategy()

Bases: Strategy

Abstract base class for composite strategies.

CompositeStrategy extends Strategy for strategies that compose multiple sub-strategies or pipelines into a single pipeline.

Subclasses compose branches as Strategy | Pipeline slots declared via uses(). _build_pipeline() is sealed: calls _validate_branches() then _build_composite_pipeline().

__init_subclass__(**kwargs)

Enforce sealed _build_pipeline by raising TypeError on override.

This runs after the metaclass creates the subclass. If the subclass declared _build_pipeline in its own dict, a TypeError is raised at class-definition time so the mistake surfaces immediately.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Keyword arguments passed to the superclass.	{}

Raises:

Type	Description
TypeError	If the subclass attempts to override _build_pipeline.

Strategy()

Bases: ABC

Abstract base class for all RAG strategies.

Strategy defines the interface for RAG strategies with auto-generated builder methods for optional slots marked with uses().

Initialize strategy with empty slot values and no cached pipeline.

__getattr__(name)

Provide typed fallback for metaclass-generated with_() methods.

This fallback is primarily for static analysis tools that cannot infer methods generated dynamically by StrategyMeta. At runtime, valid with_ methods already exist on the class and will be resolved before getattr.

Parameters:

Name	Type	Description	Default
name	str	The missing attribute name.	required

Returns:

Type	Description
Callable[[Any], Self]	Callable[[Any], Self]: Bound builder method for the requested slot.

Raises:

Type	Description
AttributeError	If the attribute is not a known slot builder.

arun(question, top_k=5, **kwargs) async

Async entry point.

Parameters:

Name	Type	Description	Default
question	str	The user query.	required
top_k	int	Number of top results to retrieve. Defaults to 5.	5
**kwargs		Additional retrieval parameters. Supported: query_filter, threshold.	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Final state dict with response.

as_tool(name='', description='')

Return a tool representation of this strategy.

Parameters:

Name	Type	Description	Default
name	str	Tool name. Defaults to class name.	''
description	str	Tool description. Defaults to class docstring.	''

Returns:

Name	Type	Description
Any	Any	Tool representation via pipeline.as_tool().

build()

Materialize the pipeline.

Idempotent - returns cached instance if already built.

Returns:

Name	Type	Description
Any	Any	Pipeline instance.

Raises:

Type	Description
NotImplementedError	If _build_pipeline() not implemented by subclass.

describe() classmethod

Return strategy description.

Returns:

Name	Type	Description
str	str	Description with strategy name, slot names/types, and slot descriptions.

run(question, top_k=5, **kwargs)

Synchronous entry point.

Parameters:

Name	Type	Description	Default
question	str	The user query.	required
top_k	int	Number of top results to retrieve. Defaults to 5.	5
**kwargs	Any	Additional retrieval parameters. Supported: query_filter, threshold.	{}

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Final state dict with response.

Raises:

Type	Description
RuntimeError	If called from within a running event loop.

StrategyMeta

Bases: ABCMeta

Metaclass for Strategy that auto-generates builder methods.

Combines with ABCMeta to preserve abstract class functionality while auto-generating .with_() builder methods for slots marked with uses().

__new__(mcs, name, bases, namespace)

Create new Strategy subclass with auto-generated builder methods.

Parameters:

Name	Type	Description	Default
mcs	StrategyMeta	The metaclass.	required
name	str	Name of the class being created.	required
bases	tuple[type, ...]	Base classes.	required
namespace	dict[str, Any]	Class namespace dictionary.	required

Returns:

Name	Type	Description
StrategyMeta	StrategyMeta	The newly created class with generated builder methods.

StrategyState

Bases: RAGStateModel

Extends RAGStateModel with gllm-rag-specific state keys.

This Pydantic model is used as the Pipeline state_type for all strategies. Inherited from RAGStateModel: user_query, queries, retrieval_params, chunks, history, context, response_synthesis_bundle, response, references, event_emitter.

Attributes:

Name	Type	Description
query_filter	Any | None	Query filter for the retriever, supporting datastore filters. Used by retrieval steps to apply metadata filters. Defaults to None.
retrieval_decision	str | None	CRAG routing decision. One of: 1. "relevant": Query is relevant to corpus 2. "irrelevant": Query is irrelevant to corpus 3. "ambiguous": Query relevance is ambiguous Defaults to None when not yet determined.
filtered_chunks	list[Chunk] | None	CRAG-internal chunks surviving relevance filter. Used and consumed by the ambiguous branch of CRAG. Defaults to None.
routed_branch	str | None	RoutedStrategy-selected branch name. Defaults to None when routing has not been resolved.