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

docs/Concepts/mental-model-and-philosophy.md

@@ -0,0 +1,363 @@
+# Mental Model & Philosophy
+
+## 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: The Three Primitives
+
+Understanding QType requires understanding three 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)  
+
+**You declare what you want, QType handles how to do it.**
+
+
+### 1. Variables: The Data
+
+**Variables are typed data containers** that hold values as they move through your application.
+
+```yaml
+variables:
+  - id: question          # A variable named "question"
+    type: text            # It holds text data
+  - id: answer
+    type: text
+  - id: reviews
+    type: list[text]      # Can hold complex types like lists
+```
+
+**Key insight:** Variables are *declared* upfront, making data flow explicit before runtime.
+
+**Types matter:** Every variable has a type (primitive like `text`/`int`, domain-specific like `ChatMessage`, or custom types you define). 
+
+---
+
+### 2. Steps: The Transformations
+
+**Steps are individual operations** that take input variables and produce output variables.
+
+```yaml
+steps:
+  - id: format_prompt
+    type: PromptTemplate
+    template: "Answer this: {question}"
+    inputs:
+      - question      # Consumes the question variable
+    outputs:
+      - prompt        # Produces a prompt variable
+```
+
+**Each step:**
+- Has a specific type (`PromptTemplate`, `LLMInference`, `InvokeTool`, etc.)
+- Declares which variables it reads (`inputs`)
+- Declares which variables it produces (`outputs`)
+- Performs one focused transformation
+
+**Key insight:** Steps are pure transformations. Everything is declared, making flows inspectable and debuggable.
+
+**Step types are extensible:** QType ships with ~25 step types (LLMs, tools, data processing, RAG operations), and you can write custom tools for domain-specific operations.
+
+---
+
+### 3. Flows: The Orchestration
+
+**Flows are sequences of steps** that form complete processing pipelines.
+
+```yaml
+flows:
+  - id: answer_question
+    inputs:
+      - question          # What comes in
+    outputs:
+      - answer            # What goes out
+    variables:            # All data containers
+      - id: question
+        type: text
+      - id: prompt
+        type: text
+      - id: answer
+        type: text
+    steps:
+      - id: format_prompt
+        type: PromptTemplate
+        # ... (transforms question → prompt)
+      - id: get_answer
+        type: LLMInference
+        # ... (transforms prompt → answer)
+```
+
+**Flows are data pipelines:**
+- They receive input variables
+- Pass them through a sequence of steps
+- Each step transforms data from one form to another
+- Final outputs are extracted and returned
+
+**Key insight:** Flows are *stateless* by default - each execution is independent. Use Memory or external storage for stateful applications (like chatbots). This makes flows easy to reason about, test, and parallelize.
+
+---
+
+## The Data Flow Model
+
+Here's how data moves through a QType application:
+
+```
+Input Variables
+     ↓
+   Step 1 (transforms A → B)
+     ↓
+   Step 2 (transforms B → C)
+     ↓
+   Step 3 (transforms C → D)
+     ↓
+Output Variables
+```
+
+**Linear execution:** Steps run sequentially in declaration order. Each step waits for its inputs to be available. Parallelism is supported for multiple inputs.
+
+**1-to-many cardinality:** Some steps (like `Explode`) can produce multiple outputs for one input, creating fan-out patterns. Other steps (like `Collect`) aggregate many inputs into one output. This enables batch processing patterns.
+
+---
+
+## Architecture: The Three Layers
+
+QType is built in three distinct layers, each with a specific responsibility:
+
+```
+┌─────────────────────────────────────────────┐
+│              CLI Commands                   │ 
+│         (validate, run, serve)              │
+├─────────────────────────────────────────────┤
+│             Interpreter                     │
+│         (execution engine)                  │
+├─────────────────────────────────────────────┤
+│              Semantic                       │
+│         (linking & validation)              │
+├─────────────────────────────────────────────┤
+│                DSL                          │
+│          (core data models)                 │
+└─────────────────────────────────────────────┘
+```
+
+### Layer 1: DSL (Domain-Specific Language)
+
+**Responsibility:** Define the data structures that represent QType specifications.
+
+- Pure Pydantic models
+- No business logic, just structure
+- Represents YAML as typed Python objects
+- References are strings (like `model: "gpt-4"`)
+
+**Example:** The `Flow` model has `steps: list[Step]`, `variables: list[Variable]`, etc.
+
+---
+
+### Layer 2: Semantic
+
+**Responsibility:** Transform DSL objects into resolved, validated representations.
+
+**The pipeline:**
+
+1. **Parse** - Load YAML and build DSL objects
+2. **Link** - Resolve string references to actual objects (`"gpt-4"` → `Model` object)
+3. **Resolve** - Build semantic IR (intermediate representation) where all IDs become object references
+4. **Check** - Validate semantic rules (no missing variables, types match, etc.)
+
+**Key insight:** This layer catches errors *before* execution. You get fast feedback without running expensive LLM calls.
+
+**Symbol table:** During linking, QType builds a map of all components by ID.
+
+---
+
+### Layer 3: Interpreter
+
+**Responsibility:** Execute flows by running steps with real resources.
+
+- Creates executors for each step type
+- Manages resources (models, indexes, caches)
+- Handles streaming and progress tracking
+- Emits telemetry events
+- Orchestrates async execution
+
+**Executor pattern:** Each step type has an executor class (`LLMInferenceExecutor`, `InvokeToolExecutor`, etc.) that knows how to run that specific operation. Executors receive `ExecutorContext` with cross-cutting concerns like auth, telemetry, and progress tracking.
+
+**Key insight:** The interpreter layer is optional - you could generate code from semantic IR, compile to a different runtime, or build alternative execution strategies. The DSL and semantic layers are independent of execution.
+
+---
+
+## The Loading Pipeline
+
+When you run `qtype validate` or `qtype run`, here's what happens:
+
+```
+YAML File
+    ↓
+1. Load (expand env vars, includes)
+    ↓
+2. Parse (YAML → DSL models)
+    ↓
+3. Link (resolve ID references)
+    ↓
+4. Resolve (DSL → Semantic IR)
+    ↓
+5. Check (validate semantics)
+    ↓
+6. Execute (run the flow)
+```
+Each stage builds on the previous, and errors are caught as early as possible.
+
+---
+
+## Philosophy: Why QType Exists
+
+### 1. **Code is a Liability**
+
+Every line of Python code you write is something you have to maintain, debug, and explain to colleagues. QType shifts complexity from *imperative code* (how to do it) to *declarative specification* (what to do).
+
+**Example:** Instead of writing Python to:
+- Initialize an LLM client
+- Format prompts
+- Handle streaming
+- Parse JSON responses
+- Construct typed objects
+- Log telemetry
+
+You write YAML that *declares* these operations, and QType handles the implementation.
+
+---
+
+### 2. **Modularity and Composability**
+
+QType applications are built from composable pieces:
+- **Flows** can invoke other flows
+- **Tools** are reusable functions
+- **Types** define domain models
+- **Models** and **Memories** are shared resources
+
+You can build libraries of flows, tools, and types that work together like Lego blocks.
+
+---
+
+### 3. **Traceability and Observability**
+
+Because everything is declared:
+- You can visualize the entire application structure
+- Trace data flow through the system
+- Emit structured telemetry
+- Understand what's happening without reading code
+
+Otel Observability is supported by default.
+
+QType makes the *implicit* (hidden in code) *explicit* (visible in YAML).
+
+---
+
+### 4. **Rapid Iteration**
+
+Changing a QType application is fast:
+- Edit YAML
+- Validate
+- Run
+
+No recompiling, no virtual environment issues, no import errors. The feedback loop is seconds, not minutes.
+
+---
+
+## What QType Is NOT
+
+### ❌ Not a Low-Code/No-Code Tool
+
+QType is not Flowise, Dify, LangFlow, or similar GUI-based agent builders.
+
+**Why not:**
+- **Audience:** QType targets *engineers* who want text-based specifications they can version control, code review, and integrate into CI/CD
+- **Control:** GUI tools trade precision and flexibility for convenience. QType gives you full control via explicit configuration, and can connect to apis or your code.
+- **Complexity ceiling:** GUIs work great for simple flows but become unwieldy for complex applications with dozens of components. YAML scales better for large systems
+
+**When to use GUI tools:** If you're non-technical or building simple demo flows, GUI tools are faster. If you're an engineer building prototype systems, QType is more maintainable.
+
+---
+
+### ❌ Not a General Data Engineering Tool
+
+**What it is:** QType is not Dagster, Prefect, Airflow, or similar orchestration frameworks.
+
+**Why not:**
+- **Focus:** Data engineering tools excel at *data pipelines* (ETL, batch processing, scheduling). QType excels at *AI workflows* (LLM calls, vector search, tool calling, agents)
+- **Features:** Dagster has sophisticated scheduling, retries, dependency management, and data lineage. QType has LLM abstractions, type systems for AI data (ChatMessage, RAGDocument), and streaming support
+- **Overlap:** Both can process data in pipelines, but the primitives are different
+
+**When to use data engineering tools:** If your workflow is primarily data transformation, aggregation, and movement without AI components, use Dagster/Airflow. They're better at traditional ETL.
+
+**When to use QType:** If your workflow involves LLMs, embeddings, vector search, tool calling, or agents, QType gives you purpose-built primitives. You *could* build these in Dagster, but QType makes it easier.
+
+**Can they coexist?** Yes! Use Dagster to orchestrate data pipelines that feed into QType applications, or use QType flows as Dagster ops for AI-specific processing.
+
+---
+
+## When to Use QType
+
+### ✅ Use QType When:
+
+**You're prototyping AI applications**
+- Quickly try different LLMs, prompts, and flows
+- Iterate on application structure without Python boilerplate
+- Get validation feedback instantly
+
+**You want type-safe AI workflows**
+- Explicit data flow with typed variables
+- Catch errors before runtime
+- Understand what data flows where
+
+**You're building modular AI systems**
+- Reusable flows, tools, and types
+- Compose applications from libraries
+- Share components across projects
+
+**You value maintainability**
+- YAML specs are easier to review than Python
+- Version control shows exactly what changed
+- Generate documentation automatically
+
+**You need observability**
+- Built-in telemetry and tracing
+- Visualize application structure
+- Understand execution patterns
+
+---
+
+### 🤔 Consider Alternatives When:
+
+**You need complete Python control**
+- Complex branching logic
+- Dynamic behavior based on runtime conditions
+- Integration with Python-specific libraries
+
+**You're building pure data pipelines**
+- No LLM or AI components
+- Traditional ETL operations
+- Dagster/Airflow are better fits
+
+**You prefer visual tools**
+- GUI-based development
+- Non-technical users
+- Flowise/Dify are more appropriate
+
+**Your workflow is extremely simple**
+- Single LLM call, no orchestration
+- Direct API usage is simpler
+- QType adds unnecessary structure
+

docs/Contributing/index.md

@@ -0,0 +1,276 @@
+# Contributing
+
+Welcome to the QType development guide! This document provides comprehensive instructions for setting up your development environment and contributing to the project.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Development Environment Setup](#development-environment-setup)
+- [Using QType Commands](#using-qtype-commands)
+- [Running Tests](#running-tests)
+- [Code Quality and Standards](#code-quality-and-standards)
+- [Project Structure](#project-structure)
+- [Making Changes](#making-changes)
+- [Next Steps](#next-steps)
+
+## Prerequisites
+
+- **Python 3.10 or higher** (this project targets Python 3.10+)
+- **uv** package manager (recommended) or **pip**
+- **Git** for version control
+
+## Development Environment Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/yourusername/qtype.git
+cd qtype
+```
+
+### 2. Set Up Python Environment
+
+We recommend using `uv` for dependency management as it's faster and more reliable:
+
+```bash
+# Install uv if you haven't already
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install all dependencies, development tools, and qtype in editable mode
+uv sync --extra interpreter --extra mcp
+```
+
+This single command installs everything you need, including the `qtype` package in editable mode so changes to the source code are immediately reflected.
+
+## Using QType Commands
+
+After installation, activate the virtual environment:
+```bash
+source ./venv/bin/activate
+```
+
+You may see `(qtype)` on yout terminal if you are in bash
+
+After installation, you should be able to run the `qtype` command from anywhere:
+
+```bash
+qtype --help
+```
+
+## Running Tests
+
+The project uses pytest for testing with coverage measurement:
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov=qtype
+
+# Run tests with coverage and generate HTML report
+uv run pytest --cov=qtype --cov-report=html
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Run specific test file
+uv run pytest tests/test_loader_file_inclusion.py
+
+# Run specific test class
+uv run pytest tests/test_loader_file_inclusion.py::TestFileIncludeLoader
+
+# Run specific test method
+uv run pytest tests/test_loader_file_inclusion.py::TestFileIncludeLoader::test_include_yaml_file
+
+# Run tests matching a pattern
+uv run pytest -k "test_include"
+
+# Run tests with specific markers
+uv run pytest -m "not network"  # Skip network tests
+uv run pytest -m "not slow"     # Skip slow tests
+
+# Run tests in parallel (if pytest-xdist is installed)
+uv run pytest -n auto
+```
+
+### Coverage Reports
+
+Coverage reports show:
+- Which lines of code are executed during tests
+- Which lines are missing test coverage  
+- Overall coverage percentage for each module
+- HTML report with line-by-line coverage highlighting
+
+The HTML coverage report (`htmlcov/index.html`) provides the most detailed view, showing exactly which lines need more test coverage.
+
+### Test Markers
+
+The project uses pytest markers to categorize tests:
+- `@pytest.mark.slow`: Tests that take longer to run
+- `@pytest.mark.network`: Tests requiring network access
+
+Skip specific test categories:
+```bash
+# Skip slow tests
+uv run pytest -m "not slow"
+
+# Skip network tests
+uv run pytest -m "not network"
+
+# Run only network tests
+uv run pytest -m "network"
+```
+
+## Code Quality and Standards
+
+This project follows strict Python coding standards:
+
+### Code Style Requirements
+
+- **PEP 8** compliance for all Python code
+- **Type hints** for all function signatures and class attributes
+- **Docstrings** for all public functions, classes, and modules
+- **Clear naming** using snake_case for functions/variables, PascalCase for classes
+- **Line length** limit of 79 characters (as per PEP 8)
+- **f-strings** for string interpolation
+- **Explicit over implicit** code style
+
+#### Format code automatically:
+
+```bash
+# Format with ruff
+ruff format qtype/ tests/
+
+# Lint with ruff
+ruff check qtype/ tests/
+
+# Sort imports
+isort qtype/ tests/
+
+# Type checking with mypy
+mypy qtype/ tests/
+```
+
+#### Pre-commit hooks (Optional but recommended):
+
+```bash
+uv pip install pre-commit
+pre-commit install
+```
+
+Settings are in `.pre-commit-config.yaml`:
+
+
+##  Project Structure
+
+- `qtype/` – Python package for parsing, validating, and interpreting QType specs
+- `examples/` – Example `.qtype.yaml` specs
+- `schema/` – JSON Schema auto-generated from the DSL
+- `docs/` – Documentation 
+- `tests/` – Unit and integration tests
+
+## Making Changes
+
+### Development Workflow
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the coding standards
+
+3. **Write or update tests** for your changes
+
+4. **Run tests** to ensure nothing is broken:
+   ```bash
+   uv run pytest --cov=qtype
+   ```
+
+5. **Check code quality:**
+   ```bash
+   ruff format qtype/ tests/
+   ruff check qtype/ tests/
+   isort qtype/ tests/
+   mypy qtype/
+   ```
+
+6. **Test CLI functionality:**
+   ```bash
+   # Generate schema
+   ptython -m qtype.cli generate-schema -o schema/test.json
+   
+   # Validate example spec
+   ptython -m qtype.cli validate examples/hello_world.qtype.yaml
+   ```
+
+7. **Update documentation** if needed
+
+8. **Commit your changes:**
+   ```bash
+   git add .
+   git commit -m "feat: add your feature description"
+   ```
+
+### How To: Expand The DSL
+
+The core of qtype is the DSL specified in [qtype/dsl/model.py](https://github.com/bazaarvoice/qtype/blob/main/qtype/dsl/model.py). All functionality is rooted in the pydantic classes in that file. To expand the dsl with new classes, types, etc., edit this file. If your new class is a subtype (like a Step, etc) you should make sure you update any unions (like `StepType` etc)
+
+Once you have it to your liking, you can generate the new schema:
+```
+qtype generate schema -o schema/qtype.schema.json 
+```
+
+You can make vscode validate it with your newly generated schema by adding it to your `settings.json`:
+```
+"yaml.schemas" : {
+   "schema/qtype.schema.json": ["qtype.config.yaml", "*.qtype.yaml"],
+},
+```
+
+The semantic version of [qtype/semantic/model.py](https://github.com/bazaarvoice/qtype/blob/main/qtype/semantic/model.py) can also be automatically generated:
+```
+qtype generate semantic-model
+```
+
+Next, update [qtype/semantic/checker.py](https://github.com/bazaarvoice/qtype/blob/main/qtype/semantic/checker.py) to enforce any semantic rules for your step.
+
+Next, make a canonical example of your new type in the `examples` folder (e.g., `examples/new_type_example.qtype.yaml`) and it can be validated:
+```
+qtype validate examples/new_type_example.qtype.yaml
+```
+
+The docstrings in the types are used to update the documentation with:
+```
+qtype generate dsl-docs
+```
+
+Finally, if desired, you can update the interpreter to support your new type. If your new type is a `Step`, you can add an `executor` in the [qtype/interpreter/executors](https://github.com/bazaarvoice/qtype/tree/main/qtype/interpreter/executors) folder and then update the [qtype/interpreter/base/factory.py](https://github.com/bazaarvoice/qtype/blob/main/qtype/interpreter/base/factory.py).
+
+
+### Adding New Dependencies
+
+When adding new dependencies, use uv to add to `pyproject.toml`:
+
+```bash
+uv add <dependency>
+```
+
+Then update the lock file:
+
+```bash
+uv lock
+```
+
+## Next Steps
+
+After setting up your development environment:
+
+1. Explore the `examples/` directory to understand QType specifications
+2. Run the existing tests to ensure everything works
+3. Read the documentation in `docs/`
+4. Look at open issues for contribution opportunities
+5. Start with small improvements or bug fixes
+
+Happy coding! 🚀