# fitz_ai/engines/fitz_rag/retrieval/steps/__init__.py
"""
Retrieval Steps - Standard composable building blocks.

These steps are always the same Python logic. Users orchestrate them
via YAML config by specifying which steps to run and their parameters.

Pipeline example: vector_search(k=25) → rerank(k=10) → threshold(τ) → limit(k=5)

Each step:
- Takes a query + list of chunks (or nothing for initial step)
- Returns a list of chunks
- Is stateless and reusable

Note: VectorSearchStep has built-in multi-query expansion and keyword filtering.
These features are always active when dependencies are available - no plugin
configuration needed. Sophistication is baked in.

Usage:
    from fitz_ai.engines.fitz_rag.retrieval.steps import (
        VectorSearchStep,
        RerankStep,
        ThresholdStep,
        LimitStep,
        DedupeStep,
        get_step_class,
        list_available_steps,
    )
"""

from .artifact_fetch import ArtifactClient, ArtifactFetchStep
from .base import RetrievalStep
from .dedupe import DedupeStep
from .limit import LimitStep
from .rerank import RerankStep
from .threshold import ThresholdStep
from .vector_search import VectorSearchStep

# =============================================================================
# Step Registry
# =============================================================================

STEP_REGISTRY: dict[str, type[RetrievalStep]] = {
    "vector_search": VectorSearchStep,
    "rerank": RerankStep,
    "threshold": ThresholdStep,
    "limit": LimitStep,
    "dedupe": DedupeStep,
    "artifact_fetch": ArtifactFetchStep,
    # freshness is now handled by unified detection in VectorSearchStep
    # table_query is registered lazily to avoid circular imports
}


def get_step_class(step_type: str) -> type[RetrievalStep]:
    """Get step class by type name."""
    # Handle table_query lazily to avoid circular imports
    if step_type == "table_query":
        from fitz_ai.tabular import TableQueryStep

        return TableQueryStep

    if step_type not in STEP_REGISTRY:
        available = list(STEP_REGISTRY.keys()) + ["table_query"]
        raise ValueError(f"Unknown step type: {step_type!r}. Available: {available}")
    return STEP_REGISTRY[step_type]


def list_available_steps() -> list[str]:
    """List all available step types."""
    return list(STEP_REGISTRY.keys()) + ["table_query"]


__all__ = [
    # Base classes
    "RetrievalStep",
    "ArtifactClient",
    # Step classes
    "VectorSearchStep",
    "RerankStep",
    "ThresholdStep",
    "LimitStep",
    "DedupeStep",
    "ArtifactFetchStep",
    # table_query loaded lazily via get_step_class()
    # Registry functions
    "STEP_REGISTRY",
    "get_step_class",
    "list_available_steps",
]
