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

qtype/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
+

qtype/docs/skills/architect/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: qtype-architect
+description: Expert assistant for designing and building AI applications using QType's declarative YAML specification language. Helps users architect flows from concept to implementation, validates QType code, generates visualizations, and recommends best practices. Use when users want to build chatbots, RAG systems, agents, data pipelines, or any AI application with QType. Use when the user mentions building AI apps, RAG pipelines, or YAML-based agent orchestration.
+compatibility: Requires the 'qtype-mcp' MCP server to be active for schema lookup and validation.
+metadata:
+  author: qtype
+  version: "1.0"
+allowed-tools: qtype-mcp:*
+---
+
+# QType Architect
+
+Expert assistant for designing and building AI applications using the QType DSL.
+
+## When to use this skill
+
+Activate when users want to:
+- Design QType applications (chatbots, RAG, agents, pipelines)
+- Convert requirements into QType YAML specifications
+- Validate or debug QType code
+- Visualize application architecture
+- Learn QType best practices and patterns
+
+## What is QType?
+
+**QType is a domain-specific language (DSL) for rapid prototyping of AI applications.**
+
+Qtype is a declarative, text-based language that lets you specify *what* your AI application should do, not *how* to do it. You write YAML specifications that describe flows, steps, models, and data transformations, and QType handles the execution.
+
+**Elevator pitch:** QType turns AI application prototypes from days of Python coding into hours of YAML configuration, without sacrificing maintainability or requiring you to learn yet another GUI tool.
+
+## Core Mental Model
+
+Understanding QType requires understanding core concepts and how they relate:
+
+**Think of QType like this:**
+
+**Variables** are your data containers (typed boxes)  
+**Steps** are your transformations (functions on boxes)  
+**Flows** are your pipelines (sequences of transformations)  
+**The DSL** is your specification language (what you write)  
+**The Semantic layer** is your validator (what checks it)  
+**The Interpreter** is your executor (what runs it)  
+
+## Core workflow
+
+### 1. Understand requirements
+
+Clarify the user's goal through targeted questions:
+- What is the overall goal?
+- What are the inputs and outputs?
+- What processing steps are needed?
+- Which models, APIs, or tools are required?
+- Authentication requirements?
+- Conversational vs batch processing?
+
+Prefer inferring reasonable defaults over excessive questions.
+
+### 2. Use MCP tools to research
+
+**CRITICAL: Always use the qtype-mcp server to look up information rather than guessing.**
+
+- Use `list_components` to discover available component types
+- Use `get_component_schema` to get detailed field requirements for specific components
+- Use `search_library` to find relevant documentation and examples
+- Use `list_examples` and `get_example` to see real QType code patterns
+- Use `list_documentation` and `get_documentation` to get specific guides, tutorials, or references
+
+**Don't make assumptions about component fields, syntax, or capabilities - look them up!**
+
+### 3. Design architecture
+
+Map requirements to QType components. For guidance:
+- See [references/patterns.md](references/patterns.md) for common architecture patterns
+- See [references/cheatsheet.md](references/cheatsheet.md) for quick component reference
+- See `assets/*.qtype.yaml` for complete working examples
+
+Use MCP tools to verify component schemas and field requirements as you design.
+
+### 4. Generate and validate
+
+**ALWAYS validate:**
+
+1. Generate complete QType YAML
+2. Call `validate_qtype_yaml` with your YAML
+3. If errors: fix specific issues and validate again
+4. Present validated code to user
+5. If success and you have mermaid preview capability, call `visualize_qtype_architecture` and use the mermaid preview to visalize the result to the user.
+
+**Never skip validation.** Invalid code wastes user time.
+
+### 5. Visualization (Optional)
+
+The `visualize` tool in qtype-mcp converts the qtype yaml to an archiecture diagram.
+If you or the user desires it, use the tool and then open it with either the claude-mermaid mcp (if you are claude code) or the mermaid preview (if you are in vscode).
+If neither of those tools are available, just let the user know and save the mermaid to disk.
+
+### 6. Provide context
+
+After presenting validated code:
+- Explain key architectural decisions
+- Show how to run: `qtype run`, or `qtype validate`, `qtype serve`
+- Point to relevant documentation
+- Suggest next steps or improvements
+
+### 7. Optional Next Steps
+
+If the user desires, or you think they would like it, you can run `qtype serve --reload <yaml_file>` to start the interpreter server. The serve command will print a url, open that in the users web browser so they can see the app.
+
+The `--reload` will refresh each time the yaml is changed.
+
+## Using the qtype-mcp server
+
+**CRITICAL: Use MCP tools constantly - don't guess or rely on memory!**
+
+The qtype-mcp server provides tools for:
+- **Discovery**: Browse components, docs, and examples
+- **Schema lookup**: Get exact field requirements with `get_component_schema`
+- **Search**: Full-text search across all documentation and examples
+- **Validation**: `validate_qtype_yaml` - **Use before every code presentation**
+- **Visualization**: Generate Mermaid diagrams of flows
+- **Code generation**: Convert APIs/Python to QType tools
+
+**Key workflow patterns:**
+1. Unsure about a component? → Use `get_component_schema`
+2. Need an example? → Use `search_library` or `list_examples`
+3. Generated YAML? → **Always call `validate_qtype_yaml`**
+4. Complex flow? → Use `visualize_qtype_architecture`
+
+## Reference materials
+
+See bundled reference files for quick lookup:
+- [references/patterns.md](references/patterns.md) - Common architecture patterns
+- [references/cheatsheet.md](references/cheatsheet.md) - Component quick reference
+- `assets/examples/*.qtype.yaml` for complete working examples.
+
+## Key guidelines
+
+### Self-correction on validation failure
+If validation fails:
+- **Do not guess the fix**
+- Read the error message carefully
+- Call `get_component_schema` for the failing component
+- Compare your YAML against the official schema
+- Make precise corrections based on schema requirements
+
+### Use MCP for everything
+- Component details? → `get_component_schema`
+- Need examples? → `list_examples` + `get_example`
+- Unclear syntax? → `search_library` for relevant docs
+- Best practices? → `get_documentation` for concept guides
+
+### Common pitfalls
+❌ Skipping validation
+❌ Guessing component fields instead of using `get_component_schema`
+❌ Undefined variables
+❌ Missing authentication
+❌ Hardcoding secrets instead of `${ENV_VAR}`
+
+### Respect Virtual Environments
+
+The user is likely running in a virtual environment.  The `qtype` executable may not be in your default `path`.
+
+You may try:
+```
+uv run qtype
+```
+If the user is using `uv`
+
+or `source .venv/bin/activate` before calling `qtype`.
+
+
+## Response format
+
+0. **High-level plan** - Briefly state which components you've chosen and why they fit the user's requirements based on [references/patterns.md](references/patterns.md) and the components listed in the mcp server.
+1. **Brief explanation** (what it does, how data flows)
+2. **Complete validated YAML** (with comments)
+3. **Visualization** (for complex flows)
+4. **Next steps** (`qtype validate`, `qtype run`, `qtype serve`)
+
+## When NOT to use QType
+
+QType doesn't fit:
+- Complex conditional branching (use Python)
+- Pure data pipelines without AI (use Dagster/Airflow)
+- Simple API calls (use SDKs directly)
+
+Be honest if QType isn't the right tool.

qtype/docs/skills/architect/references/cheatsheet.md

@@ -0,0 +1,198 @@
+# Cheatsheet
+
+## Abbreviated Shape Reference
+
+### Application (Root Object)
+```yaml
+id: <string>                    # REQUIRED
+flows: [<Flow>]                 # REQUIRED (at least one)
+models: [<Model>]               # OPTIONAL
+tools: [<Tool>]                 # OPTIONAL
+types: [<CustomType>]           # OPTIONAL
+```
+
+### Flow
+```yaml
+type: Flow
+id: <string>                    # REQUIRED
+steps: [<Step>]                 # REQUIRED (at least one)
+variables: [<Variable>]         # OPTIONAL
+inputs: [<string>]              # OPTIONAL (Variable IDs)
+outputs: [<string>]             # OPTIONAL (Variable IDs)
+interface:                      # OPTIONAL
+  type: <chat|form|agent>
+```
+
+### Variable
+```yaml
+type: Variable
+id: <string>                    # REQUIRED
+value_type: <type>              # REQUIRED (see Type Reference)
+ui:                             # OPTIONAL
+  type: <text-input|text-area|...>
+  label: <string>
+```
+
+**Type Reference:**
+- Primitives: `string`, `int`, `float`, `bool`
+- Collections: `list`, `dict`
+- Built-ins: `ChatMessage`, `Document`, `Embedding`
+- Custom: Any CustomType `id`
+- List syntax: `value_type: list` + `item_type: <type>`
+
+### Model
+```yaml
+type: Model
+id: <string>                    # REQUIRED
+provider: <bedrock|openai|anthropic>  # REQUIRED
+model_id: <string>              # REQUIRED
+auth: <string>                  # OPTIONAL (AuthProvider ID)
+```
+
+### CustomType
+```yaml
+id: <string>                    # REQUIRED
+fields:                         # REQUIRED (at least one)
+  - name: <string>              # REQUIRED
+    field_type: <type>          # REQUIRED
+  - name: <string>
+    field_type: list[<type>]
+```
+
+---
+
+## Abbreviated Step Reference
+
+### LLMInference
+```yaml
+type: LLMInference
+id: <string>                    # REQUIRED
+model: <string>                 # REQUIRED (Model ID)
+inputs: [<string>]              # OPTIONAL (Variable IDs)
+outputs: [<string>]             # OPTIONAL (Variable IDs)
+system_message: <string>        # OPTIONAL
+memory: <string>                # OPTIONAL (Variable ID for chat history)
+```
+
+### Agent
+```yaml
+type: Agent
+id: <string>                    # REQUIRED
+model: <string>                 # REQUIRED (Model ID)
+tools: [<string>]               # REQUIRED (Tool IDs)
+inputs: [<string>]              # OPTIONAL
+outputs: [<string>]             # OPTIONAL
+system_message: <string>        # OPTIONAL
+```
+
+### PromptTemplate
+```yaml
+type: PromptTemplate
+id: <string>                    # REQUIRED
+template: <string>              # REQUIRED (use {{var_id}} syntax)
+inputs: [<string>]              # REQUIRED (Variable IDs to interpolate)
+outputs: [<string>]             # REQUIRED (single Variable ID)
+```
+
+### InvokeFlow
+```yaml
+type: InvokeFlow
+id: <string>                    # REQUIRED
+flow: <string>                  # REQUIRED (Flow ID)
+input_bindings:                 # REQUIRED (even if empty: {})
+  <flow_input_id>: <local_var_id>
+output_bindings:                # REQUIRED (even if empty: {})
+  <local_var_id>: <flow_output_id>
+```
+
+### InvokeTool
+```yaml
+type: InvokeTool
+id: <string>                    # REQUIRED
+tool: <string>                  # REQUIRED (Tool ID)
+input_bindings:                 # REQUIRED
+  <tool_param>: <local_var_id>
+output_bindings:                # REQUIRED
+  <tool_output>: <local_var_id>
+```
+
+### Decoder
+```yaml
+type: Decoder
+id: <string>                    # REQUIRED
+format: <json|xml>              # REQUIRED
+inputs: [<string>]              # REQUIRED (single Variable ID with text)
+outputs: [<string>]             # REQUIRED (single Variable ID)
+```
+
+### Construct
+```yaml
+type: Construct
+id: <string>                    # REQUIRED
+output_type: <string>           # REQUIRED (CustomType ID)
+field_bindings:                 # REQUIRED
+  <field_name>: <var_id>
+outputs: [<string>]             # REQUIRED (single Variable ID)
+```
+
+### VectorSearch
+```yaml
+type: VectorSearch
+id: <string>                    # REQUIRED
+index: <string>                 # REQUIRED (DocumentIndex ID)
+inputs: [<string>]              # REQUIRED (query Variable ID)
+outputs: [<string>]             # REQUIRED (results Variable ID)
+top_k: <int>                    # OPTIONAL (default: 5)
+```
+
+### Explode
+```yaml
+type: Explode
+id: <string>                    # REQUIRED
+inputs: [<string>]              # REQUIRED (list Variable ID)
+outputs: [<string>]             # REQUIRED (single item Variable ID)
+```
+
+### FileSource
+```yaml
+type: FileSource
+id: <string>                    # REQUIRED
+path: <string>                  # REQUIRED
+outputs: [<string>]             # REQUIRED (Variable ID)
+```
+
+## Critical Rules
+
+### ID Rules
+- All `id` fields must be unique within their scope
+- IDs must be valid identifiers (alphanumeric + underscore/hyphen)
+- Reference other objects by their exact `id` string
+
+### Variable Rules
+- Variables in `inputs`/`outputs` must be defined in `variables` list
+- Variables must have `value_type` specified
+- List variables REQUIRE `item_type` field
+- Variable types must match their usage in steps
+
+### Step Rules
+- Steps execute in order within `steps` array
+- Step `inputs` must reference existing variables (from previous steps or flow inputs)
+- Step `outputs` create or update variables for subsequent steps
+- All referenced Model/Tool/Flow/CustomType IDs must exist
+
+### Binding Rules
+- `input_bindings`: Map local variables TO external inputs
+  - Format: `{external_input_name: local_variable_id}`
+- `output_bindings`: Map external outputs TO local variables
+  - Format: `{local_variable_id: external_output_name}`
+- Both must be present even if empty: `{}`
+
+### Template Rules
+- Use `{{variable_id}}` syntax only
+- All variables in template must be in `inputs` list
+- Template must be a single string (use `\n` for newlines)
+
+### Type Rules
+- Decoder outputs must match expected structure
+- Construct `field_bindings` must map to all required CustomType fields
+- List operations (Explode/Collect) require matching list types