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

docs/legacy_how_tos/Tools/python-tools.md

@@ -0,0 +1,299 @@
+# Create Tools from Python Modules
+
+QType allows you to automatically convert Python functions into QType tools. This tutorial will walk you through creating a Python module with functions and converting them into a QType specification that can be used in your applications.
+
+## Prerequisites
+
+Before following this tutorial, make sure you understand:
+
+- [Variables and types](../../Concepts/Core/variable.md) in QType
+- [Primitive types](../../components/PrimitiveTypeEnum.md) 
+- [Domain types](../Data%20Types/domain-types.md)
+- [Custom types](../Data%20Types/custom-types.md)
+
+## Overview
+
+The `qtype convert module` command analyzes Python functions in a module and automatically generates QType tool definitions. This saves you from manually writing tool specifications and ensures consistency between your Python code and QType definitions.
+
+## Supported Types
+
+For functions to be converted successfully, all arguments and return types must use supported type annotations:
+
+### Primitive Types
+- `str` → `text`
+- `int` → `int` 
+- `float` → `float`
+- `bool` → `boolean`
+- `bytes` → `file`
+- `datetime.datetime` → `datetime`
+- `datetime.date` → `date`
+- `datetime.time` → `time`
+
+### Domain Types
+- `ChatMessage` from `qtype.dsl.domain_types`
+- `ChatContent` from `qtype.dsl.domain_types`
+- `Embedding` from `qtype.dsl.domain_types`
+
+### Custom Types
+You can use your own classes **only if** they inherit from `pydantic.BaseModel`. These will be automatically converted to QType custom types.
+
+## Creating a Sample Module
+
+Let's create a sample Python module with utility functions. Create a new file called `my_utilities.py`:
+
+```python
+from datetime import datetime, timedelta
+from pydantic import BaseModel
+
+
+class ProcessingResult(BaseModel):
+    """Result of a text processing operation."""
+    processed_text: str
+    word_count: int
+    processing_time: float
+
+
+def count_words(text: str) -> int:
+    """
+    Count the number of words in a text string.
+    
+    Args:
+        text: The input text to count words in.
+        
+    Returns:
+        Number of words in the text.
+    """
+    return len(text.split())
+
+
+def format_timestamp(timestamp: datetime, format_str: str = "%Y-%m-%d %H:%M:%S") -> str:
+    """
+    Format a datetime object as a string.
+    
+    Args:
+        timestamp: The datetime to format.
+        format_str: The format string to use.
+        
+    Returns:
+        Formatted datetime string.
+    """
+    return timestamp.strftime(format_str)
+
+
+def calculate_future_date(start_date: datetime, days_ahead: int) -> datetime:
+    """
+    Calculate a future date by adding days to a start date.
+    
+    Args:
+        start_date: The starting date.
+        days_ahead: Number of days to add.
+        
+    Returns:
+        The calculated future date.
+    """
+    return start_date + timedelta(days=days_ahead)
+
+
+def process_text_advanced(text: str, uppercase: bool = False) -> ProcessingResult:
+    """
+    Process text and return detailed results.
+    
+    Args:
+        text: The text to process.
+        uppercase: Whether to convert to uppercase.
+        
+    Returns:
+        Processing results including word count and timing.
+    """
+    import time
+    start_time = time.time()
+    
+    processed = text.upper() if uppercase else text.lower()
+    word_count = len(text.split())
+    processing_time = time.time() - start_time
+    
+    return ProcessingResult(
+        processed_text=processed,
+        word_count=word_count,
+        processing_time=processing_time
+    )
+```
+
+## Converting the Module to QType Tools
+
+Now convert your Python module to QType tools using the CLI:
+
+```bash
+qtype convert module my_utilities -o my_utilities.qtype.yml
+```
+
+This will generate a QType specification file with all your functions converted to tools.
+
+## Understanding the Generated Output
+
+The generated `my_utilities.qtype.yml` file will contain:
+
+```yaml
+description: Tools created from Python module my_utilities
+id: my_utilities
+tools:
+- description: Count the number of words in a text string.
+  function_name: count_words
+  id: my_utilities.count_words
+  inputs:
+  - id: count_words.text
+    type: text
+  module_path: my_utilities
+  name: count_words
+  outputs:
+  - id: my_utilities.count_words.result
+    type: int
+
+- description: Format a datetime object as a string.
+  function_name: format_timestamp
+  id: my_utilities.format_timestamp
+  inputs:
+  - id: format_timestamp.timestamp
+    type: datetime
+  - id: format_timestamp.format_str
+    type: text
+  module_path: my_utilities
+  name: format_timestamp
+  outputs:
+  - id: my_utilities.format_timestamp.result
+    type: text
+
+- description: Calculate a future date by adding days to a start date.
+  function_name: calculate_future_date
+  id: my_utilities.calculate_future_date
+  inputs:
+  - id: calculate_future_date.start_date
+    type: datetime
+  - id: calculate_future_date.days_ahead
+    type: int
+  module_path: my_utilities
+  name: calculate_future_date
+  outputs:
+  - id: my_utilities.calculate_future_date.result
+    type: datetime
+
+- description: Process text and return detailed results.
+  function_name: process_text_advanced
+  id: my_utilities.process_text_advanced
+  inputs:
+  - id: process_text_advanced.text
+    type: text
+  - id: process_text_advanced.uppercase
+    type: boolean
+  module_path: my_utilities
+  name: process_text_advanced
+  outputs:
+  - id: my_utilities.process_text_advanced.result
+    type: ProcessingResult
+
+types:
+- description: Result of a text processing operation.
+  id: ProcessingResult
+  properties:
+    processed_text: str
+    word_count: int
+    processing_time: float
+```
+
+## Key Features of the Conversion
+
+### Automatic Type Mapping
+- Python types are automatically mapped to QType types
+- Type hints are required for all function parameters and return values
+- Docstrings are extracted and used as tool descriptions
+
+### Custom Type Generation
+- Pydantic models are automatically converted to QType custom types
+- The `ProcessingResult` class becomes a custom type definition
+- All fields in the Pydantic model are preserved with their types
+
+### Tool Naming
+- Tool IDs follow the pattern: `{module_path}.{function_name}`
+- Input variable IDs follow: `{function_name}.{parameter_name}`
+- Output variable IDs follow: `{module_path}.{function_name}.result`
+
+## Requirements and Limitations
+
+### Function Requirements
+1. **Type Annotations**: All functions must have complete type annotations for parameters and return values
+2. **Public Functions**: Only public functions (not starting with `_`) are converted
+3. **Module Definition**: Functions must be defined in the target module (not imported from elsewhere)
+4. **Supported Types**: All types must be mappable to QType types
+
+### Unsupported Features
+- Functions with `*args` or `**kwargs` parameters
+- Functions without return type annotations
+- Complex generic types (e.g., `Dict[str, List[int]]`)
+- Circular type references
+
+## Using Generated Tools
+
+Once you have your `.qtype.yml` file, you can use these tools in QType applications:
+
+```yaml
+id: text_processing_app
+name: Text Processing Application
+
+tools:
+  - import: my_utilities.qtype.yml
+
+flows:
+  - id: word_counter_flow
+    name: Count Words Flow
+    inputs:
+      - id: input_text
+        type: text
+    steps:
+      - id: count
+        type: tool
+        tool: my_utilities.count_words
+        inputs:
+          text: $input_text
+    outputs:
+      - id: word_count
+        source: count.result
+```
+
+## Best Practices
+
+### Function Design
+1. **Clear Docstrings**: Write descriptive docstrings as they become tool descriptions
+2. **Single Responsibility**: Keep functions focused on one task
+3. **Type Safety**: Use precise type hints rather than `Any`
+4. **Error Handling**: Include proper error handling in your functions
+
+### Module Organization
+1. **Logical Grouping**: Group related functions in the same module
+2. **Dependencies**: Keep external dependencies minimal
+3. **Testing**: Write tests for your functions before converting
+
+### Custom Types
+1. **Pydantic Models**: Use Pydantic BaseModel for complex return types
+2. **Field Documentation**: Add docstrings to model fields
+3. **Type Validation**: Leverage Pydantic's validation features
+
+## Troubleshooting
+
+### Common Issues
+
+**"Function must have a return type annotation"**
+- Ensure all functions have explicit return type annotations
+
+**"Unsupported Python type"**
+- Check that all parameter and return types are supported
+- Consider using custom Pydantic models for complex types
+
+**"No public functions found"**
+- Verify functions don't start with underscore
+- Check functions are defined in the target module
+
+### Debugging Tips
+1. Start with simple functions and gradually add complexity
+2. Test your Python functions independently before conversion
+3. Use `mypy` to validate type annotations before conversion
+

examples/authentication/aws_authentication.qtype.yaml

@@ -0,0 +1,63 @@
+id: aws_auth_demo
+description: |
+  Demonstrates different methods of AWS authentication for Bedrock models.
+  Choose the method that best fits your deployment environment.
+
+# Method 1: AWS Profile (recommended for local development)
+# Uses credentials from ~/.aws/credentials
+auths:
+  - type: aws
+    id: aws_profile
+    profile_name: default
+    region: us-east-1
+
+# Method 2: Environment variables (recommended for production)
+# Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION in environment
+# Uncomment to use:
+#  - type: aws
+#    id: aws_env
+#    access_key_id: ${AWS_ACCESS_KEY_ID}
+#    secret_access_key: ${AWS_SECRET_ACCESS_KEY}
+#    region: us-east-1
+
+# Method 3: Role assumption (for cross-account access)
+# Uncomment and configure to use:
+#  - type: aws
+#    id: aws_role
+#    profile_name: base_profile
+#    role_arn: arn:aws:iam::123456789012:role/BedrockAccessRole
+#    role_session_name: qtype-app-session
+#    region: us-east-1
+
+models:
+  - type: Model
+    id: nova_micro
+    provider: aws-bedrock
+    model_id: us.amazon.nova-micro-v1:0
+    auth: aws_profile  # Change to aws_env, aws_keys, or aws_role as needed
+
+flows:
+  - id: simple_completion
+    variables:
+      - id: user_prompt
+        type: text
+      - id: formatted
+        type: text
+      - id: response
+        type: text
+    inputs:
+      - user_prompt
+    outputs:
+      - response
+    steps:
+      - type: PromptTemplate
+        id: format_prompt
+        template: "{user_prompt}"
+        inputs: [user_prompt]
+        outputs: [formatted]
+      
+      - type: LLMInference
+        id: generate
+        model: nova_micro
+        inputs: [formatted]
+        outputs: [response]

examples/conversational_ai/hello_world_chat.qtype.yaml

@@ -0,0 +1,43 @@
+id: hello_world
+description: A simple chat flow with OpenAI
+models:
+  - type: Model
+    id: gpt4
+    provider: openai
+    model_id: gpt-4
+    inference_params:
+      temperature: 0.7
+      max_tokens: 512
+    auth: openai_auth
+auths:
+  - type: api_key
+    id: openai_auth
+    api_key: ${OPENAI_KEY}
+    host: https://api.openai.com
+memories:
+  - id: chat_memory
+    token_limit: 10000
+flows:
+  - type: Flow
+    id: chat_example
+    interface:
+      type: Conversational
+    variables:
+      - id: user_message
+        type: ChatMessage
+      - id: response
+        type: ChatMessage
+    inputs:
+      - user_message
+    outputs:
+      - response
+    steps:
+      - id: llm_inference_step
+        type: LLMInference
+        model: gpt4
+        system_message: "You are a helpful assistant."
+        memory: chat_memory
+        inputs:
+          - user_message
+        outputs:
+          - response

examples/conversational_ai/simple_chatbot.qtype.yaml

@@ -0,0 +1,40 @@
+id: simple_chatbot
+description: A friendly chatbot with conversation memory using 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: 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

examples/data_processing/batch_processing.qtype.yaml

@@ -0,0 +1,54 @@
+id: batch_processing_example
+description: Process multiple inputs loaded from a file
+
+models:
+  - type: Model
+    id: nova_lite
+    provider: aws-bedrock
+    model_id: amazon.nova-lite-v1:0
+
+flows:
+  - type: Flow
+    id: process_queries
+    description: Process multiple queries in batch
+
+    variables:
+      - id: query
+        type: text
+      - id: topic
+        type: text
+      - id: prompt
+        type: text
+      - id: response
+        type: text
+
+    inputs:
+      - query
+      - topic
+
+    outputs:
+      - query
+      - topic
+      - response
+
+    steps:
+      - id: create_prompt
+        type: PromptTemplate
+        template: |
+          Category: {topic}
+          Question: {query}
+          
+          Provide a brief, helpful answer:
+        inputs:
+          - query
+          - topic
+        outputs:
+          - prompt
+
+      - id: answer_query
+        type: LLMInference
+        model: nova_lite
+        inputs:
+          - prompt
+        outputs:
+          - response

examples/data_processing/cache_step_results.qtype.yaml

@@ -0,0 +1,78 @@
+id: cache_step_demo
+description: |
+  Demonstrates step caching to avoid redundant computation.
+  On first run, classifications are cached. On subsequent runs with same inputs,
+  results are retrieved from cache.
+
+auths:
+  - type: aws
+    id: aws_auth
+    region: us-east-1
+
+models:
+  - type: Model
+    id: nova
+    provider: aws-bedrock
+    model_id: us.amazon.nova-micro-v1:0
+    auth: aws_auth
+
+flows:
+  - id: classify_documents
+    variables:
+      - id: file_path
+        type: text
+      - id: document
+        type: text
+      - id: prompt
+        type: text
+      - id: category
+        type: text
+      - id: output_file
+        type: text
+
+    inputs:
+      - file_path
+
+    outputs:
+      - output_file
+
+    steps:
+      - type: FileSource
+        id: load_docs
+        path: file_path
+        outputs: [document]
+
+      - type: PromptTemplate
+        id: create_classification_prompt
+        template: |
+          Classify this document into one of these categories:
+          - Technology
+          - Finance
+          - Healthcare
+          - Education
+          
+          Document: {document}
+          
+          Reply with only the category name.
+        inputs: [document]
+        outputs: [prompt]
+
+      - type: LLMInference
+        id: classify
+        model: nova
+        inputs: [prompt]
+        outputs: [category]
+        # Enable caching with configuration
+        cache_config:
+          namespace: document_classification  # Logical separation for cache
+          version: "1.0"                       # Bump this to invalidate cache
+          on_error: Drop                       # Don't cache errors (default)
+          ttl: 3600                            # Cache for 1 hour (seconds)
+          compress: false                      # Optionally compress cached data
+
+      - type: FileWriter
+        id: write_results
+        path:
+          uri: classification_results.parquet
+        inputs: [document, category]
+        outputs: [output_file]

examples/data_processing/collect_results.qtype.yaml

@@ -0,0 +1,55 @@
+id: collect_example
+description: Aggregate fan-out results preserving only common ancestor variables
+
+flows:
+  - type: Flow
+    id: main
+    description: Process products by category, then collect results
+
+    variables:
+      - id: category
+        type: text
+      - id: region
+        type: text
+      - id: products
+        type: list[text]
+      - id: product
+        type: text
+      - id: processed_product
+        type: text
+      - id: all_processed
+        type: list[text]
+
+    inputs:
+      - category
+      - region
+      - products
+
+    outputs:
+      - all_processed
+
+    steps:
+      # Explode creates multiple messages, each with:
+      # - category (same for all)
+      # - region (same for all)
+      # - product (different for each)
+      - type: Explode
+        id: fan_out
+        inputs: [products]
+        outputs: [product]
+
+      # Each message still has category, region, and its unique product
+      - type: PromptTemplate
+        id: process
+        inputs: [product]
+        outputs: [processed_product]
+        template: "Processed: {product}"
+
+      # Collect aggregates all processed_product values into a list
+      # Only category and region are preserved as "common ancestors"
+      # (same value across all messages)
+      # The unique product variable is NOT preserved (different in each)
+      - type: Collect
+        id: aggregate
+        inputs: [processed_product]
+        outputs: [all_processed]