qtype 0.1.0__tar.gz → 0.1.2__tar.gz

{qtype-0.1.0/qtype.egg-info → qtype-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qtype
-Version: 0.1.0
+Version: 0.1.2
 Summary: DSL for Generative AI Prototyping
 Author-email: Lou Kratz <lou.kratz+qtype@bazaarvoice.com>
 License-Expression: Apache-2.0
@@ -23,16 +23,26 @@ Provides-Extra: interpreter
 Requires-Dist: aiostream>=0.7.1; extra == "interpreter"
 Requires-Dist: arize-phoenix-otel>=0.12.1; extra == "interpreter"
 Requires-Dist: boto3>=1.34.0; extra == "interpreter"
+Requires-Dist: datasets>=4.4.1; extra == "interpreter"
+Requires-Dist: diskcache>=5.6.3; extra == "interpreter"
 Requires-Dist: docling>=2.55.1; extra == "interpreter"
-Requires-Dist: diskcache[interpreter]>=5.6.3; extra == "interpreter"
+Requires-Dist: docx2txt>=0.9; extra == "interpreter"
 Requires-Dist: fastapi>=0.116.1; extra == "interpreter"
+Requires-Dist: jsonpath-ng>=1.7.0; extra == "interpreter"
+Requires-Dist: langfuse>=3.9.0; extra == "interpreter"
 Requires-Dist: llama-index-embeddings-bedrock>=0.5.2; extra == "interpreter"
 Requires-Dist: llama-index-embeddings-openai>=0.3.1; extra == "interpreter"
 Requires-Dist: llama-index-llms-bedrock-converse>=0.10.5; extra == "interpreter"
 Requires-Dist: llama-index-llms-bedrock>=0.3.8; extra == "interpreter"
+Requires-Dist: llama-index-llms-vertex>=0.6.1; extra == "interpreter"
+Requires-Dist: llama-index-postprocessor-bedrock-rerank>=0.5.1; extra == "interpreter"
+Requires-Dist: llama-index-readers-huggingface-fs>=0.4.1; extra == "interpreter"
+Requires-Dist: llama-index-vector-stores-qdrant>=0.8.6; extra == "interpreter"
 Requires-Dist: llama-index>=0.12.45; extra == "interpreter"
 Requires-Dist: openinference-instrumentation-llama-index>=4.3.4; extra == "interpreter"
 Requires-Dist: opensearch-py>=2.7.0; extra == "interpreter"
+Requires-Dist: opentelemetry-exporter-otlp>=1.35.0; extra == "interpreter"
+Requires-Dist: opentelemetry-sdk>=1.35.0; extra == "interpreter"
 Requires-Dist: pandas>=2.2.3; extra == "interpreter"
 Requires-Dist: psycopg2-binary>=2.9.10; extra == "interpreter"
 Requires-Dist: pyarrow>=21.0.0; extra == "interpreter"
@@ -41,15 +51,6 @@ Requires-Dist: python-magic>=0.4.27; extra == "interpreter"
 Requires-Dist: s3fs>=2025.7.0; extra == "interpreter"
 Requires-Dist: sqlalchemy>=2.0.42; extra == "interpreter"
 Requires-Dist: uvicorn[standard]>=0.35.0; extra == "interpreter"
-Requires-Dist: llama-index-llms-vertex>=0.6.1; extra == "interpreter"
-Requires-Dist: langfuse>=3.9.0; extra == "interpreter"
-Requires-Dist: opentelemetry-exporter-otlp>=1.35.0; extra == "interpreter"
-Requires-Dist: opentelemetry-sdk>=1.35.0; extra == "interpreter"
-Requires-Dist: docx2txt>=0.9; extra == "interpreter"
-Requires-Dist: llama-index-vector-stores-qdrant>=0.8.6; extra == "interpreter"
-Requires-Dist: jsonpath-ng>=1.7.0; extra == "interpreter"
-Requires-Dist: llama-index-readers-huggingface-fs>=0.4.1; extra == "interpreter"
-Requires-Dist: datasets>=4.4.1; extra == "interpreter"
 Dynamic: license-file
 
 # QType

{qtype-0.1.0 → qtype-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qtype"
-version = "0.1.0"
+version = "0.1.2"
 description = "DSL for Generative AI Prototyping"
 authors = [{ name="Lou Kratz", email="lou.kratz+qtype@bazaarvoice.com" }]
 readme = "README.md"
@@ -29,16 +29,26 @@ interpreter = [
     "aiostream>=0.7.1",
     "arize-phoenix-otel>=0.12.1",
     "boto3>=1.34.0",
+    "datasets>=4.4.1",
+    "diskcache>=5.6.3",
     "docling>=2.55.1",
-    "diskcache[interpreter]>=5.6.3",
+    "docx2txt>=0.9",
     "fastapi>=0.116.1",
+    "jsonpath-ng>=1.7.0",
+    "langfuse>=3.9.0",
     "llama-index-embeddings-bedrock>=0.5.2",
     "llama-index-embeddings-openai>=0.3.1",
     "llama-index-llms-bedrock-converse>=0.10.5",
     "llama-index-llms-bedrock>=0.3.8",
+    "llama-index-llms-vertex>=0.6.1",
+    "llama-index-postprocessor-bedrock-rerank>=0.5.1",
+    "llama-index-readers-huggingface-fs>=0.4.1",
+    "llama-index-vector-stores-qdrant>=0.8.6",
     "llama-index>=0.12.45",
     "openinference-instrumentation-llama-index>=4.3.4",
     "opensearch-py>=2.7.0",
+    "opentelemetry-exporter-otlp>=1.35.0",
+    "opentelemetry-sdk>=1.35.0",
     "pandas>=2.2.3",
     "psycopg2-binary>=2.9.10",
     "pyarrow>=21.0.0",
@@ -47,15 +57,6 @@ interpreter = [
     "s3fs>=2025.7.0",
     "sqlalchemy>=2.0.42",
     "uvicorn[standard]>=0.35.0",
-    "llama-index-llms-vertex>=0.6.1",
-    "langfuse>=3.9.0",
-    "opentelemetry-exporter-otlp>=1.35.0",
-    "opentelemetry-sdk>=1.35.0",
-    "docx2txt>=0.9",
-    "llama-index-vector-stores-qdrant>=0.8.6",
-    "jsonpath-ng>=1.7.0",
-    "llama-index-readers-huggingface-fs>=0.4.1",
-    "datasets>=4.4.1",
 ]
 
 [dependency-groups]

{qtype-0.1.0 → qtype-0.1.2}/qtype/application/facade.py

@@ -2,10 +2,10 @@
 
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 from typing import Any
 
-from qtype.base.logging import get_logger
 from qtype.base.types import PathLike
 from qtype.semantic.model import Application as SemanticApplication
 from qtype.semantic.model import DocumentType as SemanticDocumentType
@@ -14,7 +14,7 @@ from qtype.semantic.model import DocumentType as SemanticDocumentType
 # That's the whole point of this facade - to avoid importing optional
 # dependencies unless these methods are called.
 
-logger = get_logger("application.facade")
+logger = logging.getLogger(__name__)
 
 
 class QTypeFacade:
@@ -27,13 +27,13 @@ class QTypeFacade:
     """
 
     def telemetry(self, spec: SemanticDocumentType) -> None:
+        from qtype.interpreter.telemetry import register
+
         if isinstance(spec, SemanticApplication) and spec.telemetry:
             logger.info(
                 f"Telemetry enabled with endpoint: {spec.telemetry.endpoint}"
             )
             # Register telemetry if needed
-            from qtype.interpreter.telemetry import register
-
             register(spec.telemetry, self.secret_manager(spec), spec.id)
 
     def secret_manager(self, spec: SemanticDocumentType):
@@ -75,11 +75,17 @@ class QTypeFacade:
             DataFrame with results (one row per input)
         """
         import pandas as pd
+        from opentelemetry import trace
 
+        from qtype.interpreter.base.executor_context import ExecutorContext
+        from qtype.interpreter.converters import (
+            dataframe_to_flow_messages,
+            flow_messages_to_dataframe,
+        )
+        from qtype.interpreter.flow import run_flow
+        from qtype.interpreter.types import Session
         from qtype.semantic.loader import load
 
-        logger.info(f"Executing workflow from {path}")
-
         # Load the semantic application
         semantic_model, type_registry = load(Path(path))
         assert isinstance(semantic_model, SemanticApplication)
@@ -100,7 +106,10 @@ class QTypeFacade:
             else:
                 raise ValueError("No flows found in application")
 
+        logger.info(f"Executing flow {target_flow.id} from {path}")
+
         # Convert inputs to DataFrame (normalize single dict to 1-row DataFrame)
+
         if isinstance(inputs, dict):
             input_df = pd.DataFrame([inputs])
         elif isinstance(inputs, pd.DataFrame):
@@ -111,12 +120,6 @@ class QTypeFacade:
             )
 
         # Create session
-        from qtype.interpreter.converters import (
-            dataframe_to_flow_messages,
-            flow_messages_to_dataframe,
-        )
-        from qtype.interpreter.types import Session
-
         session = Session(
             session_id=kwargs.pop("session_id", "default"),
             conversation_history=kwargs.pop("conversation_history", []),
@@ -126,12 +129,8 @@ class QTypeFacade:
         initial_messages = dataframe_to_flow_messages(input_df, session)
 
         # Execute the flow
-        from opentelemetry import trace
-
-        from qtype.interpreter.base.executor_context import ExecutorContext
-        from qtype.interpreter.flow import run_flow
-
         secret_manager = self.secret_manager(semantic_model)
+
         context = ExecutorContext(
             secret_manager=secret_manager,
             tracer=trace.get_tracer(__name__),

{qtype-0.1.0 → qtype-0.1.2}/qtype/cli.py

@@ -7,6 +7,10 @@ import importlib
 import logging
 from pathlib import Path
 
+from qtype.base.logging import get_logger
+
+logger = get_logger("application.facade")
+
 try:
     from importlib.metadata import entry_points
 except ImportError:
@@ -131,7 +135,7 @@ def main() -> None:
     # Set logging level based on user input
     logging.basicConfig(
         level=getattr(logging, args.log_level),
-        format="%(levelname)s: %(message)s",
+        format="%(asctime)s - %(levelname)s: %(message)s",
     )
 
     # Dispatch to the selected subcommand

{qtype-0.1.0 → qtype-0.1.2}/qtype/commands/generate.py

@@ -188,7 +188,7 @@ def parser(subparsers: argparse._SubParsersAction) -> None:
 
         has_semantic_deps = True
     except ImportError:
-        logger.warning(
+        logger.debug(
             "NetworkX or Ruff is not installed. Skipping semantic model generation."
         )
         has_semantic_deps = False

{qtype-0.1.0 → qtype-0.1.2}/qtype/commands/run.py

@@ -7,10 +7,12 @@ from __future__ import annotations
 import argparse
 import json
 import logging
+import warnings
 from pathlib import Path
 from typing import Any
 
 import pandas as pd
+from pydantic.warnings import UnsupportedFieldAttributeWarning
 
 from qtype.application.facade import QTypeFacade
 from qtype.base.exceptions import InterpreterError, LoadError, ValidationError
@@ -18,6 +20,15 @@ from qtype.base.exceptions import InterpreterError, LoadError, ValidationError
 logger = logging.getLogger(__name__)
 
 
+# Supress specific pydantic warnings that llamaindex needs to fix
+warnings.filterwarnings("ignore", category=UnsupportedFieldAttributeWarning)
+
+
+# supress qdrant logging
+for name in ["httpx", "urllib3", "qdrant_client", "opensearch"]:
+    logging.getLogger(name).setLevel(logging.WARNING)
+
+
 def read_data_from_file(file_path: str) -> pd.DataFrame:
     """
     Reads a file into a pandas DataFrame based on its MIME type.
@@ -29,12 +40,16 @@ def read_data_from_file(file_path: str) -> pd.DataFrame:
     mime_type = magic.Magic(mime=True).from_file(file_path)
 
     if mime_type == "text/csv":
-        return pd.read_csv(file_path)
+        # TODO: Restore na values and convert to optional once we support them https://github.com/bazaarvoice/qtype/issues/101
+        df = pd.read_csv(file_path)
+        return df.fillna("")
     elif mime_type == "text/plain":
         # For text/plain, use file extension to determine format
         file_ext = Path(file_path).suffix.lower()
         if file_ext == ".csv":
-            return pd.read_csv(file_path)
+            # TODO: Restore na values and convert to optional once we support them https://github.com/bazaarvoice/qtype/issues/101
+            df = pd.read_csv(file_path)
+            return df.fillna("")
         elif file_ext == ".json":
             return pd.read_json(file_path)
         else:
@@ -87,7 +102,10 @@ def run_flow(args: Any) -> None:
         # Execute the workflow using the facade (now async, returns DataFrame)
         result_df = asyncio.run(
             facade.execute_workflow(
-                spec_path, flow_name=args.flow, inputs=input
+                spec_path,
+                flow_name=args.flow,
+                inputs=input,
+                show_progress=args.progress,
             )
         )
 
@@ -95,7 +113,7 @@ def run_flow(args: Any) -> None:
 
         # Display results
         if len(result_df) > 0:
-            logger.info(f"Processed {len(result_df)} input(s)")
+            logger.info(f"Processed {len(result_df)} em")
 
             # Remove 'row' and 'error' columns for display if all errors are None
             display_df = result_df.copy()
@@ -108,7 +126,7 @@ def run_flow(args: Any) -> None:
                 display_df = display_df.drop(columns=["row"])
 
             if len(display_df) > 1:
-                logger.info(f"\nResults:\n{display_df.to_string()}")
+                logger.info(f"\nResults:\n{display_df[0:10].to_string()}\n...")
             else:
                 # Print the first row with column_name: value one per line
                 fmt_str = []
@@ -172,6 +190,11 @@ def parser(subparsers: argparse._SubParsersAction) -> None:
         default=None,
         help="Path to save output data. If input is a DataFrame, output will be saved as parquet. If single result, saved as JSON.",
     )
+    cmd_parser.add_argument(
+        "--progress",
+        action="store_true",
+        help="Show progress bars during flow execution.",
+    )
 
     cmd_parser.add_argument(
         "spec", type=str, help="Path to the QType YAML spec file."

{qtype-0.1.0 → qtype-0.1.2}/qtype/dsl/domain_types.py

@@ -93,12 +93,33 @@ class RAGChunk(Embedding):
     )
 
 
-class RAGSearchResult(StrictBaseModel):
-    """A standard, built-in representation of a search result from a RAG vector search."""
+class SearchResult(StrictBaseModel):
+    """A standard, built-in representation of a search result."""
 
-    chunk: RAGChunk = Field(
+    content: Any = Field(..., description="The content of the search result.")
+    doc_id: str = Field(
+        ...,
+        description="The identifier of the document from which the result was retrieved.",
+    )
+    score: float = Field(
+        ...,
+        description="The relevance score of the search result with respect to the query.",
+    )
+
+
+class RAGSearchResult(SearchResult):
+    """A standard, built-in representation of a search result from a RAG vector search.
+
+    Note: doc_id is duplicated from content.document_id for convenience.
+    """
+
+    content: RAGChunk = Field(
         ..., description="The RAG chunk returned as a search result."
     )
+    doc_id: str = Field(
+        ...,
+        description="The document ID (duplicated from content.document_id).",
+    )
     score: float = Field(
         ...,
         description="The similarity score of the chunk with respect to the query.",

{qtype-0.1.0 → qtype-0.1.2}/qtype/dsl/model.py

@@ -573,6 +573,10 @@ class FieldExtractor(Step):
         ...,
         description="JSONPath expression to extract data from the input. Uses jsonpath-ng syntax.",
     )
+    fail_on_missing: bool = Field(
+        default=True,
+        description="Whether to raise an error if the JSONPath matches no data. If False, returns None.",
+    )
 
 
 class InvokeTool(Step, ConcurrentStepMixin):
@@ -1077,6 +1081,14 @@ class DocumentIndex(Index):
         ...,
         description="URL endpoint for the search cluster (e.g., https://my-cluster.es.amazonaws.com).",
     )
+    id_field: str | None = Field(
+        default=None,
+        description=(
+            "Field name to use as document ID. "
+            "If not specified, auto-detects from: _id, id, doc_id, document_id, or uuid. "
+            "If all are missing, a UUID is generated."
+        ),
+    )
 
 
 class Search(Step, ABC):
@@ -1089,15 +1101,18 @@ class Search(Step, ABC):
     index: Reference[IndexType] | str = Field(
         ..., description="Index to search against (object or ID reference)."
     )
+    default_top_k: int | None = Field(
+        default=10,
+        description="Number of top results to retrieve if not provided in the inputs.",
+    )
 
 
 class VectorSearch(Search, BatchableStepMixin):
     """Performs vector similarity search against a vector index."""
 
     type: Literal["VectorSearch"] = "VectorSearch"
-    default_top_k: int | None = Field(
-        default=50,
-        description="Number of top results to retrieve if not provided in the inputs.",
+    index: Reference[VectorIndex] | str = Field(
+        ..., description="Index to search against (object or ID reference)."
     )
 
 
@@ -1105,6 +1120,43 @@ class DocumentSearch(Search, ConcurrentStepMixin):
     """Performs document search against a document index."""
 
     type: Literal["DocumentSearch"] = "DocumentSearch"
+    index: Reference[DocumentIndex] | str = Field(
+        ..., description="Index to search against (object or ID reference)."
+    )
+    query_args: dict[str, Any] = Field(
+        default={
+            "type": "best_fields",
+            "fields": ["*"],
+        },
+        description="The arguments (other than 'query') to specify to the query shape (see https://docs.opensearch.org/latest/query-dsl/full-text/multi-match/).",
+    )
+
+
+class Reranker(Step):
+    """Reranks a list of documents based on relevance to a query using an LLM."""
+
+    type: Literal["Reranker"] = "Reranker"
+
+
+# TODO: create a reranker that supports llamaindex rerankers...
+
+
+class BedrockReranker(Reranker, ConcurrentStepMixin):
+    """Reranks documents using an AWS Bedrock model."""
+
+    type: Literal["BedrockReranker"] = "BedrockReranker"
+    auth: Reference[AWSAuthProvider] | str | None = Field(
+        default=None,
+        description="AWS authorization provider for Bedrock access.",
+    )
+    model_id: str = Field(
+        ...,
+        description="Bedrock model ID to use for reranking. See https://docs.aws.amazon.com/bedrock/latest/userguide/rerank-supported.html",
+    )
+    num_results: int | None = Field(
+        default=None,
+        description="Return this many results.",
+    )
 
 
 # Create a union type for all tool types
@@ -1146,6 +1198,7 @@ StepType = Annotated[
     Union[
         Agent,
         Aggregate,
+        BedrockReranker,
         Decoder,
         DocToTextConverter,
         DocumentEmbedder,

{qtype-0.1.0 → qtype-0.1.2}/qtype/interpreter/base/base_step_executor.py

@@ -212,7 +212,6 @@ class StepExecutor(ABC):
                     num_workers = (
                         self.step.concurrency_config.num_workers  # type: ignore[attr-defined]
                     )
-
                 span.set_attribute("step.concurrency", num_workers)
 
                 # Prepare messages for processing (batching hook)
@@ -331,6 +330,11 @@ class StepExecutor(ABC):
             cached_result = self.cache.get(key)
             if cached_result is not None:
                 result = [from_cache_value(d, message) for d in cached_result]  # type: ignore
+                self.progress.increment_cache(
+                    self.context.on_progress,
+                    hit_delta=len(result),
+                    miss_delta=0,
+                )
                 # cache hit
                 for msg in result:
                     yield msg
@@ -341,6 +345,9 @@ class StepExecutor(ABC):
                     buf.append(output_msg)
                     yield output_msg
 
+                self.progress.increment_cache(
+                    self.context.on_progress, hit_delta=0, miss_delta=len(buf)
+                )
                 # store the results in the cache of there are no errors or if instructed to do so
                 if (
                     all(not msg.is_failed() for msg in buf)

{qtype-0.1.0 → qtype-0.1.2}/qtype/interpreter/base/executor_context.py

@@ -7,7 +7,8 @@ concerns threaded through the execution pipeline.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
 
 from opentelemetry.trace import Tracer
 
@@ -51,6 +52,9 @@ class ExecutorContext:
         on_progress: Optional callback for progress updates during execution.
         tracer: OpenTelemetry tracer for distributed tracing and observability.
             Defaults to a no-op tracer if telemetry is not configured.
+        thread_pool: Shared thread pool for running synchronous operations
+            in async contexts. Defaults to a pool with 100 threads to support
+            high concurrency workloads without thread exhaustion.
 
     Example:
         ```python
@@ -72,3 +76,16 @@ class ExecutorContext:
     on_stream_event: StreamingCallback | None = None
     on_progress: ProgressCallback | None = None
     tracer: Tracer | None = None
+    thread_pool: ThreadPoolExecutor = field(
+        default_factory=lambda: ThreadPoolExecutor(max_workers=100)
+    )
+
+    def cleanup(self) -> None:
+        """
+        Clean up resources held by the context.
+
+        This should be called when the context is no longer needed to ensure
+        proper cleanup of the thread pool and any other resources.
+        """
+        if self.thread_pool:
+            self.thread_pool.shutdown(wait=True)

qtype-0.1.2/qtype/interpreter/base/factory.py

@@ -0,0 +1,84 @@
+from qtype.semantic.model import (
+    Agent,
+    Aggregate,
+    BedrockReranker,
+    Decoder,
+    DocToTextConverter,
+    DocumentEmbedder,
+    DocumentSearch,
+    DocumentSource,
+    DocumentSplitter,
+    Echo,
+    FieldExtractor,
+    FileSource,
+    FileWriter,
+    IndexUpsert,
+    InvokeEmbedding,
+    InvokeFlow,
+    InvokeTool,
+    LLMInference,
+    PromptTemplate,
+    SQLSource,
+    Step,
+    VectorSearch,
+)
+
+from .batch_step_executor import StepExecutor
+from .executor_context import ExecutorContext
+
+# Lazy-load executor classes only when needed
+# This avoids importing heavy dependencies until actually required
+EXECUTOR_REGISTRY = {
+    Agent: "qtype.interpreter.executors.agent_executor.AgentExecutor",
+    Aggregate: "qtype.interpreter.executors.aggregate_executor.AggregateExecutor",
+    BedrockReranker: "qtype.interpreter.executors.bedrock_reranker_executor.BedrockRerankerExecutor",
+    Decoder: "qtype.interpreter.executors.decoder_executor.DecoderExecutor",
+    DocToTextConverter: "qtype.interpreter.executors.doc_to_text_executor.DocToTextConverterExecutor",
+    DocumentEmbedder: "qtype.interpreter.executors.document_embedder_executor.DocumentEmbedderExecutor",
+    DocumentSearch: "qtype.interpreter.executors.document_search_executor.DocumentSearchExecutor",
+    DocumentSource: "qtype.interpreter.executors.document_source_executor.DocumentSourceExecutor",
+    DocumentSplitter: "qtype.interpreter.executors.document_splitter_executor.DocumentSplitterExecutor",
+    Echo: "qtype.interpreter.executors.echo_executor.EchoExecutor",
+    FieldExtractor: "qtype.interpreter.executors.field_extractor_executor.FieldExtractorExecutor",
+    FileSource: "qtype.interpreter.executors.file_source_executor.FileSourceExecutor",
+    FileWriter: "qtype.interpreter.executors.file_writer_executor.FileWriterExecutor",
+    IndexUpsert: "qtype.interpreter.executors.index_upsert_executor.IndexUpsertExecutor",
+    InvokeEmbedding: "qtype.interpreter.executors.invoke_embedding_executor.InvokeEmbeddingExecutor",
+    InvokeFlow: "qtype.interpreter.executors.invoke_flow_executor.InvokeFlowExecutor",
+    InvokeTool: "qtype.interpreter.executors.invoke_tool_executor.InvokeToolExecutor",
+    LLMInference: "qtype.interpreter.executors.llm_inference_executor.LLMInferenceExecutor",
+    PromptTemplate: "qtype.interpreter.executors.prompt_template_executor.PromptTemplateExecutor",
+    SQLSource: "qtype.interpreter.executors.sql_source_executor.SQLSourceExecutor",
+    VectorSearch: "qtype.interpreter.executors.vector_search_executor.VectorSearchExecutor",
+}
+
+
+def create_executor(
+    step: Step, context: ExecutorContext, **dependencies
+) -> StepExecutor:
+    """
+    Factory to create the appropriate executor for a given step.
+
+    Args:
+        step: The step to create an executor for
+        context: ExecutorContext containing cross-cutting concerns
+        **dependencies: Executor-specific dependencies
+
+    Returns:
+        StepExecutor: Configured executor instance
+    """
+    executor_path = EXECUTOR_REGISTRY.get(type(step))
+    if not executor_path:
+        raise ValueError(
+            f"No executor found for step type: {type(step).__name__}"
+        )
+
+    # Lazy-load the executor class
+    module_path, class_name = executor_path.rsplit(".", 1)
+    import importlib
+
+    module = importlib.import_module(module_path)
+    executor_class = getattr(module, class_name)
+
+    # This assumes the constructor takes the step, context, then dependencies
+    return executor_class(step, context, **dependencies)

{qtype-0.1.0 → qtype-0.1.2}/qtype/interpreter/base/progress_tracker.py

@@ -20,6 +20,8 @@ class ProgressTracker:
         self.items_processed = 0
         self.items_in_error = 0
         self.total_items = total_items
+        self.cache_hits = None
+        self.cache_misses = None
 
     @property
     def items_succeeded(self) -> int:
@@ -36,6 +38,8 @@ class ProgressTracker:
         on_progress: ProgressCallback | None,
         processed_delta: int,
         error_delta: int,
+        hit_delta: int | None = None,
+        miss_delta: int | None = None,
     ) -> None:
         """
         Update progress counters and invoke the progress callback.
@@ -51,6 +55,19 @@ class ProgressTracker:
         self.items_processed += processed_delta
         self.items_in_error += error_delta
 
+        if hit_delta is not None:
+            self.cache_hits = (
+                self.cache_hits + hit_delta
+                if self.cache_hits is not None
+                else hit_delta
+            )
+        if miss_delta is not None:
+            self.cache_misses = (
+                self.cache_misses + miss_delta
+                if self.cache_misses is not None
+                else miss_delta
+            )
+
         if on_progress:
             on_progress(
                 self.step_id,
@@ -58,6 +75,8 @@ class ProgressTracker:
                 self.items_in_error,
                 self.items_succeeded,
                 self.total_items,
+                self.cache_hits,
+                self.cache_misses,
             )
 
     def update_for_message(
@@ -73,3 +92,19 @@ class ProgressTracker:
             on_progress: Optional callback to notify of progress updates
         """
         self.update(on_progress, 1, 1 if message.is_failed() else 0)
+
+    def increment_cache(
+        self,
+        on_progress: ProgressCallback | None,
+        hit_delta: int = 0,
+        miss_delta: int = 0,
+    ) -> None:
+        """
+        Increment cache hit/miss counters.
+
+        Args:
+            on_progress: Optional callback to notify of progress updates
+            hit_delta: Number of cache hits to add
+            miss_delta: Number of cache misses to add
+        """
+        self.update(on_progress, 0, 0, hit_delta, miss_delta)