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

qtype/docs/How To/Command Line Usage/pass_inputs_on_the_cli.md

@@ -0,0 +1,52 @@
+# Pass Inputs On The CLI
+
+Provide input values to your QType flows directly from the command line using JSON-formatted input data, enabling dynamic parameterization of applications without modifying YAML files.
+
+### CLI Usage
+
+```bash
+# Pass a single input variable
+qtype run -i '{"user_name":"Alice"}' app.qtype.yaml
+
+# Pass multiple input variables
+qtype run -i '{"model_id":"claude-3", "temperature":0.7}' app.qtype.yaml
+
+# Pass complex nested structures
+qtype run -i '{"config":{"max_tokens":1000,"top_p":0.9}}' app.qtype.yaml
+
+# Specify which flow to run with inputs
+qtype run -f analyze_data -i '{"threshold":0.85}' app.qtype.yaml
+```
+
+### Explanation
+
+- **`-i`, `--input`**: Accepts a JSON blob containing key-value pairs where keys match variable names declared in your flow's `inputs` field
+- **JSON format**: Must be valid JSON with double quotes for strings, properly escaped special characters
+- **Flow inputs**: The variables must match those declared in the flow's `inputs` list or the application's `inputs` list
+- **`-f`, `--flow`**: Specifies which flow to run when your application contains multiple flows (defaults to first flow if omitted)
+
+## Complete Example
+
+The [LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md) example demonstrates passing the output file path as a CLI input:
+
+```bash
+# Run the pipeline with a custom output path
+qtype run -i '{"output_path":"results.parquet"}' \
+  --progress \
+  examples/data_processing/dataflow_pipelines.qtype.yaml
+```
+
+The flow declares `output_path` in its inputs:
+
+```yaml
+flows:
+  - name: analyze_reviews
+    inputs:
+      - output_path  # Receives value from CLI -i flag
+```
+
+## See Also
+
+- [Load Multiple Inputs from Files](load_multiple_inputs_from_files.md)
+- [CLI Reference](../../Reference/cli.md)
+- [Gallery: Dataflow Pipelines](../../Gallery/dataflow_pipelines.md)

qtype/docs/How To/Command Line Usage/serve_with_auto_reload.md

@@ -0,0 +1,27 @@
+# Serve Applications with Auto-Reload
+
+Enable automatic reloading of your application when YAML files change during development using the `--reload` flag.
+
+### CLI Command
+
+```bash
+qtype serve --reload my_app.qtype.yaml
+```
+
+### Explanation
+
+- **--reload**: Watches YAML files for changes and automatically restarts the server
+- **Development workflow**: Edit your YAML file, save, and immediately see changes without manual restart
+- **Port option**: Combine with `-p`/`--port` to specify server port (default: 8000)
+
+### Example with Port
+
+```bash
+qtype serve --reload -p 8080 examples/tutorials/01_hello_world.qtype.yaml
+```
+
+## See Also
+
+- [Serve Flows as APIs](../Qtype%20Server/serve_flows_as_apis.md)
+- [Serve Flows as UI](../Qtype%20Server/serve_flows_as_ui.md)
+- [CLI Reference](../../Reference/cli.md)

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

@@ -0,0 +1,40 @@
+# Adjust Concurrency
+
+Control parallel execution of steps to optimize throughput and resource usage using the `concurrency_config` parameter on steps that support concurrent processing.
+
+### QType YAML
+
+```yaml
+steps:
+  - type: LLMInference
+    id: classify
+    model: nova
+    concurrency_config:
+      num_workers: 10         # Process up to 10 items in parallel
+    inputs: [document]
+    outputs: [classification]
+```
+
+### Explanation
+
+- **concurrency_config**: Configuration object for concurrent processing with `num_workers` parameter
+- **num_workers**: Maximum number of concurrent async workers for this step (default: 1)
+
+### Steps Supporting Concurrency
+
+The following step types support `concurrency_config`:
+
+- **LLMInference**: Parallel LLM inference calls
+- **InvokeEmbedding**: Parallel embedding generation
+- **InvokeTool**: Parallel tool invocations
+- **DocToTextConverter**: Parallel document conversion
+- **DocumentSplitter**: Parallel document chunking
+- **DocumentEmbedder**: Parallel chunk embedding
+- **DocumentSearch**: Parallel search queries
+- **BedrockReranker**: Parallel reranking operations
+
+## See Also
+
+- [Step Reference](../../components/Step.md)
+- [Cache Step Results](cache_step_results.md)
+- [Gallery: Dataflow Pipelines](../../Gallery/dataflow_pipelines.md)

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

@@ -0,0 +1,71 @@
+# Cache Step Results
+
+Avoid redundant computation by caching step results on disk, enabling faster re-runs when processing the same inputs.
+
+### QType YAML
+
+```yaml
+steps:
+  - type: LLMInference
+    id: classify
+    model: nova
+    inputs: [prompt]
+    outputs: [category]
+    cache_config:
+      namespace: document_classification  # Logical grouping for cached data
+      version: "1.0"                       # Change to invalidate cache
+      on_error: Drop                       # Don't cache errors (default)
+      ttl: 3600                            # Cache for 1 hour (seconds)
+      compress: false                      # Optionally compress cached data
+```
+
+### Explanation
+
+- **cache_config**: Enables step-level caching with configuration options
+- **namespace**: Logical separation for cache entries (e.g., different projects or data domains)
+- **version**: Cache version string - increment to invalidate all cached results for this step
+- **on_error**: How to handle errors - `Drop` (don't cache errors, default) or `Cache` (cache error results)
+- **ttl**: Time-to-live in seconds before cached entries expire
+- **compress**: Whether to compress cached data (saves disk space, adds CPU overhead)
+
+Cached values are stored in the `.qtype-cache/` directory in your working directory.
+
+### Monitoring Cache Performance
+
+Use the `--progress` flag to see cache hits and misses:
+
+```bash
+qtype run app.qtype.yaml --flow my_flow --progress
+```
+
+First run shows cache misses:
+```
+Step classify    ✔ 5 succeeded ✖ 0 errors ⟳ 0 hits ✗ 5 misses
+```
+
+Subsequent runs show cache hits (much faster):
+```
+Step classify    ✔ 5 succeeded ✖ 0 errors ⟳ 5 hits ✗ 0 misses
+```
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/cache_step_results.qtype.yaml"
+```
+
+Run the example:
+```bash
+# First run - cold cache
+qtype run examples/data_processing/cache_step_results.qtype.yaml --progress -i '{"file_path": "examples/data_processing/sample_documents.jsonl"}'
+
+# Second run - warm cache (much faster)
+qtype run examples/data_processing/cache_step_results.qtype.yaml  --progress -i '{"file_path": "examples/data_processing/sample_documents.jsonl"}'
+
+```
+
+## See Also
+
+- [Step Reference](../../components/Step.md)
+- [Adjust Concurrency](adjust_concurrency.md)
+- [Tutorial: Your First QType Application](../../Tutorials/01-first-qtype-application.md)

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

@@ -0,0 +1,24 @@
+# Decode JSON/XML to Structured Data
+
+Parse string data in JSON or XML format into structured outputs. This is particularly useful for extracting structured data from llm outputs.
+
+### QType YAML
+
+```yaml
+--8<-- "../examples/data_processing/decode_json.qtype.yaml"
+```
+
+### Explanation
+
+- **Decoder**: Step that parses string data (JSON or XML) into structured outputs
+- **format**: The data format to parse - `json` (default) or `xml`
+- **inputs**: String variable containing the encoded data to decode
+- **outputs**: List of variables to extract from the decoded data (field names must match keys in the JSON/XML)
+- **Error handling**: If parsing fails, the step raises returns an error
+- **Markdown cleanup**: Automatically strips markdown code fences (```json, ```xml) if present in the input
+
+## See Also
+
+- [Decoder Reference](../../components/Decoder.md)
+- [CustomType Reference](../../components/CustomType.md)
+- [Tutorial: Structured Data](../../Tutorials/03-structured-data.md)

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

@@ -0,0 +1,40 @@
+# Fan-Out Collections with Explode
+
+Transform a single list input into multiple outputs, one per item, enabling parallel processing of collection elements.
+
+### QType YAML
+
+```yaml
+steps:
+  - type: Explode
+    id: fan_out
+    inputs:
+      - items      # Variable of type list[T]
+    outputs:
+      - item       # Variable of type T
+```
+
+### Explanation
+
+- **Explode**: Takes a single list and yields one output message per item
+- **inputs**: Must be a single variable of type `list[T]`
+- **outputs**: Single variable of the item type `T` (unwrapped from the list)
+- **Fan-out pattern**: Each item is processed independently by downstream steps
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/explode_items.qtype.yaml"
+```
+
+**Run it:**
+```bash
+qtype run examples/data_processing/explode_items.qtype.yaml \
+  -i '{"items": ["apple", "banana", "cherry"]}'
+```
+
+## See Also
+
+- [Gather Results into a List](gather_results.md)
+- [Explode Reference](../../components/Explode.md)
+- [Adjust Concurrency](adjust_concurrency.md)

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

@@ -0,0 +1,68 @@
+# Gather Results into a List
+
+Combine fan-out processing results into a single list while preserving variables that have the same value across all messages (common ancestors).
+
+### QType YAML
+
+```yaml
+variables:
+  - id: processed_product
+    type: text
+  - id: all_processed
+    type: list[text]
+
+steps:
+  - type: Collect
+    id: aggregate
+    inputs: [processed_product]
+    outputs: [all_processed]
+```
+
+### Explanation
+
+- **Collect**: Gathers all input values from multiple messages into a single list output
+- **Common ancestors**: Only variables that have the exact same value across ALL input messages are preserved in the output message
+- **Fan-out pattern**: Typically used after `Explode` to reverse the fan-out and accumulate results
+- **Single output**: Always produces exactly one output message containing the accumulate list
+
+### Understanding Common Ancestors
+
+If you have these three messages flowing into `Collect`:
+
+```
+Message 1: {category: "Electronics", region: "US", product: "Phone", processed: "Processed: Phone"}
+Message 2: {category: "Electronics", region: "US", product: "Laptop", processed: "Processed: Laptop"}
+Message 3: {category: "Electronics", region: "US", product: "Tablet", processed: "Processed: Tablet"}
+```
+
+The `Collect` step will output:
+
+```
+{category: "Electronics", region: "US", all_processed: ["Processed: Phone", "Processed: Laptop", "Processed: Tablet"]}
+```
+
+Note that `product` is **not preserved** because it has different values across the messages. Only `category` and `region` (which are identical in all three messages) are included as common ancestors.
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/collect_results.qtype.yaml"
+```
+
+Run the example:
+
+```bash
+qtype run examples/data_processing/collect_results.qtype.yaml \
+  -i '{"category": "Electronics", "region": "US", "products": ["Phone", "Laptop", "Tablet"]}'
+```
+
+Output:
+```
+all_processed: ['Processed: Phone', 'Processed: Laptop', 'Processed: Tablet']
+```
+
+## See Also
+
+- [Explode Collections](explode_collections.md)
+- [Collect Reference](../../components/Collect.md)
+- [Aggregate Reference](../../components/Aggregate.md)

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

@@ -0,0 +1,71 @@
+# Invoke Other Flows
+
+Reuse flows as composable building blocks by invoking them from other flows with input and output bindings.
+
+### QType YAML
+
+```yaml
+flows:
+  # Define reusable flow
+  - type: Flow
+    id: summarize_text
+    variables:
+      - id: input_text
+        type: text
+      - id: output_summary
+        type: text
+    inputs: [input_text]
+    outputs: [output_summary]
+    steps:
+      - type: LLMInference
+        id: summarizer
+        model: my_model
+        inputs: [input_text]
+        outputs: [output_summary]
+
+  # Main flow invokes the reusable flow
+  - type: Flow
+    id: main
+    variables:
+      - id: article
+        type: text
+      - id: summary
+        type: text
+    inputs: [article]
+    outputs: [summary]
+    steps:
+      - type: InvokeFlow
+        id: get_summary
+        flow: summarize_text           # Reference to flow by ID
+        input_bindings:
+          input_text: article          # Map flow input to step variable
+        output_bindings:
+          output_summary: summary      # Map flow output to step variable
+```
+
+### Explanation
+
+- **InvokeFlow**: Step type that executes another flow with variable mapping
+- **flow**: ID of the flow to invoke (must be defined in the application)
+- **input_bindings**: Maps flow input variables to the invoking step's variables (format: `flow_input_name: step_variable_name`)
+- **output_bindings**: Maps flow output variables to the invoking step's variables (format: `flow_output_name: step_variable_name`)
+- **Reusability**: Flows can be invoked multiple times with different bindings
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/invoke_other_flows.qtype.yaml"
+```
+
+**Run it:**
+```bash
+qtype run examples/data_processing/invoke_other_flows.qtype.yaml \
+  --flow main \
+  --input '{"article_text": "Your article text here..."}'
+```
+
+## See Also
+
+- [InvokeFlow Reference](../../components/InvokeFlow.md)
+- [Flow Reference](../../components/Flow.md)
+- [Use Agent Skills](../Language%20Features/use_agent_skills.md)

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

@@ -0,0 +1,49 @@
+# Load Data from Athena
+
+Query AWS Athena databases using standard SQL with the `SQLSource` step, which supports Athena through SQLAlchemy connection strings and AWS authentication.
+
+### QType YAML
+
+```yaml
+flows:
+  - id: query-athena
+    steps:
+      - type: SQLSource
+        id: load_sales
+        connection: "awsathena+rest://:@athena.us-east-1.amazonaws.com:443/sales_db?s3_staging_dir=s3://my-results-bucket/athena-results/&work_group=primary&catalog_name=some_catalog"
+        query: |
+          SELECT
+            product_id,
+            product_name,
+            total_sales
+          FROM product_sales
+          WHERE total_sales >= :min_sales
+          ORDER BY total_sales DESC
+        inputs:
+          - min_sales
+        outputs:
+          - product_id
+          - product_name
+          - total_sales
+```
+
+### Explanation
+
+- **awsathena+rest**: PyAthena SQLAlchemy dialect for accessing Athena via REST API
+- **Connection string format**: `awsathena+rest://:@athena.{REGION}.amazonaws.com:443/{DATABASE}?s3_staging_dir={S3_PATH}&work_group={WORKGROUP}&catalog_name={CATALOG}"`
+- **s3_staging_dir**: S3 location where Athena writes query results (required by Athena)
+- **work_group**: Athena workgroup name (e.g., `primary`)
+- **auth**: Reference to AWSAuthProvider for AWS credentials
+- **query**: Standard SQL query with parameter substitution using `:parameter_name` syntax
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/athena_query.qtype.yaml"
+```
+
+## See Also
+
+- [SQLSource Reference](../../components/SQLSource.md)
+- [Configure AWS Authentication](../Authentication/configure_aws_authentication.md)
+- [Read Data from SQL Databases](read_sql_databases.md)

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

@@ -0,0 +1,61 @@
+# Read Data from Files
+
+Load structured data from files using FileSource, which supports CSV, JSON, JSONL, and Parquet formats with automatic format detection and type conversion.
+
+### QType YAML
+
+```yaml
+steps:
+  - id: read_data
+    type: FileSource
+    path: batch_inputs.csv
+    outputs:
+      - query
+      - topic
+```
+
+### Explanation
+
+- **FileSource**: Step that reads structured data from files using fsspec-compatible URIs
+- **path**: File path (relative to YAML file or absolute), supports local files and cloud storage (s3://, gs://, etc.)
+- **outputs**: Column names from the file to extract as variables (must match actual column names)
+- **Format detection**: Automatically determined by file extension (.csv, .json, .jsonl, .parquet)
+- **Type conversion**: Automatically converts data to match variable types (primitives, domain types, custom types)
+- **Streaming**: Emits one FlowMessage per row, enabling downstream steps to process data in parallel
+
+### Automatic Type Conversion
+
+FileSource automatically converts data from files to match your variable types:
+
+- **Primitive types** (`int`, `float`, `bool`, `text`): Direct conversion from file data
+- **Domain types** (`ChatMessage`, `SearchResult`, etc.): Validated from dict/object columns
+- **Custom types**: Your defined types are validated and instantiated from dict/object columns
+
+**Format Recommendations:**
+
+- **CSV**: Best for simple primitive types (strings, numbers, booleans)
+- **JSON/JSONL**: Recommended for nested objects, custom types, and domain types
+- **Parquet**: Best for large datasets with mixed types and efficient storage
+
+**Example with Custom Types (JSON format):**
+
+```json
+[
+  {"person": {"name": "Alice", "age": 30}, "score": 95},
+  {"person": {"name": "Bob", "age": 25}, "score": 87}
+]
+```
+
+JSON preserves nested objects, making it ideal for complex types. CSV stores everything as strings, requiring nested objects to be serialized as JSON strings within the CSV.
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/read_file.qtype.yaml"
+```
+
+## See Also
+
+- [FileSource Reference](../../components/FileSource.md)
+- [Load Multiple Inputs from Files](../Command%20Line%20Usage/load_multiple_inputs_from_files.md)
+- [Write Data to File](write_data_to_file.md)

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

@@ -0,0 +1,46 @@
+# Read Data from SQL Databases
+
+Query relational databases and process results row-by-row using the `SQLSource` step, which supports any database accessible via SQLAlchemy connection strings.
+
+### QType YAML
+
+```yaml
+steps:
+  - type: SQLSource
+    id: load_reviews
+    connection: "sqlite:///data/reviews.db"
+    query: |
+      SELECT
+        review_id,
+        product_name,
+        rating,
+        review_text
+      FROM product_reviews
+      WHERE rating >= 4
+      ORDER BY review_id
+    outputs:
+      - review_id
+      - product_name
+      - rating
+      - review_text
+```
+
+### Explanation
+
+- **SQLSource**: Step type that executes SQL queries and emits one message per database row
+- **connection**: SQLAlchemy-format connection string (e.g., `sqlite:///path.db`, `postgresql://user:pass@host/db`)
+- **query**: SQL query to execute; column names must match output variable IDs
+- **outputs**: Variables to populate from query result columns (order must match SELECT clause)
+- **auth**: Optional reference to AuthorizationProvider for database credentials
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/dataflow_pipelines.qtype.yaml"
+```
+
+## See Also
+
+- [SQLSource Reference](../../components/SQLSource.md)
+- [Load Data from Athena](load_data_from_athena.md)
+- [Read Data from Files](read_data_from_files.md)

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

@@ -0,0 +1,39 @@
+# Write Data to a File
+
+Write flow data to files using the `FileWriter` step, which accumulates all messages and outputs data in Parquet format using fsspec-compatible URIs.
+
+### QType YAML
+
+```yaml
+steps:
+  - type: FileWriter
+    id: write_results
+    path: output_path          # Variable containing file path
+    inputs:
+      - review_id
+      - product_name
+      - rating
+      - llm_analysis
+      - output_path
+    outputs:
+      - result_file
+```
+
+### Explanation
+
+- **FileWriter**: Batches all incoming messages and writes them as a single Parquet file
+- **path**: fsspec-compatible URI (can be a `ConstantPath`, Variable reference, or string) for the output file location
+- **inputs**: Variables from FlowMessages to include as columns in the output file
+- **outputs**: Variable containing the path where data was written (useful for passing to downstream steps)
+- **batch_config**: Optional configuration for batch size. This defaults to max_int (i.e., processes all messages into one file). If you change it, you will get multiple files.
+
+## Complete Example
+See the [LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md) gallery example.
+
+
+
+## See Also
+
+- [FileWriter Reference](../../components/FileWriter.md)
+- [Read Data from Files](read_data_from_files.md)
+- [Gallery: Dataflow Pipelines](../../Gallery/dataflow_pipelines.md)

qtype/docs/How To/Invoke Models/call_large_language_models.md

@@ -0,0 +1,51 @@
+# Call Large Language Models
+
+Send text input to an LLM and receive a response using the `LLMInference` step with a system message and configurable model parameters like temperature and max_tokens.
+
+### QType YAML
+
+```yaml
+models:
+  - type: Model
+    id: nova_lite
+    provider: aws-bedrock
+    model_id: amazon.nova-lite-v1:0
+    inference_params:
+      temperature: 0.7
+      max_tokens: 500
+
+steps:
+  - type: LLMInference
+    id: assistant
+    model: nova_lite
+    system_message: "You are a helpful assistant"
+    inputs: [text]
+    outputs: [response]
+```
+
+### Explanation
+
+- **model**: Reference to a Model resource defining the LLM provider and model ID
+- **inference_params**: Configuration for model behavior (temperature, max_tokens, top_p, etc.)
+- **temperature**: Controls randomness (0.0 = deterministic, 1.0 = creative)
+- **max_tokens**: Maximum number of tokens in the response
+- **system_message**: Sets the assistant's persona and instructions for all requests
+- **inputs**: Variables containing the user's text input to the LLM
+- **outputs**: Variables where the LLM's response will be stored (must be type `text` or `ChatMessage`)
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/invoke_models/simple_llm_call.qtype.yaml"
+```
+
+Run with:
+```bash
+qtype run simple_llm_call.qtype.yaml --input '{"text": "What is the capital of France?"}'
+```
+
+## See Also
+
+- [LLMInference Reference](../../components/LLMInference.md)
+- [Model Reference](../../components/Model.md)
+- [Tutorial: Conversational Chatbot](../../Tutorials/02-conversational-chatbot.md)