qtype 0.1.11__py3-none-any.whl → 0.1.13__py3-none-any.whl

qtype/examples/research_assistant/tavily.qtype.yaml

@@ -0,0 +1,216 @@
+auths:
+- id: tavily-api_bearerauth_token
+  token: ${TAVILY-API_BEARER}
+  type: bearer_token
+description: Tools created from API specification 
+  examples/research_assistant/tavily.oas.yaml
+flows: []
+id: tavily-api
+indexes: []
+memories: []
+models: []
+references: []
+tools:
+- auth: tavily-api_bearerauth_token
+  description: 'Perform a web search with various filtering and customization options.
+    Returns search results with content, URLs, scores, and optional answers. '
+  endpoint: https://api.tavily.com/search
+  headers: {}
+  id: search
+  inputs:
+  - id: query
+    type: text
+  - id: search_depth
+    type: text?
+  - id: topic
+    type: text?
+  - id: time_range
+    type: text?
+  - id: start_date
+    type: text?
+  - id: end_date
+    type: text?
+  - id: days
+    type: int?
+  - id: max_results
+    type: int?
+  - id: include_domains
+    type: list[text]?
+  - id: exclude_domains
+    type: list[text]?
+  - id: include_answer
+    type: text?
+  - id: include_raw_content
+    type: text?
+  - id: include_images
+    type: boolean?
+  - id: country
+    type: text?
+  - id: auto_parameters
+    type: boolean?
+  - id: include_favicon
+    type: boolean?
+  method: POST
+  name: Search the web
+  outputs:
+  - id: query
+    type: text?
+  - id: follow_up_questions
+    type: list[text]?
+  - id: answer
+    type: text?
+  - id: images
+    type: list[schema_4849029360]?
+  - id: results
+    type: list[schema_4849029792]?
+  - id: response_time
+    type: float?
+  parameters: []
+  type: APITool
+- auth: tavily-api_bearerauth_token
+  description: 'Extract and process content from one or more URLs with various formatting
+    options. Returns extracted content in text or markdown format. '
+  endpoint: https://api.tavily.com/extract
+  headers: {}
+  id: extract
+  inputs:
+  - id: urls
+    type: list[text]
+  - id: include_images
+    type: boolean?
+  - id: extract_depth
+    type: text?
+  - id: format
+    type: text?
+  - id: include_favicon
+    type: boolean?
+  method: POST
+  name: Extract content from URLs
+  outputs:
+  - id: results
+    type: list[schema_4849038576]?
+  - id: failed_results
+    type: list[schema_4849041168]?
+  parameters: []
+  type: APITool
+- auth: tavily-api_bearerauth_token
+  description: 'Crawl a website starting from a given URL with depth and breadth controls.
+    Extract content from discovered pages with various filtering options. '
+  endpoint: https://api.tavily.com/crawl
+  headers: {}
+  id: crawl
+  inputs:
+  - id: url
+    type: text
+  - id: max_depth
+    type: int?
+  - id: max_breadth
+    type: int?
+  - id: limit
+    type: int?
+  - id: instructions
+    type: text?
+  - id: select_paths
+    type: list[text]?
+  - id: select_domains
+    type: list[text]?
+  - id: exclude_paths
+    type: list[text]?
+  - id: exclude_domains
+    type: list[text]?
+  - id: allow_external
+    type: boolean?
+  - id: include_images
+    type: boolean?
+  - id: extract_depth
+    type: text?
+  - id: format
+    type: text?
+  - id: include_favicon
+    type: boolean?
+  method: POST
+  name: Crawl websites
+  outputs:
+  - id: results
+    type: list[schema_4849520304]?
+  parameters: []
+  type: APITool
+- auth: tavily-api_bearerauth_token
+  description: "Map the structure and links of a website starting from a given URL.
+    Discover the website's architecture and page hierarchy. "
+  endpoint: https://api.tavily.com/map
+  headers: {}
+  id: map
+  inputs:
+  - id: url
+    type: text
+  - id: max_depth
+    type: int?
+  - id: max_breadth
+    type: int?
+  - id: limit
+    type: int?
+  - id: instructions
+    type: text?
+  - id: select_paths
+    type: list[text]?
+  - id: select_domains
+    type: list[text]?
+  - id: exclude_paths
+    type: list[text]?
+  - id: exclude_domains
+    type: list[text]?
+  - id: allow_external
+    type: boolean?
+  - id: include_images
+    type: boolean?
+  method: POST
+  name: Map website structure
+  outputs:
+  - id: results
+    type: list[schema_4849527888]?
+  parameters: []
+  type: APITool
+types:
+- description: Generated from OpenAPI schema
+  id: schema_4849029360
+  properties:
+    alt_text: text?
+    title: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4849029792
+  properties:
+    content: text?
+    favicon: text?
+    raw_content: text?
+    score: float?
+    title: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4849038576
+  properties:
+    content: text?
+    favicon: text?
+    title: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4849041168
+  properties:
+    error: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4849520304
+  properties:
+    content: text?
+    favicon: text?
+    links: list[text]?
+    title: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4849527888
+  properties:
+    depth: int?
+    links: list[text]?
+    title: text?
+    url: text?

qtype/examples/tutorials/01_hello_world.qtype.yaml

@@ -0,0 +1,48 @@
+id: 01_hello_world
+description: My first QType application
+
+auths:
+  - type: api_key
+    id: openai_auth
+    api_key: ${OPENAI_KEY}
+    host: https://api.openai.com
+
+models:
+  - type: Model
+    id: gpt-4
+    provider: openai
+    model_id: gpt-4-turbo
+    auth: openai_auth
+    inference_params:
+      temperature: 0.7
+
+flows:
+  - type: Flow
+    id: simple_example
+    variables:
+      - id: question
+        type: text
+      - id: formatted_prompt
+        type: text
+      - id: answer
+        type: text
+    inputs:
+      - question
+    outputs:
+      - answer
+    steps:
+      - id: format_prompt
+        type: PromptTemplate
+        template: "You are a helpful assistant. Answer the following question:\n{question}\n"
+        inputs:
+          - question
+        outputs:
+          - formatted_prompt
+
+      - id: llm_step
+        type: LLMInference
+        model: gpt-4
+        inputs:
+          - formatted_prompt
+        outputs:
+          - answer

qtype/examples/tutorials/02_conversational_chat.qtype.yaml

@@ -0,0 +1,37 @@
+id: 02_conversational_chat
+description: A simple stateful chat flow with AWS Bedrock
+models:
+  - type: Model
+    id: nova_lite
+    provider: aws-bedrock
+    model_id: amazon.nova-lite-v1:0
+    inference_params:
+      temperature: 0.7
+      max_tokens: 512
+memories:
+  - id: chat_memory
+    token_limit: 10000
+flows:
+  - type: Flow
+    id: simple_chat_example
+    interface:
+      type: Conversational
+    variables:
+      - id: user_message
+        type: ChatMessage
+      - id: response_message
+        type: ChatMessage
+    inputs:
+      - user_message
+    outputs:
+      - response_message
+    steps:
+      - id: llm_inference_step
+        type: LLMInference
+        model: nova_lite
+        system_message: "You are a helpful assistant."
+        memory: chat_memory
+        inputs:
+          - user_message
+        outputs:
+          - response_message

qtype/examples/tutorials/03_structured_data.qtype.yaml

@@ -0,0 +1,130 @@
+# Tutorial 3: Working with Types and Structured Data
+#
+# This tutorial demonstrates how to:
+# 1. Define a CustomType for your domain
+# 2. Extract fields from structured data using JSONPath (FieldExtractor)
+# 3. Parse LLM output into structured format (Decoder)
+# 4. Construct typed objects from extracted data (Construct)
+#
+# Scenario: Analyze a product review to extract structured sentiment
+#
+# Run with:
+#   qtype run -i '{"review_text":"These headphones are amazing! Great sound quality and super comfortable. Battery lasts all day."}' examples/tutorials/03_structured_data.qtype.yaml 
+
+id: review_sentiment_analyzer
+description: |
+  Analyzes a product review to extract structured sentiment insights.
+  Demonstrates custom types and structured data extraction.
+
+# Define a custom type for sentiment analysis
+types:
+  - id: ReviewSentiment
+    description: Structured sentiment analysis of a review
+    properties:
+      sentiment: text
+      confidence: float
+      key_points: list[text]
+      rating: int
+
+models:
+  - type: Model
+    id: analyzer_model
+    provider: aws-bedrock
+    model_id: amazon.nova-lite-v1:0
+    inference_params:
+      temperature: 0.7
+      max_tokens: 512
+
+flows:
+  - id: analyze_review
+    description: Analyzes a single review and extracts structured sentiment
+    inputs:
+      - review_text
+    outputs:
+      - result
+
+    variables:
+      - id: review_text
+        type: text
+      - id: raw_llm_response
+        type: text
+      - id: llm_response
+        type: text
+      - id: sentiment
+        type: text
+      - id: confidence
+        type: float
+      - id: key_points
+        type: list[text]
+      - id: rating
+        type: int
+      - id: result
+        type: ReviewSentiment
+
+    steps:
+      # Step 1: Create analysis prompt
+      - id: analysis_prompt
+        type: PromptTemplate
+        template: |
+          Analyze this product review and extract structured information.
+
+          Review: {{review_text}}
+
+          Respond with ONLY valid JSON, no other text or markdown. Use this exact structure:
+          {{
+            "sentiment": "positive|negative|neutral|mixed",
+            "confidence": 0.95,
+            "key_points": ["point 1", "point 2"],
+            "rating": 4
+          }}
+
+          Where:
+          - sentiment: overall sentiment (positive/negative/neutral/mixed)
+          - confidence: your confidence score (0.0-1.0)
+          - key_points: 2-3 main points from the review
+          - rating: estimated star rating 1-5 based on the tone
+          
+          Return ONLY the JSON object, nothing else.
+        inputs:
+          - review_text
+        outputs:
+          - raw_llm_response
+
+      # Step 2: Run LLM inference
+      - id: analyze
+        type: LLMInference
+        model: analyzer_model
+        inputs:
+          - raw_llm_response
+        outputs:
+          - llm_response
+
+      # Step 3: Parse the JSON response and build the ReviewSentiment object
+      # Decoder converts the JSON string into structured data
+      - id: parse_and_build
+        type: Decoder
+        format: json
+        inputs:
+          - llm_response
+        outputs:
+          - sentiment
+          - confidence
+          - key_points
+          - rating
+
+      # Step 4: Construct a ReviewSentiment object
+      # Construct builds typed objects from the decoded fields
+      - id: build_result
+        type: Construct
+        field_bindings:
+          sentiment: sentiment
+          confidence: confidence
+          key_points: key_points
+          rating: rating
+        inputs:
+          - sentiment
+          - confidence
+          - key_points
+          - rating
+        outputs:
+          - result

qtype/examples/tutorials/04_tools_and_function_calling.qtype.yaml

@@ -0,0 +1,89 @@
+# Tutorial 4: Adding Tools to Your Application
+#
+# This tutorial demonstrates how to:
+# 1. Import pre-built tools from the commons library
+# 2. Use InvokeTool to call Python functions
+# 3. Chain multiple tools together with input/output bindings
+#
+# Scenario: Calculate a deadline by adding days to the current time
+#
+# Run with:
+#   qtype run -i '{"days_until_due": 3}' examples/tutorials/04_tools_and_function_calling.qtype.yaml
+
+id: deadline_calculator
+description: |
+  Calculates a deadline by adding days to the current timestamp.
+  Demonstrates tool imports, InvokeTool step, and tool chaining.
+
+# Import pre-built tools from the commons library
+references:
+  - !include ../../common/tools.qtype.yaml
+
+flows:
+  - id: calculate_deadline
+    description: Calculate a formatted deadline from current time plus days
+    inputs:
+      - days_until_due
+    outputs:
+      - deadline_formatted
+
+    variables:
+      # Input
+      - id: days_until_due
+        type: int
+      
+      # Tool outputs
+      - id: current_time
+        type: datetime
+      - id: deadline_time
+        type: datetime
+      - id: format_string
+        type: text
+      - id: deadline_formatted
+        type: text
+
+    steps:
+      # Step 1: Get current timestamp using a tool
+      # This tool takes no inputs and returns the current UTC time
+      - id: get_current_time
+        type: InvokeTool
+        tool: qtype.application.commons.tools.get_current_timestamp
+        input_bindings: {}
+        output_bindings:
+          get_current_timestamp_result: current_time
+        outputs:
+          - current_time
+
+      # Step 2: Create a format string constant
+      - id: create_format_string
+        type: PromptTemplate
+        template: "%B %d, %Y at %I:%M %p UTC"
+        inputs: []
+        outputs:
+          - format_string
+
+      # Step 3: Calculate deadline by adding days to current time
+      # input_bindings maps flow variables to tool parameters
+      - id: add_days
+        type: InvokeTool
+        tool: qtype.application.commons.tools.timedelta
+        input_bindings:
+          timestamp: current_time
+          days: days_until_due
+        output_bindings:
+          timedelta_result: deadline_time
+        outputs:
+          - deadline_time
+
+      # Step 4: Format deadline for human readability
+      # Shows chaining: output from previous tool becomes input to this one
+      - id: format_deadline
+        type: InvokeTool
+        tool: qtype.application.commons.tools.format_datetime
+        input_bindings:
+          timestamp: deadline_time
+          format_string: format_string
+        output_bindings:
+          format_datetime_result: deadline_formatted
+        outputs:
+          - deadline_formatted

qtype/interpreter/api.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import asyncio
 from contextlib import asynccontextmanager
 from pathlib import Path
+from typing import Any
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -86,8 +87,10 @@ class APIExecutor:
         if ui_enabled:
             # Add CORS middleware only for localhost development
             if self.host in ("localhost", "127.0.0.1", "0.0.0.0"):
+                from typing import cast
+
                 app.add_middleware(
-                    CORSMiddleware,
+                    cast(Any, CORSMiddleware),
                     allow_origins=["*"],
                     allow_credentials=True,
                     allow_methods=["*"],

qtype/interpreter/base/base_step_executor.py

@@ -355,7 +355,9 @@ class StepExecutor(ABC):
                 ):
                     serialized = [to_cache_value(m, self.step) for m in buf]
                     self.cache.set(
-                        key, serialized, expire=self.step.cache_config.ttl
+                        key,
+                        serialized,
+                        expire=self.step.cache_config.ttl,  # type: ignore[union-attr]
                     )  # type: ignore
 
     async def _process_message_with_telemetry(

qtype/interpreter/base/stream_emitter.py

@@ -121,15 +121,15 @@ class ReasoningStreamContext:
     """
     Async context manager for reasoning streaming.
 
-    Automatically emits ReasoningStreamStartEvent on entry and
-    ReasoningStreamEndEvent on exit. Provides delta() method for emitting
-    reasoning chunks.
+    Only emits ReasoningStreamStartEvent on the first delta() call, and only
+    emits ReasoningStreamEndEvent if start was sent. This prevents empty
+    reasoning streams when models don't provide reasoning data.
 
     Example:
         ```python
         async with emitter.reasoning_stream("agent-reasoning") as streamer:
             async for chunk in agent.stream_reasoning():
-                await streamer.delta(chunk.text)
+                await streamer.delta(chunk.text)  # Start event on first call
         ```
     """
 
@@ -142,15 +142,10 @@ class ReasoningStreamContext:
         self.step = step
         self.stream_id = stream_id
         self.on_stream_event = on_stream_event
+        self._started = False
 
     async def __aenter__(self) -> ReasoningStreamContext:
-        """Emit ReasoningStreamStartEvent when entering context."""
-        if self.on_stream_event:
-            await self.on_stream_event(
-                ReasoningStreamStartEvent(
-                    step=self.step, stream_id=self.stream_id
-                )
-            )
+        """Enter context without emitting start event."""
         return self
 
     async def __aexit__(
@@ -159,8 +154,8 @@ class ReasoningStreamContext:
         exc_val: BaseException | None,
         exc_tb: Any,
     ) -> bool:
-        """Emit ReasoningStreamEndEvent when exiting context."""
-        if self.on_stream_event:
+        """Emit ReasoningStreamEndEvent only if stream was started."""
+        if self._started and self.on_stream_event:
             await self.on_stream_event(
                 ReasoningStreamEndEvent(
                     step=self.step, stream_id=self.stream_id
@@ -172,10 +167,21 @@ class ReasoningStreamContext:
         """
         Emit a reasoning delta chunk.
 
+        Sends ReasoningStreamStartEvent on first call, then delta events.
+
         Args:
             text: The incremental reasoning content to append to the stream
         """
         if self.on_stream_event:
+            # Emit start event on first delta
+            if not self._started:
+                await self.on_stream_event(
+                    ReasoningStreamStartEvent(
+                        step=self.step, stream_id=self.stream_id
+                    )
+                )
+                self._started = True
+
             await self.on_stream_event(
                 ReasoningStreamDeltaEvent(
                     step=self.step,

qtype/interpreter/conversions.py

@@ -331,7 +331,7 @@ def to_embedding_model(
             OpenAIEmbedding,
         )
 
-        api_key = None
+        api_key: str | None = None
         if model.auth:
             with auth(model.auth, secret_manager) as provider:
                 if not isinstance(provider, APIKeyAuthProvider):
@@ -343,7 +343,7 @@ def to_embedding_model(
                 api_key = provider.api_key  # type: ignore[assignment]
 
         openai_embedding: BaseEmbedding = OpenAIEmbedding(
-            api_key=api_key,
+            api_key=api_key,  # type: ignore[arg-type]
             model_name=model.model_id if model.model_id else model.id,
         )
         return openai_embedding
@@ -523,7 +523,11 @@ def from_chat_message(message: LlamaChatMessage) -> ChatMessage:
                 f"Unsupported content block type: {type(block)}"
             )
 
-    return ChatMessage(role=message.role, blocks=blocks)
+    # Convert llama_index MessageRole to our MessageRole
+    from qtype.dsl.domain_types import MessageRole as QTypeMessageRole
+
+    role = QTypeMessageRole(message.role.value)
+    return ChatMessage(role=role, blocks=blocks)
 
 
 def to_text_splitter(splitter: DocumentSplitter) -> Any: