qtype 0.0.15__py3-none-any.whl → 0.1.0__py3-none-any.whl

qtype/interpreter/flow.py

@@ -1,37 +1,162 @@
 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.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, **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)
+    if exec_context is None:
+        exec_context = ExecutorContext(
+            secret_manager=NoOpSecretManager(),
+            tracer=trace.get_tracer(__name__),
         )
 
-    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]
+
+        # 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
 )
 
 

qtype/interpreter/stream/chat/__init__.py

@@ -0,0 +1,15 @@
+"""
+Stream and chat utilities for QType interpreter.
+
+This package provides conversions between QType's internal streaming
+events and external chat protocols like Vercel AI SDK.
+"""
+
+from __future__ import annotations
+
+from qtype.interpreter.stream.chat.converter import (
+    StreamEventConverter,
+    format_stream_events_as_sse,
+)
+
+__all__ = ["StreamEventConverter", "format_stream_events_as_sse"]