qtype 0.0.12__py3-none-any.whl → 0.1.7__py3-none-any.whl

qtype/interpreter/executors/sql_source_executor.py

@@ -0,0 +1,106 @@
+from typing import AsyncIterator
+
+import boto3  # type: ignore[import-untyped]
+import pandas as pd
+import sqlalchemy
+from sqlalchemy import create_engine
+from sqlalchemy.exc import SQLAlchemyError
+
+from qtype.interpreter.auth.generic import auth
+from qtype.interpreter.base.base_step_executor import StepExecutor
+from qtype.interpreter.base.executor_context import ExecutorContext
+from qtype.interpreter.types import FlowMessage
+from qtype.semantic.model import SQLSource
+
+
+class SQLSourceExecutor(StepExecutor):
+    """Executor for SQLSource steps."""
+
+    def __init__(
+        self, step: SQLSource, context: ExecutorContext, **dependencies
+    ):
+        super().__init__(step, context, **dependencies)
+        if not isinstance(step, SQLSource):
+            raise ValueError(
+                "SQLSourceExecutor can only execute SQLSource steps."
+            )
+        self.step: SQLSource = step
+
+    async def process_message(
+        self,
+        message: FlowMessage,
+    ) -> AsyncIterator[FlowMessage]:
+        """Process a single FlowMessage for the SQLSource step.
+
+        Args:
+            message: The FlowMessage to process.
+        Yields:
+            FlowMessages with the results of SQL query execution.
+        """
+        # Create a database engine - resolve connection string if it's a SecretReference
+        connection_string = self._resolve_secret(self.step.connection)
+        connect_args = {}
+        if self.step.auth:
+            with auth(self.step.auth) as creds:
+                if isinstance(creds, boto3.Session):
+                    connect_args["session"] = creds
+        engine = create_engine(connection_string, connect_args=connect_args)
+
+        output_columns = {output.id for output in self.step.outputs}
+        step_inputs = {i.id for i in self.step.inputs}
+
+        try:
+            # Make a dictionary of column_name: value from message variables
+            params = {
+                col: message.variables.get(col)
+                for col in step_inputs
+                if col in message.variables
+            }
+
+            await self.stream_emitter.status(
+                f"Executing SQL query with params: {params}",
+            )
+
+            # Execute the query and fetch the results into a DataFrame
+            with engine.connect() as connection:
+                result = connection.execute(
+                    sqlalchemy.text(self.step.query),
+                    parameters=params if params else None,
+                )
+                df = pd.DataFrame(
+                    result.fetchall(), columns=list(result.keys())
+                )
+
+            # Confirm the outputs exist in the dataframe
+            columns = set(df.columns)
+            missing_columns = output_columns - columns
+            if missing_columns:
+                raise ValueError(
+                    (
+                        f"SQL Result was missing expected columns: "
+                        f"{', '.join(missing_columns)}, it has columns: "
+                        f"{', '.join(columns)}"
+                    )
+                )
+
+            # Emit one message per result row
+            for _, row in df.iterrows():
+                # Create a dict with only the output columns
+                row_dict = {
+                    str(k): v
+                    for k, v in row.to_dict().items()
+                    if str(k) in output_columns
+                }
+                # Merge with original message variables
+                yield message.copy_with_variables(new_variables=row_dict)
+
+            await self.stream_emitter.status(
+                f"Emitted {len(df)} rows from SQL query"
+            )
+
+        except SQLAlchemyError as e:
+            # Emit error event to stream so frontend can display it
+            await self.stream_emitter.error(str(e))
+            # Set error on the message and yield it
+            message.set_error(self.step.id, e)
+            yield message

qtype/interpreter/executors/vector_search_executor.py

@@ -0,0 +1,91 @@
+"""Vector search executor for retrieving relevant chunks from vector stores."""
+
+from __future__ import annotations
+
+import logging
+from typing import AsyncIterator
+
+from qtype.interpreter.base.base_step_executor import StepExecutor
+from qtype.interpreter.base.executor_context import ExecutorContext
+from qtype.interpreter.conversions import (
+    from_node_with_score,
+    to_llama_vector_store_and_retriever,
+)
+from qtype.interpreter.types import FlowMessage
+from qtype.semantic.model import VectorIndex, VectorSearch
+
+logger = logging.getLogger(__name__)
+
+
+class VectorSearchExecutor(StepExecutor):
+    """Executor for VectorSearch steps using LlamaIndex vector stores."""
+
+    def __init__(
+        self, step: VectorSearch, context: ExecutorContext, **dependencies
+    ):
+        super().__init__(step, context, **dependencies)
+        if not isinstance(step, VectorSearch):
+            raise ValueError(
+                "VectorSearchExecutor can only execute VectorSearch steps."
+            )
+        self.step: VectorSearch = step
+
+        if not isinstance(self.step.index, VectorIndex):
+            raise ValueError(
+                f"VectorSearch step {self.step.id} must reference a VectorIndex."
+            )
+        self.index: VectorIndex = self.step.index
+
+        # Get the vector store and retriever
+        self._vector_store, self._retriever = (
+            to_llama_vector_store_and_retriever(
+                self.step.index, self.context.secret_manager
+            )
+        )
+
+    async def process_message(
+        self,
+        message: FlowMessage,
+    ) -> AsyncIterator[FlowMessage]:
+        """Process a single FlowMessage for the VectorSearch step.
+
+        Args:
+            message: The FlowMessage to process.
+
+        Yields:
+            FlowMessage with search results.
+        """
+        try:
+            # Get the query from the input variable
+            # (validated to be exactly one text input)
+            input_var = self.step.inputs[0]
+            query = message.variables.get(input_var.id)
+
+            if not isinstance(query, str):
+                raise ValueError(
+                    f"VectorSearch input must be text, got {type(query)}"
+                )
+
+            # Perform the vector search
+            logger.debug(f"Performing vector search with query: {query}")
+            nodes_with_scores = await self._retriever.aretrieve(query)
+
+            # Convert results to RAGSearchResult objects
+            search_results = [
+                from_node_with_score(node_with_score)
+                for node_with_score in nodes_with_scores
+            ]
+
+            # Set the output variable (validated to be exactly one output
+            # of type list[RAGSearchResult])
+            output_var = self.step.outputs[0]
+            output_vars = {output_var.id: search_results}
+
+            yield message.copy_with_variables(output_vars)
+
+        except Exception as e:
+            logger.error(f"Vector search failed: {e}", exc_info=True)
+            # Emit error event to stream so frontend can display it
+            await self.stream_emitter.error(str(e))
+            message.set_error(self.step.id, e)
+            yield message

qtype/interpreter/flow.py

@@ -1,37 +1,187 @@
 from __future__ import annotations
 
+import json
 import logging
-from typing import Any
+from collections.abc import AsyncIterator
 
-from qtype.interpreter.exceptions import InterpreterError
-from qtype.interpreter.step import execute_step
-from qtype.semantic.model import Flow, Variable
+from openinference.semconv.trace import (
+    OpenInferenceSpanKindValues,
+    SpanAttributes,
+)
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
+from rich.console import Console
+
+from qtype.interpreter.base import factory
+from qtype.interpreter.base.executor_context import ExecutorContext
+from qtype.interpreter.logging_progress import LoggingProgressCallback
+from qtype.interpreter.rich_progress import RichProgressCallback
+from qtype.interpreter.types import FlowMessage, ProgressCallback
+from qtype.semantic.model import Flow
 
 logger = logging.getLogger(__name__)
 
 
-def execute_flow(flow: Flow, **kwargs: dict[Any, Any]) -> list[Variable]:
-    """Execute a flow based on the provided arguments.
+async def run_flow(
+    flow: Flow,
+    initial: list[FlowMessage] | AsyncIterator[FlowMessage] | FlowMessage,
+    show_progress: bool = False,
+    **kwargs,
+) -> list[FlowMessage]:
+    """
+    Main entrypoint for executing a flow.
 
     Args:
-        flow: The flow to execute.
-        inputs: The input variables for the flow.
-        **kwargs: Additional keyword arguments.
+        flow: The flow to execute
+        initial: Initial FlowMessage(s) to start execution
+        **kwargs: Dependencies including:
+            - context: ExecutorContext with cross-cutting concerns (optional)
+            - Other executor-specific dependencies
+
+    Returns:
+        List of final FlowMessages after execution
     """
-    logger.debug(f"Executing step: {flow.id} with kwargs: {kwargs}")
+    from qtype.interpreter.base.secrets import NoOpSecretManager
 
-    unset_inputs = [input for input in flow.inputs if not input.is_set()]
-    if unset_inputs:
-        raise InterpreterError(
-            f"The following inputs are required but have no values: {', '.join([input.id for input in unset_inputs])}"
+    # Wire up progress callback if requested
+    progress_callback: ProgressCallback | None = None
+    if show_progress:
+        console = Console()
+        if console.is_terminal:
+            progress_callback = RichProgressCallback()
+        else:
+            progress_callback = LoggingProgressCallback(log_every_seconds=120)
+
+    # Extract or create ExecutorContext
+    exec_context = kwargs.pop("context", None)
+    if exec_context is None:
+        exec_context = ExecutorContext(
+            secret_manager=NoOpSecretManager(),
+            tracer=trace.get_tracer(__name__),
+            on_progress=progress_callback,
         )
+    else:
+        if exec_context.on_progress is None and show_progress:
+            exec_context.on_progress = progress_callback
 
-    for step in flow.steps:
-        execute_step(step, **kwargs)
+    # Use tracer from context
+    tracer = exec_context.tracer or trace.get_tracer(__name__)
 
-    unset_outputs = [output for output in flow.outputs if not output.is_set()]
-    if unset_outputs:
-        raise InterpreterError(
-            f"The following outputs are required but have no values: {', '.join([output.id for output in unset_outputs])}"
-        )
-    return flow.outputs
+    # Start a span for the entire flow execution
+    span = tracer.start_span(
+        f"flow.{flow.id}",
+        attributes={
+            "flow.id": flow.id,
+            "flow.step_count": len(flow.steps),
+            SpanAttributes.OPENINFERENCE_SPAN_KIND: (
+                OpenInferenceSpanKindValues.CHAIN.value
+            ),
+        },
+    )
+
+    # Make this span the active context so step spans will nest under it
+    # Only attach if span is recording (i.e., real tracer is configured)
+    ctx = trace.set_span_in_context(span)
+    token = otel_context.attach(ctx) if span.is_recording() else None
+
+    try:
+        # 1. Get the execution plan is just the steps in order
+        execution_plan = flow.steps
+
+        # 2. Convert the initial input to an iterable of some kind. Record telemetry if possible.
+        if isinstance(initial, FlowMessage):
+            span.set_attribute("flow.input_count", 1)
+            input_vars = {k: v for k, v in initial.variables.items()}
+            span.set_attribute(
+                SpanAttributes.INPUT_VALUE,
+                json.dumps(input_vars, default=str),
+            )
+            span.set_attribute(
+                SpanAttributes.INPUT_MIME_TYPE, "application/json"
+            )
+            initial = [initial]
+
+        if isinstance(initial, list):
+            span.set_attribute("flow.input_count", len(initial))
+
+            # convert to async iterator
+            async def list_stream():
+                for message in initial:
+                    yield message
+
+            current_stream = list_stream()
+        elif isinstance(initial, AsyncIterator):
+            # We can't know the count ahead of time
+            current_stream = initial
+        else:
+            raise ValueError(
+                "Initial input must be a FlowMessage, list of FlowMessages, "
+                "or AsyncIterator of FlowMessages"
+            )
+
+        # 4. Chain executors together in the main loop
+        for step in execution_plan:
+            executor = factory.create_executor(step, exec_context, **kwargs)
+            output_stream = executor.execute(
+                current_stream,
+            )
+            current_stream = output_stream
+
+        # 5. Collect the final results from the last stream
+        final_results = [state async for state in current_stream]
+
+        # Close the progress bars if any
+        if progress_callback is not None:
+            progress_callback.close()
+        # Record flow completion metrics
+        span.set_attribute("flow.output_count", len(final_results))
+        error_count = sum(1 for msg in final_results if msg.is_failed())
+        span.set_attribute("flow.error_count", error_count)
+
+        # Record output variables for observability
+        if len(final_results) == 1 and span.is_recording():
+            try:
+                output_vars = {
+                    k: v
+                    for msg in final_results
+                    if not msg.is_failed()
+                    for k, v in msg.variables.items()
+                }
+                span.set_attribute(
+                    SpanAttributes.OUTPUT_VALUE,
+                    json.dumps(output_vars, default=str),
+                )
+                span.set_attribute(
+                    SpanAttributes.OUTPUT_MIME_TYPE, "application/json"
+                )
+            except Exception:
+                # If serialization fails, skip it
+                pass
+
+        if error_count > 0:
+            span.set_status(
+                Status(
+                    StatusCode.ERROR,
+                    f"{error_count} of {len(final_results)} messages failed",
+                )
+            )
+        else:
+            span.set_status(Status(StatusCode.OK))
+
+        return final_results
+
+    except Exception as e:
+        # Record the exception and set error status
+        span.record_exception(e)
+        span.set_status(Status(StatusCode.ERROR, f"Flow failed: {e}"))
+        raise
+    finally:
+        # Clean up context resources if we created it
+        if kwargs.get("context") is None:
+            exec_context.cleanup()
+        # Detach the context and end the span
+        # Only detach if we successfully attached (span was recording)
+        if token is not None:
+            otel_context.detach(token)
+        span.end()

qtype/interpreter/logging_progress.py

@@ -0,0 +1,61 @@
+import logging
+import time
+
+from qtype.interpreter.types import ProgressCallback
+
+
+class LoggingProgressCallback(ProgressCallback):
+    def __init__(self, log_every_seconds: float = 120.0) -> None:
+        super().__init__()
+        self.log_every_seconds = log_every_seconds
+        self._last_log: dict[str, float] = {}
+        self._totals: dict[str, int | None] = {}
+
+    def __call__(
+        self,
+        step_id: str,
+        items_processed: int,
+        items_in_error: int,
+        items_succeeded: int,
+        total_items: int | None,
+        cache_hits: int | None,
+        cache_misses: int | None,
+    ) -> None:
+        logger = logging.getLogger(__name__)
+        now = time.monotonic()
+        last = self._last_log.get(step_id, 0.0)
+
+        self._totals[step_id] = total_items
+
+        if now - last < self.log_every_seconds:
+            return
+
+        self._last_log[step_id] = now
+        total_str = (
+            f"{items_processed}/{total_items}"
+            if total_items is not None
+            else f"{items_processed}"
+        )
+        if cache_hits is not None or cache_misses is not None:
+            logger.info(
+                "Step %s: processed=%s, succeeded=%s, errors=%s, "
+                "cache_hits=%s, cache_misses=%s",
+                step_id,
+                total_str,
+                items_succeeded,
+                items_in_error,
+                cache_hits if cache_hits is not None else "-",
+                cache_misses if cache_misses is not None else "-",
+            )
+        else:
+            logger.info(
+                "Step %s: processed=%s, succeeded=%s, errors=%s",
+                step_id,
+                total_str,
+                items_succeeded,
+                items_in_error,
+            )
+
+    def close(self) -> None:
+        # optional: final summary logging
+        pass

qtype/interpreter/metadata_api.py

@@ -0,0 +1,115 @@
+"""Metadata API endpoints for flow discovery."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+from qtype.interpreter.typing import create_input_shape, create_output_shape
+from qtype.semantic.model import Application, Flow
+
+
+class FlowEndpoints(BaseModel):
+    """Available endpoints for a flow."""
+
+    rest: str = Field(..., description="REST execution endpoint")
+    stream: str | None = Field(
+        None,
+        description="Streaming endpoint (SSE) if flow has an interface",
+    )
+
+
+class FlowMetadata(BaseModel):
+    """Metadata about a flow for frontend discovery."""
+
+    id: str = Field(..., description="Flow ID")
+    description: str | None = Field(None, description="Flow description")
+    interface_type: str | None = Field(
+        None,
+        description="Interface type: 'Complete' or 'Conversational'",
+    )
+    session_inputs: list[str] = Field(
+        default_factory=list,
+        description="Input variables that persist across session",
+    )
+    endpoints: FlowEndpoints = Field(
+        ..., description="Available API endpoints"
+    )
+    input_schema: dict[str, Any] = Field(
+        ..., description="JSON schema for input"
+    )
+    output_schema: dict[str, Any] = Field(
+        ..., description="JSON schema for output"
+    )
+
+
+def create_metadata_endpoints(app: FastAPI, application: Application) -> None:
+    """
+    Create metadata endpoints for flow discovery.
+
+    Args:
+        app: FastAPI application instance
+        application: QType Application with flows
+    """
+
+    @app.get(
+        "/flows",
+        tags=["flows"],
+        summary="List all flows",
+        description="Get metadata for all available flows",
+        response_model=list[FlowMetadata],
+    )
+    async def list_flows() -> list[FlowMetadata]:
+        """List all flows with their metadata."""
+        flows_metadata = []
+
+        for flow in application.flows:
+            metadata = _create_flow_metadata(flow)
+            flows_metadata.append(metadata)
+
+        return flows_metadata
+
+
+def _create_flow_metadata(flow: Flow) -> FlowMetadata:
+    """
+    Create metadata for a single flow.
+
+    Args:
+        flow: Flow to create metadata for
+
+    Returns:
+        FlowMetadata with all information
+    """
+    # Determine interface type
+    interface_type = None
+    session_inputs = []
+    if flow.interface:
+        interface_type = flow.interface.type
+        session_inputs = [
+            var.id if hasattr(var, "id") else str(var)
+            for var in flow.interface.session_inputs
+        ]
+
+    # Create schemas
+    input_model = create_input_shape(flow)
+    output_model = create_output_shape(flow)
+
+    # Determine streaming endpoint availability
+    stream_endpoint = (
+        f"/flows/{flow.id}/stream" if flow.interface is not None else None
+    )
+
+    return FlowMetadata(
+        id=flow.id,
+        description=flow.description,
+        interface_type=interface_type,
+        session_inputs=session_inputs,
+        endpoints=FlowEndpoints(
+            rest=f"/flows/{flow.id}",
+            stream=stream_endpoint,
+        ),
+        input_schema=input_model.model_json_schema(),
+        output_schema=output_model.model_json_schema(),
+    )

qtype/interpreter/resource_cache.py

@@ -2,12 +2,13 @@ import functools
 import os
 from typing import Any, Callable
 
-from cachetools import LRUCache  # type: ignore[import-untyped]
+from cachetools import TTLCache  # type: ignore[import-untyped]
 
-# Global LRU cache with a reasonable default size
+# Global TTL cache with a reasonable default size and 55-minute TTL
 _RESOURCE_CACHE_MAX_SIZE = int(os.environ.get("RESOURCE_CACHE_MAX_SIZE", 128))
-_GLOBAL_RESOURCE_CACHE: LRUCache[Any, Any] = LRUCache(
-    maxsize=_RESOURCE_CACHE_MAX_SIZE
+_RESOURCE_CACHE_TTL = int(os.environ.get("RESOURCE_CACHE_TTL", 55 * 60))
+_GLOBAL_RESOURCE_CACHE: TTLCache[Any, Any] = TTLCache(
+    maxsize=_RESOURCE_CACHE_MAX_SIZE, ttl=_RESOURCE_CACHE_TTL
 )