qtype 0.1.12__py3-none-any.whl → 0.1.14__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?

{examples → qtype/examples}/tutorials/03_structured_data.qtype.yaml

@@ -9,7 +9,7 @@
 # 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 
+#   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: |
@@ -116,7 +116,7 @@ flows:
       # Construct builds typed objects from the decoded fields
       - id: build_result
         type: Construct
-        field_mapping:
+        field_bindings:
           sentiment: sentiment
           confidence: confidence
           key_points: key_points

{examples → qtype/examples}/tutorials/04_tools_and_function_calling.qtype.yaml

@@ -8,7 +8,7 @@
 # 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
+#   qtype run -i '{"days_until_due": 3}' examples/tutorials/04_tools_and_function_calling.qtype.yaml
 
 id: deadline_calculator
 description: |
@@ -17,7 +17,7 @@ description: |
 
 # 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
+  - !include ../../common/tools.qtype.yaml
 
 flows:
   - id: calculate_deadline
@@ -50,7 +50,7 @@ flows:
         tool: qtype.application.commons.tools.get_current_timestamp
         input_bindings: {}
         output_bindings:
-          result: current_time
+          get_current_timestamp_result: current_time
         outputs:
           - current_time
 
@@ -71,7 +71,7 @@ flows:
           timestamp: current_time
           days: days_until_due
         output_bindings:
-          result: deadline_time
+          timedelta_result: deadline_time
         outputs:
           - deadline_time
 
@@ -84,6 +84,6 @@ flows:
           timestamp: deadline_time
           format_string: format_string
         output_bindings:
-          result: deadline_formatted
+          format_datetime_result: deadline_formatted
         outputs:
           - deadline_formatted

qtype/interpreter/auth/aws.py

@@ -8,6 +8,7 @@ AWSAuthProvider configuration from the semantic model.
 from __future__ import annotations
 
 from contextlib import contextmanager
+from dataclasses import asdict, dataclass
 from typing import Any, Generator
 
 import boto3  # type: ignore[import-untyped]
@@ -27,6 +28,30 @@ class AWSAuthenticationError(Exception):
     pass
 
 
+@dataclass
+class AWSCredentials:
+    """Resolved AWS credentials for creating boto3/aioboto3 clients.
+
+    This dataclass holds the resolved AWS credentials that can be passed
+    directly to both boto3 and aioboto3 constructors, ensuring async
+    operations work correctly without botocore session issues.
+    """
+
+    aws_access_key_id: str | None = None
+    aws_secret_access_key: str | None = None
+    aws_session_token: str | None = None
+    region_name: str | None = None
+    profile_name: str | None = None
+
+    def as_kwargs(self) -> dict[str, Any]:
+        """Return non-None credentials as kwargs dict.
+
+        Returns:
+            Dictionary of credential parameters with None values filtered out.
+        """
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
 def _is_session_valid(session: boto3.Session) -> bool:
     """
     Check if a boto3 session is still valid by testing credential access.
@@ -60,14 +85,18 @@ def _is_session_valid(session: boto3.Session) -> bool:
 def aws(
     aws_provider: AWSAuthProvider,
     secret_manager: SecretManagerBase,
-) -> Generator[boto3.Session, None, None]:
+) -> Generator[AWSCredentials, None, None]:
     """
-    Create a boto3 Session using AWS authentication provider configuration.
+    Resolve AWS credentials from provider configuration.
+
+    This context manager resolves AWS credentials based on the authentication
+    method specified in the AWSAuthProvider and returns them as an
+    AWSCredentials dataclass. The credentials can be passed directly to both
+    boto3 and aioboto3 constructors, ensuring async operations work correctly.
 
-    This context manager creates a boto3 Session based on the authentication
-    method specified in the AWSAuthProvider. Sessions are cached using an LRU
-    cache to avoid recreating them unnecessarily. The cache size can be configured
-    via the AUTH_CACHE_MAX_SIZE environment variable (default: 128).
+    Sessions are cached using an LRU cache to avoid recreating them
+    unnecessarily. The cache size can be configured via the AUTH_CACHE_MAX_SIZE
+    environment variable (default: 128).
 
     It supports:
     - Direct credentials (access key + secret key + optional session token)
@@ -81,13 +110,17 @@ def aws(
     - Invalid or expired sessions are evicted and recreated
 
     Args:
-        aws_provider: AWSAuthProvider instance containing authentication configuration
+        aws_provider: AWSAuthProvider instance containing authentication
+            configuration
+        secret_manager: SecretManagerBase for resolving SecretReferences
 
     Yields:
-        boto3.Session: Configured boto3 session ready for creating AWS service clients
+        AWSCredentials: Resolved credentials ready for creating AWS service
+            clients
 
     Raises:
-        AWSAuthenticationError: When authentication fails or configuration is invalid
+        AWSAuthenticationError: When authentication fails or configuration is
+            invalid
 
     Example:
         ```python
@@ -102,9 +135,13 @@ def aws(
             region="us-east-1"
         )
 
-        with aws(aws_auth) as session:
-            athena_client = session.client("athena")
-            s3_client = session.client("s3")
+        with aws(aws_auth, secret_manager) as creds:
+            # Use with boto3
+            client = boto3.client("s3", **creds.as_kwargs())
+
+            # Or with llama-index Bedrock
+            from llama_index.llms.bedrock_converse import BedrockConverse
+            llm = BedrockConverse(**creds.as_kwargs(), model="...")
         ```
     """
     try:
@@ -112,8 +149,8 @@ def aws(
         cached_session = get_cached_auth(aws_provider)
 
         if cached_session is not None and _is_session_valid(cached_session):
-            # Cache hit with valid session
-            yield cached_session
+            # Cache hit with valid session - extract credentials from it
+            yield _extract_credentials(cached_session, aws_provider)
             return
 
         # Cache miss or invalid session - create new session
@@ -123,13 +160,15 @@ def aws(
         credentials = session.get_credentials()
         if credentials is None:
             raise AWSAuthenticationError(
-                f"Failed to obtain AWS credentials for provider '{aws_provider.id}'"
+                f"Failed to obtain AWS credentials for provider "
+                f"'{aws_provider.id}'"
             )
 
         # Cache the valid session using provider object as key
         cache_auth(aws_provider, session)
 
-        yield session
+        # Extract and yield credentials
+        yield _extract_credentials(session, aws_provider)
 
     except (ClientError, NoCredentialsError) as e:
         raise AWSAuthenticationError(
@@ -137,10 +176,48 @@ def aws(
         ) from e
     except Exception as e:
         raise AWSAuthenticationError(
-            f"Unexpected error during AWS authentication for provider '{aws_provider.id}': {e}"
+            f"Unexpected error during AWS authentication for provider "
+            f"'{aws_provider.id}': {e}"
         ) from e
 
 
+def _extract_credentials(
+    session: boto3.Session, aws_provider: AWSAuthProvider
+) -> AWSCredentials:
+    """
+    Extract credentials from a boto3 Session.
+
+    This function extracts the actual credential values from a boto3.Session,
+    including temporary credentials from role assumption. This allows the
+    credentials to be passed directly to boto3/aioboto3 constructors.
+
+    Args:
+        session: The boto3 session to extract credentials from
+        aws_provider: AWSAuthProvider for region/profile information
+
+    Returns:
+        AWSCredentials with the extracted credential values
+    """
+    credentials = session.get_credentials()
+
+    if credentials is None:
+        # No explicit credentials - use profile or environment
+        return AWSCredentials(
+            profile_name=aws_provider.profile_name,
+            region_name=session.region_name or aws_provider.region,
+        )
+
+    # Extract frozen credentials (works for both static and temporary)
+    frozen = credentials.get_frozen_credentials()
+
+    return AWSCredentials(
+        aws_access_key_id=frozen.access_key,
+        aws_secret_access_key=frozen.secret_key,
+        aws_session_token=frozen.token,
+        region_name=session.region_name or aws_provider.region,
+    )
+
+
 def _create_session(
     aws_provider: AWSAuthProvider,
     secret_manager: SecretManagerBase,

qtype/interpreter/auth/generic.py

@@ -44,9 +44,7 @@ from __future__ import annotations
 from contextlib import contextmanager
 from typing import Generator
 
-import boto3  # type: ignore[import-untyped]
-
-from qtype.interpreter.auth.aws import aws
+from qtype.interpreter.auth.aws import AWSCredentials, aws
 from qtype.interpreter.base.secrets import SecretManagerBase
 from qtype.semantic.model import (
     APIKeyAuthProvider,
@@ -111,13 +109,13 @@ def resolve_provider_secrets(
 def auth(
     auth_provider: AuthorizationProvider,
     secret_manager: SecretManagerBase,
-) -> Generator[boto3.Session | AuthorizationProvider, None, None]:
+) -> Generator[AWSCredentials | AuthorizationProvider, None, None]:
     """
-    Create an appropriate session or provider instance based on the auth provider type.
+    Create appropriate credentials or provider instance based on auth provider type.
 
     This context manager dispatches to the appropriate authentication handler based
     on the type of AuthorizationProvider:
-    - AWSAuthProvider: Returns a configured boto3.Session
+    - AWSAuthProvider: Returns AWSCredentials with resolved credentials
     - APIKeyAuthProvider: Returns the provider instance (contains the API key)
 
     Args:
@@ -125,7 +123,7 @@ def auth(
         secret_manager: Secret manager for resolving SecretReferences
 
     Yields:
-        boto3.Session | APIKeyAuthProvider: The appropriate session or provider instance
+        AWSCredentials | AuthorizationProvider: The appropriate credentials or provider instance
 
     Raises:
         UnsupportedAuthProviderError: When an unsupported provider type is used
@@ -135,7 +133,7 @@ def auth(
         from qtype.semantic.model import AWSAuthProvider, APIKeyAuthProvider
         from qtype.interpreter.auth.generic import auth
 
-        # AWS provider - returns boto3.Session
+        # AWS provider - returns AWSCredentials
         aws_auth = AWSAuthProvider(
             id="my-aws-auth",
             type="aws",
@@ -144,8 +142,9 @@ def auth(
             region="us-east-1"
         )
 
-        with auth(aws_auth) as session:
-            s3_client = session.client("s3")
+        with auth(aws_auth, secret_manager) as creds:
+            import boto3
+            s3_client = boto3.client("s3", **creds.as_kwargs())
 
         # API Key provider - returns the provider itself
         api_auth = APIKeyAuthProvider(
@@ -161,8 +160,8 @@ def auth(
     """
     if isinstance(auth_provider, AWSAuthProvider):
         # Use AWS-specific context manager
-        with aws(auth_provider, secret_manager) as session:
-            yield session
+        with aws(auth_provider, secret_manager) as creds:
+            yield creds
 
     elif isinstance(auth_provider, (APIKeyAuthProvider, OAuth2AuthProvider)):
         # For non-AWS providers, resolve secrets and yield modified copy

qtype/interpreter/base/secrets.py

@@ -255,10 +255,12 @@ class AWSSecretManager(SecretManagerBase):
             json.JSONDecodeError: If secret is not valid JSON when key
                 is specified
         """
+        import boto3
+
         from qtype.interpreter.auth.aws import aws
 
-        with aws(self.config.auth) as session:  # type: ignore
-            client = session.client("secretsmanager")
+        with aws(self.config.auth) as creds:  # type: ignore
+            client = boto3.client("secretsmanager", **creds.as_kwargs())
             response = client.get_secret_value(SecretId=secret_ref.secret_name)
 
             if "SecretString" not in response:

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

@@ -194,16 +194,15 @@ def to_llm(
 
         from qtype.semantic.model import AWSAuthProvider
 
+        creds_kwargs = {}
         if model.auth:
             # Type hint for mypy - we know it's AWSAuthProvider for aws-bedrock
             assert isinstance(model.auth, AWSAuthProvider)
-            with aws(model.auth, secret_manager) as session:
-                session = session._session
-        else:
-            session = None
+            with aws(model.auth, secret_manager) as creds:
+                creds_kwargs = creds.as_kwargs()
 
         brv: BaseLLM = BedrockConverse(
-            botocore_session=session,
+            **creds_kwargs,
             model=model.model_id if model.model_id else model.id,
             system_prompt=system_prompt,
             **(model.inference_params if model.inference_params else {}),
@@ -314,14 +313,14 @@ def to_embedding_model(
             BedrockEmbedding,
         )
 
-        session = None
+        creds_kwargs = {}
         if model.auth is not None:
             assert isinstance(model.auth, AWSAuthProvider)
-            with aws(model.auth, secret_manager) as session:
-                session = session._session
+            with aws(model.auth, secret_manager) as creds:
+                creds_kwargs = creds.as_kwargs()
 
         bedrock_embedding: BaseEmbedding = BedrockEmbedding(
-            botocore_session=session,
+            **creds_kwargs,
             model_name=model.model_id if model.model_id else model.id,
             max_retries=100,
         )
@@ -382,10 +381,12 @@ def to_opensearch_client(
         elif hasattr(index.auth, "type") and index.auth.type == "aws":
             # Use AWS authentication with boto3 session
             # Get AWS credentials from auth provider using context manager
-            with auth(index.auth, secret_manager) as auth_session:
-                # Type checker doesn't know this is a boto3.Session
-                # but runtime validation ensures it for AWS auth
-                credentials = auth_session.get_credentials()  # type: ignore
+            with auth(index.auth, secret_manager) as creds:
+                # Create a boto3 session from credentials to get boto3.Credentials
+                import boto3
+
+                session = boto3.Session(**creds.as_kwargs())
+                credentials = session.get_credentials()
                 if credentials is None:
                     raise InterpreterError(
                         f"Failed to obtain AWS credentials for DocumentIndex '{index.id}'"
@@ -394,7 +395,7 @@ def to_opensearch_client(
                 # Use opensearch-py's async AWS auth
                 aws_auth = AWSV4SignerAsyncAuth(
                     credentials,
-                    auth_session.region_name or "us-east-1",  # type: ignore
+                    creds.region_name or "us-east-1",
                     "aoss",  # service name for OpenSearch Serverless
                 )