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

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

@@ -0,0 +1,483 @@
+# Adding Tools to Your Application
+
+**Time:** 20 minutes  
+**Prerequisites:** [Tutorial 3: Working with Types and Structured Data](03-structured-data.md)  
+**Example:** [`04_tools_and_function_calling.qtype.yaml`](https://github.com/bazaarvoice/qtype/blob/main/examples/tutorials/04_tools_and_function_calling.qtype.yaml)
+
+**What you'll learn:**
+
+* Import pre-built tools from the commons library
+* Use InvokeTool to call Python functions
+* Chain multiple tools with input/output bindings
+* Understand tool references and automatic generation
+
+**What you'll build:** A deadline calculator that uses tools to get the current time, add days, and format the result.
+
+---
+
+## Background: What Are Tools?
+
+Tools extend your QType applications with custom steps.
+Tools are how you plug QType into other existing systems that may not be supported in the shipped interpreter.
+
+**A tool is simply a reference to:**
+- **A Python function** - Call any Python function with typed parameters
+- **An API endpoint** - Make HTTP requests to external services
+
+Tools define their **inputs** (parameters) and **outputs** (return values) with explicit types. 
+
+### The Commons Library
+
+QType provides a [commons library](https://github.com/bazaarvoice/qtype/blob/main/common/tools.qtype.yaml) published on GitHub with pre-built tools for common operations:
+
+- **Time utilities** - Get current time, add/subtract durations, format timestamps
+- **String operations** - Base64 encoding/decoding, text transformations
+- **Data processing** - JSON parsing, field extraction, type conversions
+
+### Automatic Tool Generation
+
+You don't need to write tool YAML files manually! QType can generate them automatically using `qtype convert`:
+
+**From Python modules:**
+```bash
+qtype convert python --module myapp.utils --output tools.qtype.yaml
+```
+
+**From OpenAPI specifications:**
+```bash
+qtype convert openapi --spec api_spec.yaml --output api_tools.qtype.yaml
+```
+
+The converter analyzes function signatures or API schemas and creates properly typed tool definitions. 
+
+---
+
+## Part 1: Import and Use Your First Tool (7 minutes)
+
+### Create Your Application File
+
+Create `04_tools_and_function_calling.qtype.yaml`:
+
+```yaml
+id: deadline_calculator
+description: |
+  Calculates a deadline by adding days to the current timestamp.
+  Demonstrates tool imports, InvokeTool step, and tool chaining.
+```
+
+---
+
+### Import the Commons Library
+
+Add a `references:` section before `flows:`:
+
+```yaml
+# 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
+```
+
+**What this means:**
+
+**`!include`** - YAML directive to load another file's content. `!include` brings in yaml files inside the header. 
+- Can use local paths: `!include ../../common/tools.qtype.yaml`
+- Or remote URLs: `!include https://...` (shown here)
+- Imports all tools, types, and definitions from that file
+
+**`references:` section** - Where you import external components. References can be other applications or lists of models, tools, authorization providers, variables, or custom types.
+
+You can now reference any tool by its `id` (like `qtype.application.commons.tools.get_current_timestamp`).
+
+**Check your work:**
+
+```bash
+qtype validate 04_tools_and_function_calling.qtype.yaml
+```
+
+Should pass ✅ (even with no flows yet - imports are valid)
+
+---
+
+### Define Your Flow Variables
+
+Add the flow structure:
+
+```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
+```
+
+**New types:**
+
+**`datetime` type** - Built-in QType type for timestamps:
+- Represents a point in time (date + time)
+- Stored internally as ISO 8601 strings
+- Automatically converted to/from Python `datetime` objects
+- Tools can accept and return `datetime` values
+
+**Why all these variables?** Each tool transforms data:
+- `current_time` ← output from get_current_timestamp
+- `deadline_time` ← output from timedelta (current_time + days)
+- `deadline_formatted` ← output from format_datetime (pretty string)
+
+Explicit variables make the data flow visible and debuggable.
+
+---
+
+### Add Your First Tool Call
+
+Add this under `steps:`:
+
+```yaml
+    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
+```
+
+**New step type: InvokeTool**
+
+This is your primary way to call tools in QType flows.
+
+**`tool:`** - Full ID of the tool to invoke:
+- Format: `<module_id>.<function_name>` 
+- Must match a tool defined in your imports or application
+- Example: `qtype.application.commons.tools.get_current_timestamp`
+
+**`input_bindings:`** - Maps flow variables to tool parameters:
+- Empty `{}` means no inputs needed
+- This tool has no parameters - it just returns the current time
+
+**`output_bindings:`** - Maps tool outputs to flow variables:
+- `result: current_time` means "take the tool's `result` output and store it in the `current_time` variable"
+- Tool outputs are defined in the tool's YAML definition
+
+**`outputs:`** - Flow-level outputs this step produces:
+- Lists which flow variables this step creates or modifies
+- Used by QType to validate data flow through the pipeline
+
+**Check your work:**
+
+```bash
+qtype validate 04_tools_and_function_calling.qtype.yaml
+```
+
+Should pass ✅
+
+---
+
+## Part 2: Chain Tools with Bindings (8 minutes)
+
+### Add a Constant Variable
+
+Before we can format our datetime, we need to define the format string:
+
+```yaml
+      # 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
+```
+
+**Pattern: Constants in flows**
+
+Since tool `input_bindings` only accept variable names (not literal values), we use PromptTemplate to create constants:
+- Template with no placeholders → constant string
+- `inputs: []` → no dependencies
+- Produces `format_string` variable for later use
+
+**Format string syntax:** Uses Python's `strftime` format codes:
+- `%B` - Full month name (January)
+- `%d` - Day of month (14)
+- `%Y` - 4-digit year (2026)
+- `%I:%M %p` - Time in 12-hour format (03:30 PM)
+
+---
+
+### Add Days with Input Bindings
+
+Now let's use a tool with multiple inputs:
+
+```yaml
+      # 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
+```
+
+**Understanding bindings:**
+
+**Input bindings structure:**
+```yaml
+input_bindings:
+  <tool_parameter_name>: <flow_variable_name>
+```
+
+In this case:
+- Tool parameter `timestamp` ← gets value from flow variable `current_time`
+- Tool parameter `days` ← gets value from flow variable `days_until_due`
+
+The `timedelta` tool definition (from commons library) looks like:
+```yaml
+inputs:
+  timestamp:
+    type: datetime
+  days:
+    type: int
+  hours:
+    type: int
+    optional: true
+  # ... more optional parameters
+```
+
+**Optional parameters:** You only need to bind the required parameters. `timedelta` has many optional parameters (hours, minutes, seconds, weeks), but we only use `days`.
+
+---
+
+### Chain Tools Together
+
+Finally, format the deadline using the output from the previous step:
+
+```yaml
+      # 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
+```
+
+**Check your work:**
+
+```bash
+qtype validate 04_tools_and_function_calling.qtype.yaml
+```
+
+Should pass ✅
+
+---
+
+## Part 3: Test Your Tools (5 minutes)
+
+### Run the Application
+
+```bash
+qtype run -i '{"days_until_due": 3}' 04_tools_and_function_calling.qtype.yaml
+```
+
+**Expected output:**
+
+```json
+{
+  "deadline_formatted": "January 17, 2026 at 03:39 PM UTC"
+}
+```
+
+The exact time will match when you run it, but the date should be 3 days from now.
+
+---
+
+### Try Different Durations
+
+```bash
+# One week deadline
+qtype run -i '{"days_until_due": 7}' 04_tools_and_function_calling.qtype.yaml
+
+# Two weeks
+qtype run -i '{"days_until_due": 14}' 04_tools_and_function_calling.qtype.yaml
+
+# Same day (0 days)
+qtype run -i '{"days_until_due": 0}' 04_tools_and_function_calling.qtype.yaml
+```
+
+---
+
+### Add the `--progress` Flag
+
+For more visibility into tool execution:
+
+```bash
+qtype run -i '{"days_until_due": 3}' 04_tools_and_function_calling.qtype.yaml --progress
+```
+
+You'll see each step execute in real-time:
+
+```
+Step get_current_time     ✔ 1 succeeded
+Step create_format_string ✔ 1 succeeded
+Step add_days            ✔ 1 succeeded
+Step format_deadline     ✔ 1 succeeded
+```
+
+---
+
+## Part 4: Understanding Tools Deeply (Bonus)
+
+### Tool Types and Custom Types
+
+Remember from Tutorial 3 where `calculate_time_difference` returns `TimeDifferenceResultType`? That's a custom type defined in the commons library:
+
+```yaml
+types:
+  - id: TimeDifferenceResultType
+    properties:
+      days: int
+      seconds: int
+      microseconds: int
+      total_hours: float
+      total_minutes: float
+      total_seconds: float
+      total_days: float
+```
+
+If you use `calculate_time_difference`, you can extract fields from its result:
+
+```yaml
+- id: calc_difference
+  type: InvokeTool
+  tool: qtype.application.commons.tools.calculate_time_difference
+  input_bindings:
+    start_time: start
+    end_time: end
+  output_bindings:
+    result: time_diff  # time_diff is now TimeDifferenceResultType
+
+# Later, access fields using FieldExtractor or Construct
+```
+
+---
+
+### Generating Your Own Tools
+
+When you're ready to create custom tools, use `qtype convert`:
+
+**From a Python module:**
+
+```bash
+# Generate tools from all functions in myapp.utils
+qtype convert python --module myapp.utils --output my_tools.qtype.yaml
+```
+
+QType will:
+- Scan all public functions in the module
+- Extract type hints from function signatures
+- Generate tool definitions with proper input/output types
+- Include docstrings as descriptions
+
+**From an OpenAPI spec:**
+
+```bash
+# Generate tools from a REST API
+qtype convert openapi --spec weather_api.yaml --output weather_tools.qtype.yaml
+```
+
+QType will:
+- Parse endpoint definitions
+- Create a tool for each operation
+- Map request parameters to tool inputs
+- Map response schemas to tool outputs
+- Handle authentication configurations
+
+<!-- **Learn more:** See the [How-To Guide: Generate Tools](../How-To%20Guides/Tools/generate-tools.md) for detailed examples. -->
+
+---
+
+## What You've Learned
+
+Congratulations! You've mastered:
+
+✅ **Tool concepts** - References to Python functions or API calls  
+✅ **Importing tools** - Using `!include` with local or remote files  
+✅ **InvokeTool step** - Calling tools with input/output bindings  
+✅ **Input bindings** - Mapping flow variables to tool parameters  
+✅ **Output bindings** - Mapping tool results to flow variables  
+✅ **Tool chaining** - Connecting outputs to inputs across steps  
+✅ **Commons library** - Pre-built tools for common operations  
+✅ **Tool generation** - Using `qtype convert` to create tool definitions  
+
+---
+
+## Next Steps
+
+**Reference the complete example:**
+
+- [`04_tools_and_function_calling.qtype.yaml`](https://github.com/bazaarvoice/qtype/blob/main/examples/tutorials/04_tools_and_function_calling.qtype.yaml) - Full working example
+- [Commons Library](https://github.com/bazaarvoice/qtype/blob/main/common/tools.qtype.yaml) - Browse all available tools
+- [Commons Library Source](https://github.com/bazaarvoice/qtype/blob/v0.1.11/qtype/application/commons/tools.py) - Browse the source of tools.
+<!-- 
+**Learn more:**
+
+- [PythonFunctionTool Reference](../components/PythonFunctionTool.md) - Complete specification
+- [APITool Reference](../components/APITool.md) - External service integration
+- [InvokeTool Step](../components/InvokeTool.md) - Advanced binding patterns
+- [Generate Tools](../How-To%20Guides/Tools/generate-tools.md) - Create your own tools -->
+
+<!-- **Next tutorial:**
+
+- Tutorial 5: Building an AI Agent - Use tools with autonomous LLM decision-making -->
+
+---
+
+## Common Questions
+
+**Q: Can I call multiple tools in parallel?**  
+A: Not directly in a single step. However, if tools don't depend on each other's outputs, QType's execution engine may parallelize them automatically based on dependency analysis.
+
+**Q: What happens if a tool raises an error?**  
+A: The flow stops and returns an error. 
+
+**Q: Can I pass literal values instead of variables to tools?**  
+A: No - `input_bindings` only accepts variable names. Use PromptTemplate to create constant variables, or define them in your flow's input data.
+
+**Q: How do I know what parameters a tool accepts?**  
+A: Check the tool's YAML definition (in the commons library or your generated file). It lists all `inputs` with their types and whether they're optional.
+
+**Q: Can tools modify variables or have side effects?**  
+A: Tools are functional - they take inputs and return outputs without modifying flow state. Side effects (like writing files or calling APIs) happen inside the tool implementation, but they don't affect other flow variables.
+
+**Q: What's the difference between InvokeTool and Agent?**  
+A: **InvokeTool** explicitly calls a specific tool with defined bindings. **Agent** gives an LLM access to multiple tools and lets it decide which to use and when. Use InvokeTool for deterministic workflows, Agent for autonomous decision-making.

docs/Tutorials/index.md

@@ -0,0 +1,92 @@
+# Installation
+
+QType can be installed in two different ways depending on your needs:
+
+## Interpreter Package Installation (Recommended)
+
+For full functionality including the ability to execute QType flows, serve them as APIs, and launch user experiences, install with the interpreter extra:
+
+=== "uv"
+    ```sh
+    uv add qtype[interpreter]
+    ```
+
+=== "pip"
+    ```bash
+    pip install qtype[interpreter]
+    ```
+
+
+## Base Package Installation
+
+The base QType package provides core functionality for defining, validating, and generating schemas for QType specifications:
+
+=== "uv"
+    ```sh
+    uv add qtype
+    ```
+
+=== "uvx"
+    ```sh
+    uvx qtype
+    ```
+
+=== "pip"
+    ```sh
+    pip install qtype
+    ```
+
+### What's included in the base package:
+
+- **Schema validation**: Validate your QType YAML files against the specification
+- **File conversion**: Convert between different QType formats
+- **Core DSL components**: Define models, prompts, tools, and flows
+- **Basic CLI commands**: `validate`, `generate`, `convert`
+
+
+### Additional capabilities with the interpreter package:
+
+- **Flow execution**: Run QType flows locally with the `run` command
+- **UI and API serving**: Serve QType flows as web UI and APIs with the `serve` command
+- **Multiple model Providers**: Support for AWS Bedrock, OpenAI, and other LLM providers
+- **Embeddings and Detrieval**: Built-in support for vector embeddings and retrieval
+- **Observability**: Integrated telemetry and tracing with OpenTelemetry
+
+### Additional dependencies:
+
+(These are installed by default with the `interpreter` package)
+
+- `boto3` - AWS SDK for Bedrock and other AWS services
+- `fastapi` - Web framework for serving APIs
+- `uvicorn` - ASGI server for FastAPI
+- `llama-index` - LLM application framework with embeddings support
+- `arize-phoenix-otel` - OpenTelemetry instrumentation
+
+## Requirements
+
+- **Python 3.10 or higher**
+- Operating systems: macOS, Linux, Windows
+
+## Verification
+
+After installation, verify that QType is working correctly:
+
+```bash
+# Check installation
+qtype --help
+
+# Validate a sample spec (base package)
+qtype validate examples/hello_world.qtype.yaml
+```
+
+Then, edit `.env` and put in your `OPENAI_KEY`:
+```
+OPENAI_KEY=sk-proj....
+```
+
+and run the example flow:
+```
+# Run a flow (interpreter package only)
+qtype run -i '{"question":"What is your quest?"}'  examples/hello_world.qtype.yaml
+```
+

docs/components/APIKeyAuthProvider.md

@@ -0,0 +1,7 @@
+### APIKeyAuthProvider
+
+API key-based authentication provider.
+
+- **type** (`Literal`): (No documentation available.)
+- **api_key** (`str | SecretReference`): API key for authentication.
+- **host** (`str | None`): Base URL or domain of the provider.

docs/components/APITool.md

@@ -0,0 +1,10 @@
+### APITool
+
+Tool that invokes an API endpoint.
+
+- **type** (`Literal`): (No documentation available.)
+- **endpoint** (`str`): API endpoint URL to call.
+- **method** (`str`): HTTP method to use (GET, POST, PUT, DELETE, etc.).
+- **auth** (`Reference[AuthProviderType] | str | None`): Optional AuthorizationProvider for API authentication.
+- **headers** (`dict[str, str]`): Optional HTTP headers to include in the request.
+- **parameters** (`dict[str, ToolParameter]`): Output parameters produced by this tool.

docs/components/AWSAuthProvider.md

@@ -0,0 +1,13 @@
+### AWSAuthProvider
+
+AWS authentication provider supporting multiple credential methods.
+
+- **type** (`Literal`): (No documentation available.)
+- **access_key_id** (`str | SecretReference | None`): AWS access key ID.
+- **secret_access_key** (`str | SecretReference | None`): AWS secret access key.
+- **session_token** (`str | SecretReference | None`): AWS session token for temporary credentials.
+- **profile_name** (`str | None`): AWS profile name from credentials file.
+- **role_arn** (`str | None`): ARN of the role to assume.
+- **role_session_name** (`str | None`): Session name for role assumption.
+- **external_id** (`str | None`): External ID for role assumption.
+- **region** (`str | None`): AWS region.

docs/components/AWSSecretManager.md

@@ -0,0 +1,5 @@
+### AWSSecretManager
+
+Configuration for AWS Secrets Manager.
+
+- **type** (`Literal`): (No documentation available.)

docs/components/Agent.md

@@ -0,0 +1,6 @@
+### Agent
+
+Defines an agent that can perform tasks and make decisions based on user input and context.
+
+- **type** (`Literal`): (No documentation available.)
+- **tools** (`list[Reference[ToolType] | str]`): List of tools available to the agent.

docs/components/Aggregate.md

@@ -0,0 +1,8 @@
+### Aggregate
+
+A terminal step that consumes an entire input stream and produces a single
+summary message with success/error counts.
+
+- **type** (`Literal`): (No documentation available.)
+- **cardinality** (`Literal`): (No documentation available.)
+- **outputs** (`list[Reference[Variable] | str]`): References to the variables for the output. There should be one and only one output with type AggregateStats

docs/components/AggregateStats.md

@@ -0,0 +1,7 @@
+### AggregateStats
+
+A standard, built-in representation of aggregate statistics.
+
+- **num_successful** (`int`): The count of successful messages processed.
+- **num_failed** (`int`): The count of failed messages processed.
+- **num_total** (`int`): The total count of messages processed.

docs/components/Application.md

@@ -0,0 +1,22 @@
+### Application
+
+Defines a complete QType application specification.
+An Application is the top-level container of the entire
+program in a QType YAML file. It serves as the blueprint for your
+AI-powered application, containing all the models, flows, tools, data sources,
+and configuration needed to run your program. Think of it as the main entry
+point that ties together all components into a cohesive,
+executable system.
+
+- **id** (`str`): Unique ID of the application.
+- **description** (`str | None`): Optional description of the application.
+- **memories** (`list[Memory]`): List of memory definitions used in this application.
+- **models** (`list[ModelType]`): List of models used in this application.
+- **types** (`list[CustomType]`): List of custom types defined in this application.
+- **flows** (`list[Flow]`): List of flows defined in this application.
+- **auths** (`list[AuthProviderType]`): List of authorization providers used for API access.
+- **tools** (`list[ToolType]`): List of tools available in this application.
+- **indexes** (`list[IndexType]`): List of indexes available for search operations.
+- **secret_manager** (`SecretManagerType | None`): Optional secret manager configuration for the application.
+- **telemetry** (`TelemetrySink | None`): Optional telemetry sink for observability.
+- **references** (`list[Document]`): List of other q-type documents you may use. This allows modular composition and reuse of components across applications.

docs/components/AuthorizationProvider.md

@@ -0,0 +1,6 @@
+### AuthorizationProvider
+
+Base class for authentication providers.
+
+- **id** (`str`): Unique ID of the authorization configuration.
+- **type** (`str`): Authorization method type.

docs/components/AuthorizationProviderList.md

@@ -0,0 +1,5 @@
+### AuthorizationProviderList
+
+Schema for a standalone list of authorization providers.
+
+- **root** (`list[APIKeyAuthProvider | BearerTokenAuthProvider | AWSAuthProvider | OAuth2AuthProvider | VertexAuthProvider]`): (No documentation available.)

docs/components/BearerTokenAuthProvider.md

@@ -0,0 +1,6 @@
+### BearerTokenAuthProvider
+
+Bearer token authentication provider.
+
+- **type** (`Literal`): (No documentation available.)
+- **token** (`str | SecretReference`): Bearer token for authentication.

docs/components/BedrockReranker.md

@@ -0,0 +1,8 @@
+### BedrockReranker
+
+Reranks documents using an AWS Bedrock model.
+
+- **type** (`Literal`): (No documentation available.)
+- **auth** (`Reference[AWSAuthProvider] | str | None`): AWS authorization provider for Bedrock access.
+- **model_id** (`str`): Bedrock model ID to use for reranking. See https://docs.aws.amazon.com/bedrock/latest/userguide/rerank-supported.html
+- **num_results** (`int | None`): Return this many results.