qtype 0.0.4__py3-none-any.whl → 0.0.6__py3-none-any.whl

qtype/dsl/model.py

@@ -3,9 +3,15 @@ from __future__ import annotations
 import inspect
 from abc import ABC
 from enum import Enum
-from typing import Any, Type, Union
-
-from pydantic import Field, RootModel, model_validator
+from typing import Any, Literal, Type, Union
+
+from pydantic import (
+    BaseModel,
+    Field,
+    RootModel,
+    ValidationInfo,
+    model_validator,
+)
 
 import qtype.dsl.domain_types as domain_types
 from qtype.dsl.base_types import PrimitiveTypeEnum, StrictBaseModel
@@ -26,7 +32,9 @@ DOMAIN_CLASSES = {
 }
 
 
-def _resolve_variable_type(parsed_type: Any) -> Any:
+def _resolve_variable_type(
+    parsed_type: Any, custom_type_registry: dict[str, Type[BaseModel]]
+) -> Any:
     """Resolve a type string to its corresponding PrimitiveTypeEnum or return as is."""
     # If the type is already resolved or is a structured definition, pass it through.
     if not isinstance(parsed_type, str):
@@ -44,12 +52,16 @@ def _resolve_variable_type(parsed_type: Any) -> Any:
     if parsed_type in DOMAIN_CLASSES:
         return DOMAIN_CLASSES[parsed_type]
 
+    # Check the registry of dynamically created custom types
+    if parsed_type in custom_type_registry:
+        return custom_type_registry[parsed_type]
+
     # If it's not a primitive or a known domain entity, return it as a string.
     # This assumes it might be a reference ID to another custom type.
     return parsed_type
 
 
-class Variable(StrictBaseModel):
+class Variable(BaseModel):
     """Schema for a variable that can serve as input, output, or parameter within the DSL."""
 
     id: str = Field(
@@ -58,67 +70,45 @@ class Variable(StrictBaseModel):
     )
     type: VariableType | str = Field(
         ...,
-        description=("Type of data expected or produced."),
+        description=(
+            "Type of data expected or produced. Either a CustomType or domain specific type."
+        ),
     )
 
     @model_validator(mode="before")
     @classmethod
-    def resolve_type(cls, data: Any) -> Any:
-        if isinstance(data, dict) and "type" in data:
-            data["type"] = _resolve_variable_type(data["type"])  # type: ignore
+    def resolve_type(cls, data: Any, info: ValidationInfo) -> Any:
+        """
+        This validator runs during the main validation pass. It uses the
+        context to resolve string-based type references.
+        """
+        if (
+            isinstance(data, dict)
+            and "type" in data
+            and isinstance(data["type"], str)
+        ):
+            # Get the registry of custom types from the validation context.
+            custom_types = (info.context or {}).get("custom_types", {})
+            resolved = _resolve_variable_type(data["type"], custom_types)
+            # {'id': 'user_message', 'type': 'ChatMessage'}
+            data["type"] = resolved
         return data
 
 
-class TypeDefinitionBase(StrictBaseModel, ABC):
-    id: str = Field(description="The unique identifier for this custom type.")
-    kind: StructuralTypeEnum = Field(
-        ...,
-        description="The kind of structure this type represents (object/array).",
-    )
-    description: str | None = Field(
-        None, description="A description of what this type represents."
-    )
+class CustomType(StrictBaseModel):
+    """A simple declaration of a custom data type by the user."""
 
+    id: str
+    description: str | None = None
+    properties: dict[str, str]
 
-class ObjectTypeDefinition(TypeDefinitionBase):
-    kind: StructuralTypeEnum = StructuralTypeEnum.object
-    properties: dict[str, VariableType | str] | None = Field(
-        None, description="Defines the nested properties."
-    )
 
-    @model_validator(mode="after")
-    def resolve_type(self) -> "ObjectTypeDefinition":
-        """Resolve the type string to its corresponding PrimitiveTypeEnum."""
-        # Pydantic doesn't properly handle enums as strings in model validation,
-        if self.properties:
-            for key, value in self.properties.items():
-                if isinstance(value, str):
-                    self.properties[key] = _resolve_variable_type(value)
-        return self
-
-
-class ArrayTypeDefinition(TypeDefinitionBase):
-    kind: StructuralTypeEnum = StructuralTypeEnum.array
-    type: VariableType | str = Field(
-        ..., description="The type of items in the array."
-    )
-
-    @model_validator(mode="before")
-    @classmethod
-    def resolve_type(cls, data: Any) -> Any:
-        if isinstance(data, dict) and "type" in data:
-            # If the type is a string, resolve it to PrimitiveTypeEnum or Domain Entity class.
-            data["type"] = _resolve_variable_type(data["type"])  # type: ignore
-        return data
-
-
-TypeDefinition = ObjectTypeDefinition | ArrayTypeDefinition
 VariableType = (
     PrimitiveTypeEnum
-    | TypeDefinition
     | Type[Embedding]
     | Type[ChatMessage]
     | Type[ChatContent]
+    | Type[BaseModel]
 )
 
 
@@ -321,6 +311,12 @@ class Flow(Step):
     the first and last step, respectively.
     """
 
+    description: str | None = Field(
+        default=None, description="Optional description of the flow."
+    )
+
+    mode: Literal["Complete", "Chat"] = "Complete"
+
     steps: list[StepType | str] = Field(
         default_factory=list, description="List of steps or step IDs."
     )
@@ -422,7 +418,15 @@ class TelemetrySink(StrictBaseModel):
 
 
 class Application(StrictBaseModel):
-    """Defines a QType application that can include models, variables, and other components."""
+    """Defines a complete QType application specification.
+
+    An Application is the top-level container of the entire
+    program in a QType YAML file. It serves as the blueprint for your
+    AI-powered application, containing all the models, flows, tools, data sources,
+    and configuration needed to run your program. Think of it as the main entry
+    point that ties together all components into a cohesive,
+    executable system.
+    """
 
     id: str = Field(..., description="Unique ID of the application.")
     description: str | None = Field(
@@ -437,7 +441,7 @@ class Application(StrictBaseModel):
     models: list[ModelType] | None = Field(
         default=None, description="List of models used in this application."
     )
-    types: list[TypeDefinition] | None = Field(
+    types: list[CustomType] | None = Field(
         default=None,
         description="List of custom types defined in this application.",
     )
@@ -540,24 +544,7 @@ class VectorSearch(Search):
             ]
 
         if self.outputs is None:
-            self.outputs = [
-                Variable(
-                    id=f"{self.id}.results",
-                    type=ArrayTypeDefinition(
-                        id=f"{self.id}.SearchResult",
-                        type=ObjectTypeDefinition(
-                            id="SearchResult",
-                            description="Result of a search operation.",
-                            properties={
-                                "score": PrimitiveTypeEnum.number,
-                                "id": PrimitiveTypeEnum.text,
-                                "document": PrimitiveTypeEnum.text,
-                            },
-                        ),
-                        description=None,
-                    ),
-                )
-            ]
+            self.outputs = [Variable(id=f"{self.id}.results", type=Embedding)]
         return self
 
 
@@ -639,10 +626,10 @@ class ToolList(RootModel[list[ToolType]]):
     root: list[ToolType]
 
 
-class TypeList(RootModel[list[TypeDefinition]]):
+class TypeList(RootModel[list[CustomType]]):
     """Schema for a standalone list of type definitions."""
 
-    root: list[TypeDefinition]
+    root: list[CustomType]
 
 
 class VariableList(RootModel[list[Variable]]):

qtype/dsl/validator.py

@@ -436,4 +436,24 @@ def validate(
         for obj_id, obj in lookup_map.items()
     }
 
+    # If any chat flow doesn't have an input variable that is a chat message, raise an error.
+    for flow in dsl_application.flows or []:
+        if flow.mode == "Chat":
+            inputs = flow.inputs or []
+            if not any(
+                input_var.type == qtype.dsl.domain_types.ChatMessage
+                for input_var in inputs
+                if isinstance(input_var, dsl.Variable)
+            ):
+                raise QTypeValidationError(
+                    f"Chat flow {flow.id} must have at least one input variable of type ChatMessage."
+                )
+            if (
+                len(flow.outputs) != 1
+                or flow.outputs[0].type != qtype.dsl.domain_types.ChatMessage
+            ):  # type: ignore
+                raise QTypeValidationError(
+                    f"Chat flow {flow.id} must have exactly one output variable of type ChatMessage."
+                )
+
     return dsl_application

qtype/interpreter/api.py

@@ -1,6 +1,10 @@
-from typing import Optional
+from __future__ import annotations
+
+from pathlib import Path
 
 from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
 
 from qtype.interpreter.flow import execute_flow
 from qtype.interpreter.typing import (
@@ -23,19 +27,54 @@ class APIExecutor:
         self.host = host
         self.port = port
 
-    def create_app(self, name: Optional[str]) -> FastAPI:
+    def create_app(
+        self,
+        name: str | None = None,
+        ui_enabled: bool = True,
+        fast_api_args: dict | None = None,
+    ) -> FastAPI:
         """Create FastAPI app with dynamic endpoints."""
-        app = FastAPI(
-            title=name or "QType API",
-            docs_url="/docs",  # Swagger UI
-            redoc_url="/redoc",
-        )
+        if fast_api_args is None:
+            fast_api_args = {
+                "docs_url": "/docs",
+                "redoc_url": "/redoc",
+            }
+
+        app = FastAPI(title=name or "QType API", **fast_api_args)
+
+        # Serve static UI files if they exist
+        if ui_enabled:
+            # Add CORS middleware only for localhost development
+            if self.host in ("localhost", "127.0.0.1", "0.0.0.0"):
+                app.add_middleware(
+                    CORSMiddleware,
+                    allow_origins=["*"],
+                    allow_credentials=True,
+                    allow_methods=["*"],
+                    allow_headers=["*"],
+                )
+            ui_dir = Path(__file__).parent / "ui"
+            if ui_dir.exists():
+                app.mount(
+                    "/ui",
+                    StaticFiles(directory=str(ui_dir), html=True),
+                    name="ui",
+                )
 
         flows = self.definition.flows if self.definition.flows else []
 
         # Dynamically generate POST endpoints for each flow
         for flow in flows:
-            self._create_flow_endpoint(app, flow)
+            if flow.mode == "Chat":
+                # For chat, we can create a single endpoint
+                # that handles the chat interactions
+                from qtype.interpreter.chat.chat_api import (
+                    create_chat_flow_endpoint,
+                )
+
+                create_chat_flow_endpoint(app, flow)
+            else:
+                self._create_flow_endpoint(app, flow)
 
         return app
 
@@ -49,11 +88,9 @@ class APIExecutor:
 
         # Create the endpoint function with proper model binding
         def execute_flow_endpoint(request: RequestModel) -> ResponseModel:  # type: ignore
-            """Execute the specific flow with provided inputs."""
             try:
                 # Make a copy of the flow to avoid modifying the original
-                # TODO: just store this in case we're using memory / need state.
-                # TODO: Store memory and session info in a cache to enable this kind of stateful communication.
+                # TODO: Use session to ensure memory is not used across requests.
                 flow_copy = flow.model_copy(deep=True)
                 # Set input values on the flow variables
                 if flow_copy.inputs:
@@ -98,7 +135,6 @@ class APIExecutor:
         app.post(
             f"/flows/{flow_id}",
             tags=["flow"],
-            summary=f"Execute {flow_id} flow",
-            description=f"Execute the '{flow_id}' flow with the provided input parameters.",
+            description=flow.description or "Execute a flow",
             response_model=ResponseModel,
         )(execute_flow_endpoint)

qtype/interpreter/chat/chat_api.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Generator
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.responses import StreamingResponse
+
+from qtype.dsl.base_types import PrimitiveTypeEnum
+from qtype.dsl.domain_types import ChatContent, ChatMessage, MessageRole
+from qtype.interpreter.chat.file_conversions import file_to_content
+from qtype.interpreter.chat.vercel import (
+    ChatRequest,
+    ErrorChunk,
+    FinishChunk,
+    StartChunk,
+    TextDeltaChunk,
+    TextEndChunk,
+    TextStartChunk,
+    UIMessage,
+)
+from qtype.interpreter.flow import execute_flow
+from qtype.interpreter.streaming_helpers import create_streaming_generator
+from qtype.semantic.model import Flow
+
+
+def _ui_request_to_domain_type(request: ChatRequest) -> list[ChatMessage]:
+    """
+    Convert a ChatRequest to domain-specific ChatMessages.
+
+    Processes all UI messages from the AI SDK UI/React request format.
+    Returns the full conversation history for context.
+    """
+    if not request.messages:
+        raise ValueError("No messages provided in request.")
+
+    # Convert each UIMessage to a domain-specific ChatMessage
+    return [
+        _ui_message_to_domain_type(message) for message in request.messages
+    ]
+
+
+def _ui_message_to_domain_type(message: UIMessage) -> ChatMessage:
+    """
+    Convert a UIMessage to a domain-specific ChatMessage.
+
+    Creates one block for each part in the message content.
+    """
+    blocks = []
+
+    for part in message.parts:
+        if part.type == "text":
+            blocks.append(
+                ChatContent(type=PrimitiveTypeEnum.text, content=part.text)
+            )
+        elif part.type == "reasoning":
+            blocks.append(
+                ChatContent(type=PrimitiveTypeEnum.text, content=part.text)
+            )
+        elif part.type == "file":
+            blocks.append(
+                file_to_content(part.url)  # type: ignore
+            )
+        elif part.type.startswith("tool-"):
+            raise NotImplementedError(
+                "Tool call part handling is not implemented yet."
+            )
+        elif part.type == "dynamic-tool":
+            raise NotImplementedError(
+                "Dynamic tool part handling is not implemented yet."
+            )
+        elif part.type == "step-start":
+            # Step boundaries might not need content blocks
+            continue
+        elif part.type in ["source-url", "source-document"]:
+            raise NotImplementedError(
+                "Source part handling is not implemented yet."
+            )
+        elif part.type.startswith("data-"):
+            raise NotImplementedError(
+                "Data part handling is not implemented yet."
+            )
+        else:
+            # Log unknown part types for debugging
+            raise ValueError(f"Unknown part type: {part.type}")
+
+    # If no blocks were created, raise an error
+    if not blocks:
+        raise ValueError(
+            "No valid content blocks created from UIMessage parts."
+        )
+
+    return ChatMessage(
+        role=MessageRole(message.role),
+        blocks=blocks,
+    )
+
+
+def create_chat_flow_endpoint(app: FastAPI, flow: Flow) -> None:
+    """
+    Create a chat endpoint for the given Flow.
+
+    This creates an endpoint at /flows/{flow_id}/chat that follows the
+    AI SDK UI/React request format and responds with streaming data.
+
+    Args:
+        app: The FastAPI application instance
+        flow: The Flow to create an endpoint for
+    """
+    flow_id = flow.id
+
+    async def handle_chat_data(request: ChatRequest) -> StreamingResponse:
+        """Handle chat requests for the specific flow."""
+
+        try:
+            # Convert AI SDK UI request to domain ChatMessages
+            messages = _ui_request_to_domain_type(request)
+            if not len(messages):
+                raise ValueError("No input messages received")
+
+            # Pop the last message as the current input
+            current_input = messages.pop()
+            if current_input.role != MessageRole.user:
+                raise ValueError(
+                    f"Unexpected input {current_input} from non user role: {current_input.role}"
+                )
+
+            flow_copy = flow.model_copy(deep=True)
+
+            input_variable = [
+                var for var in flow_copy.inputs if var.type == ChatMessage
+            ][0]
+            input_variable.value = current_input
+
+            # Pass conversation context to flow execution for memory population
+            execution_kwargs: Any = {
+                "session_id": request.id,  # Use request ID as session identifier
+                "conversation_history": messages,
+            }
+
+            # Create a streaming generator for the flow execution
+            stream_generator, result_future = create_streaming_generator(
+                execute_flow, flow_copy, **execution_kwargs
+            )
+        except Exception as e:
+            error_chunk = ErrorChunk(errorText=str(e))
+            response = StreamingResponse(
+                [
+                    f"data: {error_chunk.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+                ],
+                media_type="text/plain; charset=utf-8",
+            )
+            response.headers["x-vercel-ai-ui-message-stream"] = "v1"
+            return response
+
+        # Create generator that formats messages according to AI SDK UI streaming protocol
+        def vercel_ai_formatter() -> Generator[str, None, None]:
+            """Format stream data according to AI SDK UI streaming protocol."""
+
+            # Send start chunk
+            start_chunk = StartChunk(messageId=str(uuid.uuid4()))  # type: ignore
+            yield f"data: {start_chunk.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+
+            # Track text content for proper streaming
+            text_id = str(uuid.uuid4())
+            text_started = False
+
+            for step, message in stream_generator:
+                if isinstance(message, ChatMessage):
+                    # Convert ChatMessage to text content
+                    content = " ".join(
+                        [
+                            block.content
+                            for block in message.blocks
+                            if hasattr(block, "content") and block.content
+                        ]
+                    )
+                    if content.strip():
+                        # Start text block if not started
+                        if not text_started:
+                            text_start = TextStartChunk(id=text_id)
+                            yield f"data: {text_start.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+                            text_started = True
+
+                        # Send text delta
+                        text_delta = TextDeltaChunk(id=text_id, delta=content)
+                        yield f"data: {text_delta.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+                else:
+                    # Handle other message types as text deltas
+                    text_content = str(message)
+                    if text_content.strip():
+                        # Start text block if not started
+                        if not text_started:
+                            text_start = TextStartChunk(id=text_id)
+                            yield f"data: {text_start.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+                            text_started = True
+
+                        # Send text delta
+                        text_delta = TextDeltaChunk(
+                            id=text_id, delta=text_content
+                        )
+                        yield f"data: {text_delta.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+
+            # End text block if it was started
+            if text_started:
+                text_end = TextEndChunk(id=text_id)
+                yield f"data: {text_end.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+
+            # Send finish chunk
+            try:
+                result_future.result(timeout=5.0)
+                finish_chunk = FinishChunk()
+                yield f"data: {finish_chunk.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+            except Exception as e:
+                # Send error
+                error_chunk = ErrorChunk(errorText=str(e))
+                logging.error(
+                    f"Error during flow execution: {e}", exc_info=True
+                )
+                yield f"data: {error_chunk.model_dump_json(by_alias=True, exclude_none=True)}\n\n"
+
+        response = StreamingResponse(
+            vercel_ai_formatter(), media_type="text/plain; charset=utf-8"
+        )
+        response.headers["x-vercel-ai-ui-message-stream"] = "v1"
+        return response
+
+    # Add the endpoint to the FastAPI app
+    app.post(
+        f"/flows/{flow_id}/chat",
+        tags=["chat"],
+        summary=f"Chat with {flow_id} flow",
+        description=flow.description,
+        response_class=StreamingResponse,
+    )(handle_chat_data)

qtype/interpreter/chat/file_conversions.py

@@ -0,0 +1,57 @@
+import base64
+
+import magic
+import requests
+
+from qtype.dsl.base_types import PrimitiveTypeEnum
+from qtype.dsl.domain_types import ChatContent
+
+
+def file_to_content(url: str) -> ChatContent:
+    """
+    Convert a file URL to a ChatContent block.
+
+    Args:
+        url: The URL of the file.
+
+    Returns:
+        A ChatContent block with type 'file' and the file URL as content.
+    """
+
+    # Get the bytes from the url.
+    if url.startswith("data:"):
+        # strip the `data:` prefix and decode the base64 content
+        b64content = url[len("data:") :].split(",", 1)[1]
+        content = base64.b64decode(b64content)
+    else:
+        content = requests.get(url).content
+
+    # Determine the mime type using python-magic
+    media_type = magic.from_buffer(content, mime=True)
+
+    if media_type.startswith("image/"):
+        return ChatContent(
+            type=PrimitiveTypeEnum.image, content=content, mime_type=media_type
+        )
+    elif media_type.startswith("video/"):
+        return ChatContent(
+            type=PrimitiveTypeEnum.video, content=content, mime_type=media_type
+        )
+    elif media_type.startswith("audio/"):
+        return ChatContent(
+            type=PrimitiveTypeEnum.audio, content=content, mime_type=media_type
+        )
+    elif media_type.startswith("text/"):
+        return ChatContent(
+            type=PrimitiveTypeEnum.text,
+            content=content.decode("utf-8"),
+            mime_type=media_type,
+        )
+    elif media_type.startswith("document/"):
+        return ChatContent(
+            type=PrimitiveTypeEnum.file, content=content, mime_type=media_type
+        )
+    else:
+        return ChatContent(
+            type=PrimitiveTypeEnum.bytes, content=content, mime_type=media_type
+        )