qtype 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

examples/research_assistant/tavily.qtype.yaml

@@ -0,0 +1,289 @@
+auths:
+- id: tavily-api_bearerauth_token
+  token: ${TAVILY-API_BEARER}
+  type: bearer_token
+description: Tools created from API specification 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:
+    auto_parameters:
+      optional: true
+      type: boolean
+    country:
+      optional: true
+      type: text
+    days:
+      optional: true
+      type: int
+    end_date:
+      optional: true
+      type: text
+    exclude_domains:
+      optional: true
+      type:
+        element_type: text
+    include_answer:
+      optional: true
+      type: text
+    include_domains:
+      optional: true
+      type:
+        element_type: text
+    include_favicon:
+      optional: true
+      type: boolean
+    include_images:
+      optional: true
+      type: boolean
+    include_raw_content:
+      optional: true
+      type: text
+    max_results:
+      optional: true
+      type: int
+    query:
+      optional: false
+      type: text
+    search_depth:
+      optional: true
+      type: text
+    start_date:
+      optional: true
+      type: text
+    time_range:
+      optional: true
+      type: text
+    topic:
+      optional: true
+      type: text
+  method: POST
+  name: Search the web
+  outputs:
+    answer:
+      optional: true
+      type: text
+    follow_up_questions:
+      optional: true
+      type:
+        element_type: text
+    images:
+      optional: true
+      type:
+        element_type: schema_4844015520
+    query:
+      optional: true
+      type: text
+    response_time:
+      optional: true
+      type: float
+    results:
+      optional: true
+      type:
+        element_type: schema_4844016144
+  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:
+    extract_depth:
+      optional: true
+      type: text
+    format:
+      optional: true
+      type: text
+    include_favicon:
+      optional: true
+      type: boolean
+    include_images:
+      optional: true
+      type: boolean
+    urls:
+      optional: false
+      type:
+        element_type: text
+  method: POST
+  name: Extract content from URLs
+  outputs:
+    failed_results:
+      optional: true
+      type:
+        element_type: schema_4844027472
+    results:
+      optional: true
+      type:
+        element_type: schema_4844024880
+  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:
+    allow_external:
+      optional: true
+      type: boolean
+    exclude_domains:
+      optional: true
+      type:
+        element_type: text
+    exclude_paths:
+      optional: true
+      type:
+        element_type: text
+    extract_depth:
+      optional: true
+      type: text
+    format:
+      optional: true
+      type: text
+    include_favicon:
+      optional: true
+      type: boolean
+    include_images:
+      optional: true
+      type: boolean
+    instructions:
+      optional: true
+      type: text
+    limit:
+      optional: true
+      type: int
+    max_breadth:
+      optional: true
+      type: int
+    max_depth:
+      optional: true
+      type: int
+    select_domains:
+      optional: true
+      type:
+        element_type: text
+    select_paths:
+      optional: true
+      type:
+        element_type: text
+    url:
+      optional: false
+      type: text
+  method: POST
+  name: Crawl websites
+  outputs:
+    results:
+      optional: true
+      type:
+        element_type: schema_4844408352
+  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:
+    allow_external:
+      optional: true
+      type: boolean
+    exclude_domains:
+      optional: true
+      type:
+        element_type: text
+    exclude_paths:
+      optional: true
+      type:
+        element_type: text
+    include_images:
+      optional: true
+      type: boolean
+    instructions:
+      optional: true
+      type: text
+    limit:
+      optional: true
+      type: int
+    max_breadth:
+      optional: true
+      type: int
+    max_depth:
+      optional: true
+      type: int
+    select_domains:
+      optional: true
+      type:
+        element_type: text
+    select_paths:
+      optional: true
+      type:
+        element_type: text
+    url:
+      optional: false
+      type: text
+  method: POST
+  name: Map website structure
+  outputs:
+    results:
+      optional: true
+      type:
+        element_type: schema_4844415936
+  parameters: {}
+  type: APITool
+types:
+- description: Generated from OpenAPI schema
+  id: schema_4844015520
+  properties:
+    alt_text: text?
+    title: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4844016144
+  properties:
+    content: text?
+    favicon: text?
+    raw_content: text?
+    score: float?
+    title: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4844024880
+  properties:
+    content: text?
+    favicon: text?
+    title: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4844027472
+  properties:
+    error: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4844408352
+  properties:
+    content: text?
+    favicon: text?
+    links: list[text]?
+    title: text?
+    url: text?
+- description: Generated from OpenAPI schema
+  id: schema_4844415936
+  properties:
+    depth: int?
+    links: list[text]?
+    title: text?
+    url: text?

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

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

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:
+#   uv run 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_mapping:
+          sentiment: sentiment
+          confidence: confidence
+          key_points: key_points
+          rating: rating
+        inputs:
+          - sentiment
+          - confidence
+          - key_points
+          - rating
+        outputs:
+          - result

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:
+#   uv run 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 https://raw.githubusercontent.com/bazaarvoice/qtype/refs/tags/v0.1.11/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:
+          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:
+          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:
+          result: deadline_formatted
+        outputs:
+          - deadline_formatted

qtype/application/converters/tools_from_api.py

@@ -86,47 +86,53 @@ def _create_custom_type_from_schema(
     schema_name_map: dict[int, str],
 ) -> CustomType:
     """Create a CustomType from an Object schema."""
-    # Generate a unique ID for this schema-based type
-    type_id = None
+    # Use object id instead of hash(str()) to avoid recursion with circular refs
+    schema_id = id(schema)
+
+    # Check if we already have this type (prevents circular reference issues)
+    if schema_id in schema_name_map:
+        type_id = schema_name_map[schema_id]
+        if type_id in existing_custom_types:
+            return existing_custom_types[type_id]
 
-    schema_hash = hash(str(schema))
-    if schema_hash in schema_name_map:
-        type_id = schema_name_map[schema_hash]
+    # Generate a unique ID for this schema-based type
+    if schema.title:
+        # Use title if available, make it lowercase, alphanumeric, snake_case
+        base_id = schema.title.lower().replace(" ", "_").replace("-", "_")
+        # Remove non-alphanumeric characters except underscores
+        type_id = "schema_" + "".join(
+            c for c in base_id if c.isalnum() or c == "_"
+        )
     else:
-        # make a type id manually
-        if schema.title:
-            # Use title if available, make it lowercase, alphanumeric, snake_case
-            base_id = schema.title.lower().replace(" ", "_").replace("-", "_")
-            # Remove non-alphanumeric characters except underscores
-            type_id = "schema_" + "".join(
-                c for c in base_id if c.isalnum() or c == "_"
-            )
-        else:
-            # Fallback to hash if no title
-            type_id = f"schema_{hash(str(schema))}"
+        # Fallback to object id if no title
+        type_id = f"schema_{schema_id}"
 
-    # Check if we already have this type
+    # Check again with the generated type_id
     if type_id in existing_custom_types:
         return existing_custom_types[type_id]
 
-    # Create properties from the schema
-    properties = _schema_to_qtype_properties(
-        schema, existing_custom_types, schema_name_map
-    )
-
-    # Create the custom type
-    custom_type = CustomType(
+    # Create a placeholder to prevent infinite recursion
+    # This will be updated with properties below
+    placeholder = CustomType(
         id=type_id,
         description=schema.description
         or schema.title
         or "Generated from OpenAPI schema",
-        properties=properties,
+        properties={},  # Empty initially
     )
 
-    # Store it in the registry to prevent infinite recursion
-    existing_custom_types[type_id] = custom_type
+    # Store it BEFORE processing properties to break circular references
+    existing_custom_types[type_id] = placeholder
 
-    return custom_type
+    # Now process properties (which may reference back to this type)
+    properties = _schema_to_qtype_properties(
+        schema, existing_custom_types, schema_name_map
+    )
+
+    # Update the placeholder with actual properties
+    placeholder.properties = properties
+
+    return placeholder
 
 
 def _schema_to_qtype_type(
@@ -353,9 +359,6 @@ def to_api_tool(
 def to_authorization_provider(
     api_name: str, scheme_name: str, security: Security
 ) -> AuthProviderType:
-    if security.scheme is None:
-        raise ValueError("Security scheme is missing")
-
     match security.type:
         case SecurityType.API_KEY:
             return APIKeyAuthProvider(
@@ -364,6 +367,8 @@ def to_authorization_provider(
                 host=None,  # Will be set from base URL if available
             )
         case SecurityType.HTTP:
+            if security.scheme is None:
+                raise ValueError("HTTP security scheme is missing")
             if security.scheme == AuthenticationScheme.BEARER:
                 return BearerTokenAuthProvider(
                     id=f"{api_name}_{scheme_name}_{security.bearer_format or 'token'}",
@@ -452,11 +457,10 @@ def tools_from_api(
     existing_custom_types: dict[str, CustomType] = {}
     tools = []
 
-    # Create a mapping from schema hash to their names in the OpenAPI spec
-    # Note: We can't monkey-patch here since the openapi_parser duplicates instances in memory
-    # if they are $ref'd in the content
+    # Create a mapping from schema id to their names in the OpenAPI spec
+    # Use id() instead of hash(str()) to avoid infinite recursion with circular refs
     schema_name_map: dict[int, str] = {
-        hash(str(schema)): name.replace(" ", "-").replace("_", "-")
+        id(schema): name.replace(" ", "-").replace("_", "-")
         for name, schema in specification.schemas.items()
     }