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

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_inputs_from_files.md)
+- [Use Session Inputs for Sticky Variables](../Language%20Features/use_session_inputs.md)
+- [Example: LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md)

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

@@ -0,0 +1,26 @@
+# 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 Command Reference](../../Reference/CLI.md#serve)
+- [Tutorial: Hello World](../../Tutorials/01_hello_world.md)

docs/How To/Data Processing/adjust_concurrency.md

@@ -0,0 +1,41 @@
+# 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
+
+- [LLMInference Reference](../../components/LLMInference.md)
+- [InvokeEmbedding Reference](../../components/InvokeEmbedding.md)
+- [DocumentEmbedder Reference](../../components/DocumentEmbedder.md)
+- [LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md)

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
+
+- [LLMInference Reference](../../components/LLMInference.md)
+- [Adjust Concurrency](adjust_concurrency.md)
+- [Tutorial: Your First QType Application](../../Tutorials/your_first_qtype_application.md)

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: Working with Types and Structured Data](../../Tutorials/structured_data.md)

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
+
+- [Aggregate Data using Collect](./aggregate_data.md)
+- [Explode Reference](../../components/Explode.md)
+- [Adjust Concurrency](./adjust_concurrency.md)

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 aggregate results
+- **Single output**: Always produces exactly one output message containing the aggregated 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 for Fan-Out Processing](explode_collections.md)
+- [Collect Reference](../../components/Collect.md)
+- [Explode Reference](../../components/Explode.md)

docs/How To/Data Processing/read_data_from_files.md

@@ -0,0 +1,35 @@
+# Read Data from Files
+
+Load structured data from files using FileSource, which supports CSV, JSON, JSONL, and Parquet formats with automatic format detection based on file extension.
+
+### 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)
+- **Streaming**: Emits one FlowMessage per row, enabling downstream steps to process data in parallel
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/data_processing/read_file.qtype.yaml"
+```
+
+## See Also
+
+- [FileSource Reference](../../components/FileSource.md)
+- [Aggregate Reference](../../components/Aggregate.md)
+- [Example: Batch Processing](../../Gallery/Data%20Processing/batch_processing.md)

docs/How To/Data Processing/read_sql_databases.md

@@ -0,0 +1,47 @@
+# 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)
+- [FileSource Reference](../../components/FileSource.md)
+- [Tutorial: Working with Types and Structured Data](../../Tutorials/working_with_types_and_structured_data.md)
+- [Example: Dataflow Pipeline](../../Gallery/Data%20Processing/dataflow_pipelines.md)

docs/How To/Data Processing/write_data_to_file.md

@@ -0,0 +1,40 @@
+# 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)
+- [Read SQL Databases](read_sql_databases.md)
+- [LLM Processing Pipelines](../../Gallery/dataflow_pipelines.md)

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: Build a Conversational Interface](../../Tutorials/conversational_interface.md)

docs/How To/Invoke Models/create_embeddings.md

@@ -0,0 +1,49 @@
+# Create Embeddings
+
+Generate vector embeddings from text using an embedding model, useful for semantic search, similarity comparisons, and RAG applications.
+
+### QType YAML
+
+```yaml
+models:
+  - type: EmbeddingModel
+    id: titan_embed
+    provider: aws-bedrock
+    model_id: amazon.titan-embed-text-v2:0
+    dimensions: 1024
+
+flows:
+  - type: Flow
+    id: main
+    steps:
+      - type: InvokeEmbedding
+        id: embed_text
+        model: titan_embed
+        inputs: [text]
+        outputs: [embedding]
+```
+
+### Explanation
+
+- **EmbeddingModel**: Defines an embedding model configuration with provider and dimensions
+- **dimensions**: Size of the embedding vector (must match model output, e.g., 1024 for Titan v2)
+- **InvokeEmbedding**: Step type that generates embeddings from input text
+- **Embedding**: Output type containing the vector array and metadata
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/invoke_models/create_embeddings.qtype.yaml"
+```
+
+Run with:
+```bash
+qtype run examples/invoke_models/create_embeddings.qtype.yaml \
+  -i '{"text": "Your text here"}'
+```
+
+## See Also
+
+- [InvokeEmbedding Reference](../../components/InvokeEmbedding.md)
+- [EmbeddingModel Reference](../../components/EmbeddingModel.md)
+- [Tutorial: Build a RAG System](../../Tutorials/building_rag_system.md)

docs/How To/Invoke Models/reuse_prompts_with_templates.md

@@ -0,0 +1,39 @@
+# Reuse Prompts with Templates
+
+Define reusable prompt templates with variable placeholders using the `PromptTemplate` step, enabling consistent prompt formatting and dynamic content substitution.
+
+### QType YAML
+
+```yaml
+steps:
+  - id: create_prompt
+    type: PromptTemplate
+    template: |
+      Analyze this product review in 1-2 sentences. Include:
+      - Overall sentiment (positive/negative/mixed)
+      - Key themes or points
+
+      Product: {product_name}
+      Rating: {rating}/5
+      Review: {review_text}
+    inputs:
+      - product_name
+      - rating
+      - review_text
+    outputs:
+      - analysis_prompt
+```
+
+### Explanation
+
+- **type: PromptTemplate**: Step that formats strings with variable placeholders using Python's `str.format()` syntax
+- **template**: String with `{variable_name}` placeholders that get replaced with actual values from inputs
+- **inputs**: Variables whose values will be substituted into the template placeholders
+- **outputs**: Single variable containing the formatted prompt string ready for LLM inference
+
+## See Also
+
+- [PromptTemplate Reference](../../components/PromptTemplate.md)
+- [How-To: Include Raw Text from Other Files](../../How%20To/Language%20Features/include_raw_text.md)
+- [How-To: Invoke LLMs with System Messages](invoke_llms_with_system_messages.md)
+- [Tutorial: Your First QType Application](../../Tutorials/your_first_qtype_application.md)

docs/How To/Language Features/include_qtype_yaml.md

@@ -0,0 +1,45 @@
+# Include QType YAML
+
+Organize QType applications into reusable modules by including external YAML files using the `!include` directive, allowing you to share models, tools, authentication providers, and other resources across multiple applications.
+
+### QType YAML
+
+```yaml
+id: my_app
+
+# Include shared resources from other files
+references:
+  - !include common/auth.qtype.yaml
+  - !include common/models.qtype.yaml
+  - !include common/tools.qtype.yaml
+
+flows:
+  - id: main_flow
+    steps:
+      - type: LLMInference
+        id: generate
+        model: shared_gpt4        # References model from included file
+        prompt: "Generate a summary"
+```
+
+**common/models.qtype.yaml:**
+```yaml
+- id: shared_gpt4
+  type: Model
+  provider: openai
+  model_id: gpt-4
+  auth: shared_openai_auth
+```
+
+### Explanation
+
+- **!include**: YAML tag that loads and parses external YAML files, merging their content into the current specification
+- **Relative paths**: File paths are resolved relative to the including YAML file's location
+- **Nested includes**: Included files can include other files, creating a hierarchy of modular components
+- **Remote includes**: Supports URLs (e.g., `!include https://example.com/config.yaml`) via fsspec
+
+## See Also
+
+- [Reference Entities by ID](reference_entities_by_id.md)
+- [Include Raw Text from Other Files](include_raw_text_from_other_files.md)
+- [Application Reference](../../components/Application.md)

docs/How To/Language Features/include_raw_text_from_other_files.md

@@ -0,0 +1,47 @@
+# Include Raw Text from Other Files
+
+Load external text files into your YAML configuration using the `!include_raw` directive, useful for keeping prompts, templates, and long text content in separate files.
+
+### QType YAML
+
+```yaml
+steps:
+  - id: generate_story
+    type: PromptTemplate
+    template: !include_raw story_prompt.txt
+    inputs:
+      - theme
+      - tone
+    outputs:
+      - story
+```
+
+**story_prompt.txt:**
+```txt
+--8<-- "../examples/language_features/story_prompt.txt"
+```
+
+### Explanation
+
+- **!include_raw**: YAML tag that loads the contents of an external file as a raw string
+- **Relative paths**: File paths are resolved relative to the YAML file's location
+- **Template substitution**: The loaded text can contain variable placeholders (e.g., `{theme}`, `{tone}`) that are substituted at runtime
+- **Use cases**: Prompt templates, system messages, documentation, or any text content you want to manage separately
+
+## Complete Example
+
+```yaml
+--8<-- "../examples/language_features/include_raw.qtype.yaml"
+```
+
+
+
+**Run it:**
+```bash
+qtype run include_raw.qtype.yaml -i '{"theme":"a robot learning to paint","tone":"inspirational"}'
+```
+
+## See Also
+
+- [PromptTemplate Reference](../../components/PromptTemplate.md)
+- [Reference Entities by ID](../../How%20To/Language%20Features/reference_entities_by_id.md)