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

qtype/docs/How To/Data Processing/read_sql_databases.md

@@ -2,6 +2,8 @@
 
 Query relational databases and process results row-by-row using the `SQLSource` step, which supports any database accessible via SQLAlchemy connection strings.
 
+**Note:** SQLSource is a source step that generates data from database queries, so flows using it typically require no inputs.
+
 ### QType YAML
 
 ```yaml

qtype/docs/Reference/cli.md

@@ -34,14 +34,15 @@ qtype run [options] spec
 #### Options
 
 - **`-f FLOW, --flow FLOW`** - The name of the flow to run. If not specified, runs the first flow found
-- **`-i INPUT, --input INPUT`** - JSON blob of input values for the flow (default: `{}`)
+- **`-i INPUT, --input INPUT`** - JSON blob of input values for the flow (optional - omit for flows with source steps that generate their own data)
 - **`-I INPUT_FILE, --input-file INPUT_FILE`** - Path to a file (e.g., CSV, JSON, Parquet) with input data for batch processing
 - **`-o OUTPUT, --output OUTPUT`** - Path to save output data. If input is a DataFrame, output will be saved as parquet. If single result, saved as JSON
 - **`--progress`** - Show progress bars during flow execution
+- **`--show-output`** - Display full output data in console (default: summary only)
 
 #### Examples
 
-Run a simple application:
+Run a simple application with no inputs (e.g., flows with source steps):
 ```bash
 qtype run app.qtype.yaml
 ```

qtype/docs/Reference/plugins.md

@@ -93,7 +93,3 @@ my-qtype-plugin/
 └── tests/
     └── test_plugin.py
 ```
-
-## See Also
-
-- [CLI Reference](cli.md)

qtype/docs/Reference/semantic-validation-rules.md

@@ -176,9 +176,4 @@ This document lists all semantic validation rules enforced by QType. These rules
 ## VectorSearch
 
 - Must have exactly 1 input of type `text`
-- Must have exactly 1 output of type `list[RAGSearchResult]`
-
-## See Also
-
-- [Validate QType YAML](../How%20To/Observability%20%26%20Debugging/validate_qtype_yaml.md)
-- [CLI Reference](cli.md)
+- Must have exactly 1 output of type `list[RAGSearchResult]`

qtype/docs/Tutorials/01-first-qtype-application.md

@@ -180,7 +180,7 @@ Replace `sk-your-key-here` with your actual OpenAI API key.
 Run your application:
 
 ```bash
-qtype run -i '{"question":"What is 2+2?"}' 01_hello_world.qtype.yaml
+qtype run -i '{"question":"What is 2+2?"}' --show-output 01_hello_world.qtype.yaml
 ```
 
 **What you should see:**

qtype/docs/Tutorials/03-structured-data.md

@@ -316,7 +316,7 @@ Should pass ✅
 ### Run It!
 
 ```bash
-qtype run -i '{"review_text":"These headphones are amazing! Great sound quality and super comfortable. Battery lasts all day."}' 03_structured_data.qtype.yaml
+qtype run -i '{"review_text":"These headphones are amazing! Great sound quality and super comfortable. Battery lasts all day."}' --show-output 03_structured_data.qtype.yaml
 ```
 
 **Expected output:**

qtype/docs/Tutorials/04-tools-and-function-calling.md

@@ -305,7 +305,7 @@ Should pass ✅
 ### Run the Application
 
 ```bash
-qtype run -i '{"days_until_due": 3}' 04_tools_and_function_calling.qtype.yaml
+qtype run -i '{"days_until_due": 3}' --show-output 04_tools_and_function_calling.qtype.yaml
 ```
 
 **Expected output:**

qtype/examples/conversational_ai/simple_chatbot_with_auth.qtype.yaml

@@ -0,0 +1,48 @@
+id: simple_chatbot
+description: A friendly chatbot with conversation memory using AWS Bedrock
+
+# AWS Authentication for Bedrock
+auths:
+  - type: aws
+    id: aws_auth
+    profile_name: ${AWS_PROFILE}
+
+models:
+  - type: Model
+    id: nova_lite
+    provider: aws-bedrock
+    model_id: amazon.nova-lite-v1:0
+    inference_params:
+      temperature: 0.7
+      max_tokens: 512
+    auth: aws_auth
+memories:
+  - id: conversation_memory
+    token_limit: 10000
+flows:
+  - type: Flow
+    id: chat_flow
+    interface:
+      type: Conversational
+    variables:
+      - id: user_message
+        type: ChatMessage
+      - id: assistant_response
+        type: ChatMessage
+    inputs:
+      - user_message
+    outputs:
+      - assistant_response
+    steps:
+      - id: generate_response
+        type: LLMInference
+        model: nova_lite
+        system_message: |
+          You are a friendly and helpful chatbot. You have a warm, conversational 
+          tone and enjoy helping users with their questions. You remember context 
+          from previous messages in the conversation.
+        memory: conversation_memory
+        inputs:
+          - user_message
+        outputs:
+          - assistant_response

qtype/examples/data_processing/load_documents.qtype.yaml

@@ -0,0 +1,31 @@
+# Load all markdown files from docs directory using DocumentSource
+#
+# This example demonstrates using DocumentSource with SimpleDirectoryReader
+# to load documents from a local directory with file filtering.
+
+id: load_documents_example
+description: Load markdown files from docs directory
+
+flows:
+  - type: Flow
+    id: load_md_files
+    description: Load all markdown files from docs directory
+
+    variables:
+      - id: document
+        type: RAGDocument
+
+    inputs: []
+    outputs:
+      - document
+
+    steps:
+      - type: DocumentSource
+        id: md_docs
+        reader_module: llama_index.core.SimpleDirectoryReader
+        args:
+          input_dir: docs
+          required_exts: [".md"]
+          recursive: true
+        outputs:
+          - document

qtype/examples/invoke_models/invoke_embedding_aws.qtype.yaml

@@ -0,0 +1,45 @@
+id: invoke_embedding_test
+description: Test InvokeEmbedding step with AWS Bedrock embeddings
+
+# AWS Authentication for Bedrock
+auths:
+  - type: aws
+    id: aws_auth
+    profile_name: ${AWS_PROFILE}
+
+models:
+  # Embedding model using AWS Bedrock
+  - type: EmbeddingModel
+    id: titan_embed
+    provider: aws-bedrock
+    model_id: amazon.titan-embed-text-v2:0
+    dimensions: 1024
+    auth: aws_auth
+
+flows:
+  - type: Flow
+    id: test_invoke_embedding
+    description: Generate embeddings for text using AWS Bedrock
+    
+    variables:
+      - id: input_text
+        type: text
+        ui:
+          widget: textarea
+      - id: embedding
+        type: Embedding
+    
+    inputs:
+      - input_text
+    
+    outputs:
+      - embedding
+    
+    steps:
+      - id: generate_embedding
+        type: InvokeEmbedding
+        model: titan_embed
+        inputs:
+          - input_text
+        outputs:
+          - embedding

qtype/examples/rag/recipe_chatbot.qtype.yaml

@@ -0,0 +1,216 @@
+id: recipe_rag_chatbot
+description: |
+  RAG chatbot for the Chowdown recipe collection from GitHub.
+  
+  This application provides two flows:
+  
+  1. recipe_chat: Conversational chatbot that answers questions about recipes
+     - Uses RAG to find relevant recipes based on user questions
+     - Maintains conversation history with memory
+     - Provides cooking advice, recipe recommendations, and ingredient information
+  
+  2. recipe_ingestion: Ingests recipe markdown files into vector database
+     - Clones/fetches recipes from GitHub (clarklab/chowdown)
+     - Splits recipe documents into searchable chunks
+     - Generates embeddings using AWS Bedrock Titan
+     - Stores in Qdrant vector database for fast similarity search
+  
+  Prerequisites:
+  - AWS credentials configured (AWS_PROFILE environment variable)
+  - Qdrant running locally on port 6333 (or update args for Qdrant Cloud)
+  - Clone the recipe repo: git clone https://github.com/clarklab/chowdown.git
+  
+  To ingest recipes:
+    qtype run recipe_chatbot.qtype.yaml --flow recipe_ingestion
+  
+  To start chatbot:
+    qtype serve recipe_chatbot.qtype.yaml --flow recipe_chat
+
+# AWS Authentication for Bedrock
+auths:
+  - type: aws
+    id: aws_auth
+    profile_name: ${AWS_PROFILE}
+
+# Models
+models:
+  # Embedding model for vectorizing recipes and queries
+  - type: EmbeddingModel
+    id: titan_embed
+    provider: aws-bedrock
+    model_id: amazon.titan-embed-text-v2:0
+    dimensions: 1024
+    auth: aws_auth
+  
+  # Chat model for conversational responses
+  - type: Model
+    id: claude_sonnet
+    provider: aws-bedrock
+    model_id: us.anthropic.claude-3-5-sonnet-20241022-v2:0
+    inference_params:
+      temperature: 0.7
+      max_tokens: 4096
+    auth: aws_auth
+
+# Vector index for recipe embeddings
+indexes:
+  - type: VectorIndex
+    module: llama_index.vector_stores.qdrant.QdrantVectorStore
+    id: recipe_index
+    name: chowdown_recipes
+    embedding_model: titan_embed
+    args:
+      collection_name: chowdown_recipes
+      url: http://localhost:6333
+      api_key: ""  # Empty for local Qdrant
+
+# Memory for maintaining conversation context
+memories:
+  - id: recipe_chat_memory
+    token_limit: 10000
+    chat_history_token_ratio: 0.7
+
+# Flows
+flows:
+  # Conversational chatbot flow
+  - type: Flow
+    id: recipe_chat
+    description: Chat with the recipe collection using RAG
+    
+    interface:
+      type: Conversational
+    
+    variables:
+      - id: user_message
+        type: ChatMessage
+      - id: user_question
+        type: text
+      - id: search_results
+        type: list[RAGSearchResult]
+      - id: context_prompt
+        type: text
+      - id: assistant_response
+        type: ChatMessage
+    
+    inputs:
+      - user_message
+    
+    outputs:
+      - assistant_response
+    
+    steps:
+      # Extract text from user's chat message
+      - id: extract_question
+        type: FieldExtractor
+        json_path: "$.blocks[?(@.type == 'text')].content"
+        inputs:
+          - user_message
+        outputs:
+          - user_question
+      
+      # Search recipe vector index for relevant recipes
+      - id: search_recipes
+        type: VectorSearch
+        index: recipe_index
+        default_top_k: 5
+        inputs:
+          - user_question
+        outputs:
+          - search_results
+      
+      # Build prompt with recipe context
+      - id: build_context_prompt
+        type: PromptTemplate
+        template: |
+          You are a helpful cooking assistant with access to a collection of recipes from Chowdown.
+          
+          Here are the most relevant recipes based on the user's question:
+          
+          {search_results}
+          
+          User question: {user_question}
+          
+          Please provide a helpful answer based on the recipes above. If you're suggesting a recipe, 
+          include key ingredients and brief cooking instructions. If the recipes don't contain 
+          relevant information, politely say so and offer general cooking advice if appropriate.
+        inputs:
+          - search_results
+          - user_question
+        outputs:
+          - context_prompt
+      
+      # Generate conversational response using LLM with memory
+      - id: generate_response
+        type: LLMInference
+        model: claude_sonnet
+        memory: recipe_chat_memory
+        system_message: |
+          You are a friendly and knowledgeable cooking assistant. You help users find recipes, 
+          answer questions about ingredients, suggest substitutions, and provide cooking tips.
+          Base your answers on the provided recipe context, but feel free to add general 
+          cooking knowledge when helpful. Be conversational and enthusiastic about food!
+        inputs:
+          - context_prompt
+        outputs:
+          - assistant_response
+
+  # Recipe ingestion flow
+  - type: Flow
+    id: recipe_ingestion
+    description: Load recipes from local GitHub clone, chunk, embed, and index
+    
+    variables:
+      - id: recipe_document
+        type: RAGDocument
+      - id: recipe_chunk
+        type: RAGChunk
+      - id: embedded_chunk
+        type: RAGChunk
+    
+    outputs:
+      - embedded_chunk
+    
+    steps:
+      # Load recipe markdown files from local clone
+      - id: load_recipes
+        type: DocumentSource
+        reader_module: llama_index.core.SimpleDirectoryReader
+        args:
+          input_dir: "./chowdown/_recipes"
+          recursive: false
+          required_exts: [".md"]
+        outputs:
+          - recipe_document
+      
+      # Split recipes into chunks for better retrieval
+      - id: split_recipes
+        type: DocumentSplitter
+        splitter_name: "SentenceSplitter"
+        chunk_size: 512
+        chunk_overlap: 50
+        inputs:
+          - recipe_document
+        outputs:
+          - recipe_chunk
+      
+      # Generate embeddings for each chunk
+      - id: embed_chunks
+        type: DocumentEmbedder
+        model: titan_embed
+        concurrency_config:
+          num_workers: 5
+        inputs:
+          - recipe_chunk
+        outputs:
+          - embedded_chunk
+      
+      # Store embedded chunks in Qdrant
+      - id: index_recipes
+        type: IndexUpsert
+        index: recipe_index
+        batch_config:
+          batch_size: 25
+        inputs:
+          - embedded_chunk
+        outputs:
+          - embedded_chunk

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: