qtype 0.0.16__py3-none-any.whl → 0.1.1__py3-none-any.whl

qtype/interpreter/base/batch_step_executor.py

@@ -0,0 +1,171 @@
+from abc import abstractmethod
+from typing import Any, AsyncIterator
+
+from aiostream import stream
+from opentelemetry.trace import Status, StatusCode
+
+from qtype.interpreter.base.base_step_executor import StepExecutor
+from qtype.interpreter.base.executor_context import ExecutorContext
+from qtype.interpreter.types import FlowMessage
+
+
+class BatchedStepExecutor(StepExecutor):
+    """
+    Executor for steps that benefit from API-level batching.
+
+    This executor groups messages into batches and processes them together,
+    which is useful for operations that can leverage batch APIs for better
+    performance (e.g., GPU operations, bulk database operations, batch inference).
+
+    Like StepExecutor, this supports concurrent processing, but the unit of
+    concurrency is the batch rather than individual messages.
+
+    **Subclass Requirements:**
+    - Must implement `process_batch()` to handle batch processing
+    - Must NOT implement `process_message()` (it's handled automatically)
+    - Can optionally implement `finalize()` for cleanup/terminal operations
+
+    Args:
+        step: The semantic step model defining behavior and configuration
+        on_stream_event: Optional callback for real-time streaming events
+        on_progress: Optional callback for progress updates
+        **dependencies: Executor-specific dependencies
+    """
+
+    def __init__(
+        self,
+        step: Any,
+        context: ExecutorContext,
+        **dependencies: Any,
+    ):
+        super().__init__(step, context, **dependencies)
+        # Override the processor to use batch processing with telemetry
+        # instead of message processing
+        self._processor = self._process_batch_with_telemetry
+
+    def _prepare_message_stream(
+        self, valid_messages: AsyncIterator[FlowMessage]
+    ) -> Any:
+        """
+        Prepare messages by chunking them into batches.
+
+        Overrides the base implementation to group messages into batches
+        based on the step's batch_config.
+
+        Args:
+            valid_messages: Stream of valid (non-failed) messages
+
+        Returns:
+            Stream of message batches (AsyncIterable[list[FlowMessage]])
+        """
+        # Determine batch size from step configuration
+        batch_size = 1
+        if (
+            hasattr(self.step, "batch_config")
+            and self.step.batch_config is not None  # type: ignore[attr-defined]
+        ):
+            batch_size = self.step.batch_config.batch_size  # type: ignore[attr-defined]
+
+        # Group messages into batches
+        return stream.chunks(valid_messages, batch_size)
+
+    async def process_message(
+        self, message: FlowMessage
+    ) -> AsyncIterator[FlowMessage]:
+        """
+        Process a single message by wrapping it in a batch of one.
+
+        This method is implemented automatically to satisfy the base class
+        contract. Subclasses should NOT override this method.
+
+        Args:
+            message: The input message to process
+
+        Yields:
+            Processed messages from the batch
+        """
+        raise NotImplementedError(
+            "Batch executors should call process_batch, not process_message."
+        )
+        yield  # type: ignore[misc]
+
+    @abstractmethod
+    async def process_batch(
+        self, batch: list[FlowMessage]
+    ) -> AsyncIterator[FlowMessage]:
+        """
+        Process a batch of messages as a single API call.
+
+        Subclasses MUST implement this method to define how batches are
+        processed together for improved performance.
+
+        This is a many-to-many operation: a batch of input messages yields
+        a corresponding set of output messages. Messages should be yielded
+        as they become available to maintain memory efficiency (don't collect
+        all results before yielding).
+
+        This method is automatically wrapped with telemetry tracing when
+        called through the executor's execution pipeline.
+
+        Args:
+            batch: List of input messages to process as a batch
+
+        Yields:
+            Processed messages corresponding to the input batch
+        """
+        yield  # type: ignore[misc]
+
+    async def _process_batch_with_telemetry(
+        self, batch: list[FlowMessage]
+    ) -> AsyncIterator[FlowMessage]:
+        """
+        Internal wrapper that adds telemetry tracing to process_batch.
+
+        This method creates a span for batch processing operations,
+        automatically recording batch size, errors, and success metrics.
+        """
+        span = self._tracer.start_span(
+            f"step.{self.step.id}.process_batch",
+            attributes={
+                "batch.size": len(batch),
+            },
+        )
+
+        try:
+            output_count = 0
+            error_count = 0
+
+            async for output_msg in self.process_batch(batch):
+                output_count += 1
+                if output_msg.is_failed():
+                    error_count += 1
+                    span.add_event(
+                        "message_failed",
+                        {
+                            "error": str(output_msg.error),
+                        },
+                    )
+                yield output_msg
+
+            # Record processing metrics
+            span.set_attribute("batch.outputs", output_count)
+            span.set_attribute("batch.errors", error_count)
+
+            if error_count > 0:
+                span.set_status(
+                    Status(
+                        StatusCode.ERROR,
+                        f"{error_count} of {output_count} messages failed",
+                    )
+                )
+            else:
+                span.set_status(Status(StatusCode.OK))
+
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(
+                Status(StatusCode.ERROR, f"Batch processing failed: {e}")
+            )
+            raise
+        finally:
+            span.end()

qtype/interpreter/base/exceptions.py

@@ -0,0 +1,50 @@
+"""
+Custom exception types for the QType interpreter.
+
+This module provides specialized exception classes for better error handling
+and reporting throughout the interpreter layer.
+"""
+
+from __future__ import annotations
+
+
+class SecretResolutionError(Exception):
+    """
+    Raised when a secret cannot be resolved.
+
+    This exception is raised when attempting to resolve a SecretReference
+    but the operation fails due to:
+    - No secret manager configured
+    - Secret not found in the secret store
+    - Invalid secret format or structure
+    - Authentication/authorization failures
+    """
+
+    def __init__(
+        self,
+        secret_name: str,
+        context: str = "",
+        cause: Exception | None = None,
+    ):
+        """
+        Initialize SecretResolutionError with structured attributes.
+
+        Args:
+            secret_name: Name/ID/ARN of the secret that failed to resolve
+            context: Optional context describing where resolution failed
+                (e.g., "auth provider 'my_auth'", "step 'my_step'")
+            cause: Optional underlying exception that caused the failure
+        """
+        self.secret_name = secret_name
+        self.context = context
+        self.cause = cause
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        """Format the error message from structured attributes."""
+        msg = f"Failed to resolve secret '{self.secret_name}'"
+        if self.context:
+            msg += f" in {self.context}"
+        if self.cause:
+            msg += f": {self.cause}"
+        return msg

qtype/interpreter/base/executor_context.py

@@ -0,0 +1,74 @@
+"""
+Execution context for flow and step executors.
+
+This module provides the ExecutorContext dataclass that bundles cross-cutting
+concerns threaded through the execution pipeline.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from opentelemetry.trace import Tracer
+
+from qtype.interpreter.base.secrets import SecretManagerBase
+from qtype.interpreter.types import ProgressCallback, StreamingCallback
+
+
+@dataclass
+class ExecutorContext:
+    """
+    Runtime context for flow execution shared across all executors.
+
+    This bundles cross-cutting concerns that need to be threaded through
+    the execution pipeline but aren't specific to individual step types.
+    Using a context object reduces parameter threading boilerplate while
+    keeping dependencies explicit and testable.
+
+    Secret Resolution Lifecycle:
+        Secrets are resolved EARLY in the execution pipeline, following a
+        fail-fast principle:
+
+        1. At executor construction time, any SecretReferences in step
+           configuration are resolved
+        2. At auth context creation time, SecretReferences in auth providers
+           are resolved (via auth() context manager)
+        3. Resolution failures raise SecretResolutionError immediately,
+           preventing execution from starting with invalid configuration
+
+        This ensures:
+        - Errors are caught before expensive operations begin
+        - All secrets are validated at initialization
+        - No partial execution with missing secrets
+        - Clear, actionable error messages at startup
+
+    Attributes:
+        secret_manager: Secret manager for resolving SecretReferences at
+            runtime. Always present (uses NoOpSecretManager if no secrets
+            are configured), eliminating the need for None checks.
+        on_stream_event: Optional callback for streaming real-time execution
+            events (chunks, steps, errors) to clients.
+        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.
+
+    Example:
+        ```python
+        from qtype.interpreter.base.executor_context import ExecutorContext
+        from qtype.interpreter.base.secrets import create_secret_manager
+        from opentelemetry import trace
+
+        context = ExecutorContext(
+            secret_manager=create_secret_manager(config),
+            on_stream_event=my_stream_callback,
+            tracer=trace.get_tracer(__name__)
+        )
+
+        executor = create_executor(step, context=context)
+        ```
+    """
+
+    secret_manager: SecretManagerBase
+    on_stream_event: StreamingCallback | None = None
+    on_progress: ProgressCallback | None = None
+    tracer: Tracer | None = None

qtype/interpreter/base/factory.py

@@ -0,0 +1,117 @@
+from qtype.interpreter.executors.agent_executor import AgentExecutor
+from qtype.interpreter.executors.aggregate_executor import AggregateExecutor
+from qtype.interpreter.executors.decoder_executor import DecoderExecutor
+from qtype.interpreter.executors.doc_to_text_executor import (
+    DocToTextConverterExecutor,
+)
+from qtype.interpreter.executors.document_embedder_executor import (
+    DocumentEmbedderExecutor,
+)
+from qtype.interpreter.executors.document_search_executor import (
+    DocumentSearchExecutor,
+)
+from qtype.interpreter.executors.document_source_executor import (
+    DocumentSourceExecutor,
+)
+from qtype.interpreter.executors.document_splitter_executor import (
+    DocumentSplitterExecutor,
+)
+from qtype.interpreter.executors.echo_executor import EchoExecutor
+from qtype.interpreter.executors.field_extractor_executor import (
+    FieldExtractorExecutor,
+)
+from qtype.interpreter.executors.file_source_executor import FileSourceExecutor
+from qtype.interpreter.executors.file_writer_executor import FileWriterExecutor
+from qtype.interpreter.executors.index_upsert_executor import (
+    IndexUpsertExecutor,
+)
+from qtype.interpreter.executors.invoke_embedding_executor import (
+    InvokeEmbeddingExecutor,
+)
+from qtype.interpreter.executors.invoke_flow_executor import InvokeFlowExecutor
+from qtype.interpreter.executors.invoke_tool_executor import InvokeToolExecutor
+from qtype.interpreter.executors.llm_inference_executor import (
+    LLMInferenceExecutor,
+)
+from qtype.interpreter.executors.prompt_template_executor import (
+    PromptTemplateExecutor,
+)
+from qtype.interpreter.executors.sql_source_executor import SQLSourceExecutor
+from qtype.interpreter.executors.vector_search_executor import (
+    VectorSearchExecutor,
+)
+from qtype.semantic.model import (
+    Agent,
+    Aggregate,
+    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
+
+# ... import other executors
+
+EXECUTOR_REGISTRY = {
+    Agent: AgentExecutor,
+    Aggregate: AggregateExecutor,
+    Decoder: DecoderExecutor,
+    DocToTextConverter: DocToTextConverterExecutor,
+    DocumentEmbedder: DocumentEmbedderExecutor,
+    DocumentSearch: DocumentSearchExecutor,
+    DocumentSource: DocumentSourceExecutor,
+    DocumentSplitter: DocumentSplitterExecutor,
+    Echo: EchoExecutor,
+    FieldExtractor: FieldExtractorExecutor,
+    FileSource: FileSourceExecutor,
+    FileWriter: FileWriterExecutor,
+    IndexUpsert: IndexUpsertExecutor,
+    InvokeEmbedding: InvokeEmbeddingExecutor,
+    InvokeFlow: InvokeFlowExecutor,
+    InvokeTool: InvokeToolExecutor,
+    LLMInference: LLMInferenceExecutor,
+    PromptTemplate: PromptTemplateExecutor,
+    SQLSource: SQLSourceExecutor,
+    VectorSearch: 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_class = EXECUTOR_REGISTRY.get(type(step))
+    if not executor_class:
+        raise ValueError(
+            f"No executor found for step type: {type(step).__name__}"
+        )
+
+    # This assumes the constructor takes the step, context, then dependencies
+    return executor_class(step, context, **dependencies)

qtype/interpreter/base/progress_tracker.py

@@ -0,0 +1,110 @@
+from qtype.interpreter.types import FlowMessage, ProgressCallback
+
+
+class ProgressTracker:
+    """
+    Tracks progress for step execution.
+
+    This class encapsulates all progress tracking logic, separating it from
+    the execution logic in StepExecutor.
+
+    Attributes:
+        step_id: ID of the step being tracked
+        items_processed: Total number of items processed
+        items_in_error: Number of items that encountered errors
+        total_items: Total expected items (None if unknown)
+    """
+
+    def __init__(self, step_id: str, total_items: int | None = None):
+        self.step_id = step_id
+        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:
+        """
+        Number of items successfully processed.
+
+        This is derived from items_processed and items_in_error to avoid
+        state inconsistency.
+        """
+        return self.items_processed - self.items_in_error
+
+    def update(
+        self,
+        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.
+
+        Internal state is always updated regardless of whether a callback
+        is provided. This ensures the aggregator can access accurate counts.
+
+        Args:
+            on_progress: Optional callback to notify of progress updates
+            processed_delta: Number of items processed in this update
+            error_delta: Number of items that failed in this update
+        """
+        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,
+                self.items_processed,
+                self.items_in_error,
+                self.items_succeeded,
+                self.total_items,
+                self.cache_hits,
+                self.cache_misses,
+            )
+
+    def update_for_message(
+        self,
+        message: FlowMessage,
+        on_progress: ProgressCallback | None,
+    ) -> None:
+        """
+        Update progress based on a single message result.
+
+        Args:
+            message: The message to check for success/failure
+            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)