qtype 0.0.16__py3-none-any.whl → 0.1.1__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,174 @@
 from __future__ import annotations
 
 import logging
-from typing import Any
 
-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 qtype.interpreter.base import factory
+from qtype.interpreter.base.executor_context import ExecutorContext
+from qtype.interpreter.rich_progress import RichProgressCallback
+from qtype.interpreter.types import FlowMessage
+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] | 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])}"
+    # Extract or create ExecutorContext
+    exec_context = kwargs.pop("context", None)
+    progress_callback = RichProgressCallback() if show_progress else 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. Initialize the stream
+        if not isinstance(initial, list):
+            initial = [initial]
+
+        span.set_attribute("flow.input_count", len(initial))
+
+        # Record input variables for observability
+        if initial:
+            import json
+
+            try:
+                input_vars = {
+                    k: v for msg in initial for k, v in msg.variables.items()
+                }
+                span.set_attribute(
+                    SpanAttributes.INPUT_VALUE,
+                    json.dumps(input_vars, default=str),
+                )
+                span.set_attribute(
+                    SpanAttributes.INPUT_MIME_TYPE, "application/json"
+                )
+            except Exception:
+                # If serialization fails, skip it
+                pass
+
+        async def initial_stream():
+            for message in initial:
+                yield message
+
+        current_stream = initial_stream()
+
+        # 3. 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
+
+        # 4. 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 final_results:
+            import json
+
+            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:
+        # 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/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
 )