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

qtype/commands/generate.py

@@ -2,24 +2,48 @@ import argparse
 import json
 import logging
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 
 from qtype.dsl.model import Document
 
 logger = logging.getLogger(__name__)
 
 
+def generate_aws_bedrock_models() -> list[dict[str, Any]]:
+    """Generate AWS Bedrock model definitions.
+
+    Returns:
+        List of model definitions for AWS Bedrock models.
+
+    Raises:
+        ImportError: If boto3 is not installed.
+        Exception: If AWS API call fails.
+    """
+    import boto3  # type: ignore[import-untyped]
+
+    logger.info("Discovering AWS Bedrock models...")
+    client = boto3.client("bedrock")
+    models = client.list_foundation_models()
+
+    model_definitions = []
+    for model_summary in models.get("modelSummaries", []):
+        model_definitions.append(
+            {
+                "id": model_summary["modelId"],
+                "provider": "aws-bedrock",
+            }
+        )
+
+    logger.info(f"Discovered {len(model_definitions)} AWS Bedrock models")
+    return model_definitions
+
+
 def run_dump_commons_library(args: argparse.Namespace) -> None:
     """Generate commons library tools and AWS Bedrock models."""
-    import logging
     from pathlib import Path
 
-    from qtype.application.facade import QTypeFacade
     from qtype.dsl.model import Model, ModelList
 
-    logger = logging.getLogger(__name__)
-    facade = QTypeFacade()
-
     try:
         # Generate common tools using convert module functionality
         logger.info("Generating common tools...")
@@ -38,7 +62,7 @@ def run_dump_commons_library(args: argparse.Namespace) -> None:
         # Generate AWS Bedrock models
         logger.info("Generating AWS Bedrock models...")
         try:
-            model_definitions = facade.generate_aws_bedrock_models()
+            model_definitions = generate_aws_bedrock_models()
 
             model_list = ModelList(
                 root=[
@@ -80,6 +104,54 @@ def run_generate_documentation(args: argparse.Namespace) -> None:
     generate_documentation(Path(args.output))
 
 
+def _copy_resource_file(resource, rel_path: Path, output_file: Path) -> None:
+    """Copy a file from a resource directory to an output location."""
+    content = resource.get_file(str(rel_path))
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    output_file.write_text(content, encoding="utf-8")
+
+
+def run_generate_skill(args: argparse.Namespace) -> None:
+    """Generate a Claude skill with QType documentation and examples.
+
+    Args:
+        args: Command-line arguments with 'output' path.
+    """
+    from qtype.base.resources import get_docs_resource, get_examples_resource
+
+    _docs_resource = get_docs_resource()
+    _examples_resource = get_examples_resource()
+
+    output_path = Path(args.output) / "qtype-architect"
+
+    # Copy skill documentation files
+    skills_path = _docs_resource.get_path() / "skills" / "architect"
+    skill_count = 0
+    for skill_file in skills_path.rglob("*.*"):
+        rel_path = skill_file.relative_to(_docs_resource.get_path())
+        _copy_resource_file(
+            _docs_resource,
+            rel_path,
+            output_path / rel_path.relative_to("skills/architect"),
+        )
+        skill_count += 1
+
+    # Copy all example files
+    example_count = 0
+    for yaml_file in _examples_resource.get_path().rglob("*.yaml"):
+        rel_path = yaml_file.relative_to(_examples_resource.get_path())
+        if "legacy" not in rel_path.parts:
+            _copy_resource_file(
+                _examples_resource, rel_path, output_path / "assets" / rel_path
+            )
+            example_count += 1
+
+    logger.info(
+        f"Skill generated at {output_path}: "
+        f"{skill_count} docs, {example_count} examples"
+    )
+
+
 def generate_schema(args: argparse.Namespace) -> None:
     """Generate and output the JSON schema for Document.
 
@@ -87,6 +159,7 @@ def generate_schema(args: argparse.Namespace) -> None:
         args (argparse.Namespace): Command-line arguments with an optional
             'output' attribute specifying the output file path.
     """
+    logger.info("Generating QType DSL JSON schema...")
     schema = Document.model_json_schema()
 
     # Add the $schema property to indicate JSON Schema version
@@ -166,6 +239,7 @@ def parser(subparsers: argparse._SubParsersAction) -> None:
         "-o",
         "--output",
         type=str,
+        default=None,
         help="Output file for the schema (default: stdout)",
     )
     schema_parser.set_defaults(func=generate_schema)
@@ -184,6 +258,20 @@ def parser(subparsers: argparse._SubParsersAction) -> None:
     )
     dsl_parser.set_defaults(func=run_generate_documentation)
 
+    # Parser for generating Agent skills
+    skill_parser = generate_subparsers.add_parser(
+        "skills",
+        help="Generates Agent skills with QType documentation and examples.",
+    )
+    skill_parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default=".claude/skills",
+        help="Output directory for the skills (default: .claude/skills)",
+    )
+    skill_parser.set_defaults(func=run_generate_skill)
+
     # Parser for generating the semantic model
     # only add this if networkx and ruff are installed
     try:

qtype/commands/run.py

@@ -11,11 +11,10 @@ import warnings
 from pathlib import Path
 from typing import Any
 
-import pandas as pd
 from pydantic.warnings import UnsupportedFieldAttributeWarning
 
-from qtype.application.facade import QTypeFacade
 from qtype.base.exceptions import InterpreterError, LoadError, ValidationError
+from qtype.interpreter.converters import read_dataframe_from_file
 
 logger = logging.getLogger(__name__)
 
@@ -29,50 +28,124 @@ for name in ["httpx", "urllib3", "qdrant_client", "opensearch"]:
     logging.getLogger(name).setLevel(logging.WARNING)
 
 
-def read_data_from_file(file_path: str) -> pd.DataFrame:
-    """
-    Reads a file into a pandas DataFrame based on its MIME type.
+def register_telemetry(spec) -> None:
+    """Register telemetry if enabled in the spec."""
+    from qtype.interpreter.telemetry import register
+    from qtype.semantic.model import Application as SemanticApplication
+
+    if isinstance(spec, SemanticApplication) and spec.telemetry:
+        logger.info(
+            f"Telemetry enabled with endpoint: {spec.telemetry.endpoint}"
+        )
+        secret_mgr = create_secret_manager_for_spec(spec)
+        register(spec.telemetry, secret_mgr, spec.id)
+
+
+def create_secret_manager_for_spec(spec):
+    """Create a secret manager based on the specification."""
+    from qtype.interpreter.base.secrets import create_secret_manager
+    from qtype.semantic.model import Application as SemanticApplication
+
+    if isinstance(spec, SemanticApplication):
+        return create_secret_manager(spec.secret_manager)
+    else:
+        raise ValueError(
+            "Can't create secret manager for non-Application spec"
+        )
+
+
+async def execute_workflow(
+    path: Path,
+    inputs: dict | Any,
+    flow_name: str | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Execute a complete workflow from document to results.
+
+    Args:
+        path: Path to the QType specification file
+        inputs: Dictionary of input values or DataFrame for batch
+        flow_name: Optional name of flow to execute
+        **kwargs: Additional dependencies for execution
+
+    Returns:
+        DataFrame with results (one row per input)
     """
-    from pathlib import Path
-
-    import magic
-
-    mime_type = magic.Magic(mime=True).from_file(file_path)
-
-    if mime_type == "text/csv":
-        # TODO: Restore na values and convert to optional once we support them https://github.com/bazaarvoice/qtype/issues/101
-        df = pd.read_csv(file_path)
-        return df.fillna("")
-    elif mime_type == "text/plain":
-        # For text/plain, use file extension to determine format
-        file_ext = Path(file_path).suffix.lower()
-        if file_ext == ".csv":
-            # TODO: Restore na values and convert to optional once we support them https://github.com/bazaarvoice/qtype/issues/101
-            df = pd.read_csv(file_path)
-            return df.fillna("")
-        elif file_ext == ".json":
-            return pd.read_json(file_path)
+    import pandas as pd
+    from opentelemetry import trace
+
+    from qtype.interpreter.base.executor_context import ExecutorContext
+    from qtype.interpreter.converters import (
+        dataframe_to_flow_messages,
+        flow_messages_to_dataframe,
+    )
+    from qtype.interpreter.flow import run_flow
+    from qtype.interpreter.types import Session
+    from qtype.semantic.loader import load
+    from qtype.semantic.model import Application as SemanticApplication
+
+    # Load the semantic application
+    semantic_model, type_registry = load(path)
+    assert isinstance(semantic_model, SemanticApplication)
+    register_telemetry(semantic_model)
+
+    # Find the flow to execute
+    if flow_name:
+        target_flow = None
+        for flow in semantic_model.flows:
+            if flow.id == flow_name:
+                target_flow = flow
+                break
+        if target_flow is None:
+            raise ValueError(f"Flow '{flow_name}' not found")
+    else:
+        if semantic_model.flows:
+            target_flow = semantic_model.flows[0]
         else:
-            raise ValueError(
-                (
-                    f"Unsupported text/plain file extension: {file_ext}. "
-                    "Supported extensions: .csv, .json"
-                )
-            )
-    elif mime_type == "application/json":
-        return pd.read_json(file_path)
-    elif mime_type in [
-        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-        "application/vnd.ms-excel",
-    ]:
-        return pd.read_excel(file_path)
-    elif mime_type in ["application/vnd.parquet", "application/octet-stream"]:
-        return pd.read_parquet(file_path)
+            raise ValueError("No flows found in application")
+
+    logger.info(f"Executing flow {target_flow.id} from {path}")
+
+    # Convert inputs to DataFrame (normalize single dict to 1-row DataFrame)
+    if isinstance(inputs, dict):
+        input_df = pd.DataFrame([inputs])
+    elif isinstance(inputs, pd.DataFrame):
+        input_df = inputs
     else:
         raise ValueError(
-            f"Unsupported MIME type for file {file_path}: {mime_type}"
+            f"Inputs must be dict or DataFrame, got {type(inputs)}"
         )
 
+    # Create session
+    session = Session(
+        session_id=kwargs.pop("session_id", "default"),
+        conversation_history=kwargs.pop("conversation_history", []),
+    )
+
+    # Convert DataFrame to FlowMessages with type conversion
+    initial_messages_list = dataframe_to_flow_messages(
+        input_df, target_flow.inputs, session=session
+    )
+
+    # Execute the flow
+    secret_manager = create_secret_manager_for_spec(semantic_model)
+
+    context = ExecutorContext(
+        secret_manager=secret_manager,
+        tracer=trace.get_tracer(__name__),
+    )
+    results = await run_flow(
+        target_flow,
+        initial_messages_list,
+        context=context,
+        **kwargs,
+    )
+
+    # Convert results back to DataFrame
+    results_df = flow_messages_to_dataframe(results, target_flow)
+
+    return results_df
+
 
 def run_flow(args: Any) -> None:
     """Run a QType YAML spec file by executing its flows.
@@ -82,7 +155,6 @@ def run_flow(args: Any) -> None:
     """
     import asyncio
 
-    facade = QTypeFacade()
     spec_path = Path(args.spec)
 
     try:
@@ -90,7 +162,7 @@ def run_flow(args: Any) -> None:
 
         if args.input_file:
             logger.info(f"Loading input data from file: {args.input_file}")
-            input: Any = read_data_from_file(args.input_file)
+            input: Any = read_dataframe_from_file(args.input_file)
         else:
             # Parse input JSON
             try:
@@ -99,9 +171,9 @@ def run_flow(args: Any) -> None:
                 logger.error(f"❌ Invalid JSON input: {e}")
                 return
 
-        # Execute the workflow using the facade (now async, returns DataFrame)
+        # Execute the workflow using the standalone function
         result_df = asyncio.run(
-            facade.execute_workflow(
+            execute_workflow(
                 spec_path,
                 flow_name=args.flow,
                 inputs=input,
@@ -113,7 +185,7 @@ def run_flow(args: Any) -> None:
 
         # Display results
         if len(result_df) > 0:
-            logger.info(f"Processed {len(result_df)} em")
+            logger.info(f"Processed {len(result_df)} rows")
 
             # Remove 'row' and 'error' columns for display if all errors are None
             display_df = result_df.copy()
@@ -125,15 +197,37 @@ def run_flow(args: Any) -> None:
             if "row" in display_df.columns:
                 display_df = display_df.drop(columns=["row"])
 
-            if len(display_df) > 1:
-                logger.info(f"\nResults:\n{display_df[0:10].to_string()}\n...")
-            else:
-                # Print the first row with column_name: value one per line
-                fmt_str = []
-                for col, val in display_df.iloc[0].items():
-                    fmt_str.append(f"{col}: {val}")
-                fmt_str = "\n".join(fmt_str)
-                logger.info(f"\nResults:\n{fmt_str}")
+            # Show summary for console display
+            logger.info(
+                f"\nResults summary: {len(display_df)} rows, "
+                f"{len(display_df.columns)} columns: {list(display_df.columns)}"
+            )
+
+            # Optionally show full output
+            if args.show_output:
+                # Truncate long strings for display
+                max_col_width = 100
+                for col in display_df.columns:
+                    display_df[col] = display_df[col].apply(
+                        lambda x: (
+                            f"{str(x)[:max_col_width]}..."
+                            if isinstance(x, str)
+                            and len(str(x)) > max_col_width
+                            else x
+                        )
+                    )
+
+                if len(display_df) > 1:
+                    logger.info(
+                        f"\nResults:\n{display_df[0:10].to_string()}\n..."
+                    )
+                else:
+                    # Print the first row with column_name: value one per line
+                    fmt_str = []
+                    for col, val in display_df.iloc[0].items():
+                        fmt_str.append(f"{col}: {val}")
+                    fmt_str = "\n".join(fmt_str)
+                    logger.info(f"\nResults:\n{fmt_str}")
 
             # Save the output
             if args.output:
@@ -195,6 +289,11 @@ def parser(subparsers: argparse._SubParsersAction) -> None:
         action="store_true",
         help="Show progress bars during flow execution.",
     )
+    cmd_parser.add_argument(
+        "--show-output",
+        action="store_true",
+        help="Display full output data in console (default: summary only).",
+    )
 
     cmd_parser.add_argument(
         "spec", type=str, help="Path to the QType YAML spec file."

qtype/docs/.pages

@@ -0,0 +1,8 @@
+nav:
+  - index.md
+  - Tutorials
+  - Gallery
+  - How To
+  - Concepts
+  - Reference
+  - Contributing

{docs → qtype/docs}/Concepts/mental-model-and-philosophy.md

@@ -128,7 +128,7 @@ 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.
+**1-to-many cardinality:** Some steps (like `Explode`) can produce multiple outputs for one input, creating fan-out patterns. Other steps (like `Collect`) gather many inputs into one collection. This enables batch processing patterns.
 
 ---
 

qtype/docs/Contributing/.pages

@@ -0,0 +1,4 @@
+title: Contributing
+nav:
+  - index.md
+  - roadmap.md

{docs → qtype/docs}/Contributing/index.md

@@ -57,6 +57,14 @@ After installation, you should be able to run the `qtype` command from anywhere:
 qtype --help
 ```
 
+## Running the MCP In Dev Mode
+
+To start it in `dev` mode with the inspector:
+```
+mcp dev qtype/mcp/server.py:mcp
+```
+
+
 ## Running Tests
 
 The project uses pytest for testing with coverage measurement:
@@ -161,7 +169,6 @@ pre-commit install
 
 Settings are in `.pre-commit-config.yaml`:
 
-
 ##  Project Structure
 
 - `qtype/` – Python package for parsing, validating, and interpreting QType specs

{docs → qtype/docs}/Gallery/dataflow_pipelines.md

@@ -64,11 +64,24 @@ Example output:
 
 You'll notice that the output shows 1 message for `write_results` and 10 for the others. That is because it is reporting the number of messages _emitted_ from each step, and `write_results` is a sink that collects all messages.
 
-The final message of the output will be the result file where the data are written:
+By default, QType shows a summary of the results. The final message will show:
 
 ```
 2026-01-16 11:23:35,151 - INFO: ✅ Flow execution completed successfully
-2026-01-16 11:23:35,151 - INFO: Processed 1 em
+2026-01-16 11:23:35,151 - INFO: Processed 1 rows
+2026-01-16 11:23:35,152 - INFO: 
+Results summary: 1 rows, 1 columns: ['result_file']
+```
+
+To see the full output data, add the `--show-output` flag:
+
+```bash
+qtype run -i '{"output_path":"results.parquet"}' --progress --show-output examples/data_processing/dataflow_pipelines.qtype.yaml
+```
+
+This will display:
+
+```
 2026-01-16 11:23:35,152 - INFO: 
 Results:
 result_file: results.parquet
@@ -76,5 +89,6 @@ result_file: results.parquet
 
 ## Learn More
 
-- Tutorial: [Your First QType Application](../../Tutorials/01_hello_world.md)
-- Example: [Simple Chatbot](./simple_chatbot.md)
+- [Tutorial: Your First QType Application](../Tutorials/01-first-qtype-application.md)
+- [Read Data from SQL Databases](../How%20To/Data%20Processing/read_sql_databases.md)
+- [Adjust Concurrency](../How%20To/Data%20Processing/adjust_concurrency.md)

qtype/docs/Gallery/recipe_chatbot.md

@@ -0,0 +1,103 @@
+# Retrieval Augmented Generation Chatbot
+
+## Overview
+
+A complete RAG (Retrieval Augmented Generation) chatbot that answers cooking questions using a recipe collection from GitHub. The system ingests markdown recipe files, splits them into chunks, generates embeddings, stores them in a vector database, and provides conversational search with context-aware responses using memory to maintain conversation history.
+
+## Architecture
+
+```mermaid
+--8<-- "Gallery/recipe_chatbot.mermaid"
+```
+
+## Complete Code
+
+```yaml
+--8<-- "../examples/rag/recipe_chatbot.qtype.yaml"
+```
+
+## Running the Example
+
+### Prerequisites
+
+Start Qdrant vector database locally:
+```bash
+docker run -p 6333:6333 qdrant/qdrant
+```
+
+Clone the recipe repository:
+```bash
+git clone https://github.com/clarklab/chowdown.git
+```
+
+### Ingest Recipe Documents
+
+Run the ingestion flow to populate the vector index:
+```bash
+AWS_PROFILE=my_profile qtype run examples/rag/recipe_chatbot.qtype.yaml --flow recipe_ingestion --progress
+```
+
+This will:
+1. Load all markdown files from `chowdown/_recipes/`
+2. Split them into 512-token chunks with 50-token overlap
+3. Generate embeddings using AWS Bedrock Titan
+4. Store vectors in Qdrant collection `chowdown_recipes`
+
+You should see the output similar to:
+```
+2026-02-04 06:38:06,222 - qtype.commands.run - INFO - Running flow from recipe_chatbot.qtype.yaml
+2026-02-04 06:38:06,315 - qtype.commands.run - INFO - Executing flow recipe_ingestion from recipe_chatbot.qtype.yaml
+/Users/lou.kratz/repos/qtype-cicd-fix/.venv/lib/python3.13/site-packages/llama_index/vector_stores/qdrant/base.py:238: UserWarning: Api key is used with an insecure connection.
+  self._client = qdrant_client.QdrantClient(
+/Users/lou.kratz/repos/qtype-cicd-fix/.venv/lib/python3.13/site-packages/llama_index/vector_stores/qdrant/base.py:241: UserWarning: Api key is used with an insecure connection.
+  self._aclient = qdrant_client.AsyncQdrantClient(
+╭─────────────────────────────────────────────── Flow Progress ────────────────────────────────────────────────╮
+│                                                                                                              │
+│  Step load_recipes   12.9 msg/s ▁▁▂▄▄▅▅▅▅▄▆▆▆▇▇█▇▇… ✔ 34 succeeded ✖ 0 errors ⟳ - hits ✗ - misses 0:00:02    │
+│  Step split_recipes  14.9 msg/s ▁▁▁▃▂▅▅▅▆▅▆▆▇▇▇█▇▇… ✔ 39 succeeded ✖ 0 errors ⟳ - hits ✗ - misses 0:00:02    │
+│  Step embed_chunks   18.7 msg/s ██▃▃▁▂▂▁▂▁▁▁▁▁▁▁▁▁… ✔ 39 succeeded ✖ 0 errors ⟳ - hits ✗ - misses 0:00:02    │
+│  Step index_recipes  47.0 msg/s ████████▁           ✔ 39 succeeded ✖ 0 errors ⟳ - hits ✗ - misses 0:00:00    │
+│                                                                                                              │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+2026-02-04 06:38:11,141 - qtype.commands.run - INFO - ✅ Flow execution completed successfully
+2026-02-04 06:38:11,141 - qtype.commands.run - INFO - Processed 39 rows
+2026-02-04 06:38:11,141 - qtype.commands.run - INFO - 
+Results summary: 39 rows, 1 columns: ['embedded_chunk']
+```
+
+### Start the Chatbot
+
+Launch the conversational UI:
+```bash
+AWS_PROFILE=my_profile qtype serve examples/rag/recipe_chatbot.qtype.yaml --flow recipe_chat
+```
+
+Then open http://localhost:8000 and ask questions like:
+- "What dessert recipes do you have?"
+- "What can I make with chicken?"
+
+![A screenshot the ui showing a user asking for a healthy recipe and the AI responding with bean sprout stir fry](recipe_chatbot.png)
+
+## Key Features
+
+- **Conversational Interface**: Flow interface type that accumulates messages in `conversation_history` for stateful multi-turn chat
+- **Memory**: Conversation buffer with `token_limit` (10,000) and `chat_history_token_ratio` (0.7) that auto-flushes oldest messages when limit exceeded
+- **DocumentSource**: Loads markdown files via LlamaIndex `SimpleDirectoryReader` with `required_exts` file filter
+- **DocumentSplitter**: Splits documents with `SentenceSplitter` using `chunk_size` (512) and `chunk_overlap` (50) parameters
+- **DocumentEmbedder**: Generates embeddings with AWS Bedrock Titan, processes chunks concurrently via `num_workers` (5)
+- **VectorIndex**: Qdrant vector store with `embedding_model` reference and dimensions (1024)
+- **IndexUpsert**: Writes to vector index in batches via `batch_size` (25)
+- **VectorSearch**: Semantic search with `default_top_k` (5) returns chunks by embedding distance
+- **FieldExtractor**: Extracts text from ChatMessage using JSONPath `$.blocks[?(@.type == 'text')].content`
+- **PromptTemplate**: Injects search results and query into template string for LLM context
+- **LLMInference**: Calls model with `system_message` and `memory` reference for conversation history
+- **RAGDocument**: Domain type with `content`, `file_id`, `file_name`, `metadata` fields
+- **RAGChunk**: Domain type with `content`, `chunk_id`, `document_id`, `vector` fields
+- **RAGSearchResult**: Domain type with `content` (RAGChunk), `doc_id`, `score` fields
+
+
+## Learn More
+
+- Tutorial: [Building a Stateful Chatbot](../../Tutorials/building-a-stateful-chatbot.md)
+- How-To: [Use Environment Variables](../../How-To%20Guides/Language%20Features/use-environment-variables.md)
+- How-To: [Configure AWS Authentication](../../How-To%20Guides/Authentication/configure-aws-authentication.md)

qtype/docs/Gallery/recipe_chatbot.mermaid

@@ -0,0 +1,62 @@
+flowchart TD
+    subgraph APP ["📱 recipe_rag_chatbot"]
+        direction TB
+
+    subgraph FLOW_0 ["🔄 recipe_chat"]
+        direction LR
+        FLOW_0_START@{shape: circle, label: "▶️ Start"}
+        FLOW_0_S0@{shape: rect, label: "⚙️ extract_question"}
+        FLOW_0_S1@{shape: cyl, label: "🔎 search_recipes"}
+        FLOW_0_S2@{shape: doc, label: "📄 build_context_prompt"}
+        FLOW_0_S3@{shape: rounded, label: "✨ generate_response"}
+        FLOW_0_START -->|user_message| FLOW_0_S0
+        FLOW_0_S0 -->|user_question| FLOW_0_S1
+        FLOW_0_S1 -->|search_results| FLOW_0_S2
+        FLOW_0_S0 -->|user_question| FLOW_0_S2
+        FLOW_0_S2 -->|context_prompt| FLOW_0_S3
+    end
+
+    subgraph FLOW_1 ["🔄 recipe_ingestion"]
+        direction TB
+        FLOW_1_S0@{shape: rect, label: "⚙️ load_recipes"}
+        FLOW_1_S1@{shape: rect, label: "⚙️ split_recipes"}
+        FLOW_1_S2@{shape: rect, label: "⚙️ embed_chunks"}
+        FLOW_1_S3@{shape: rect, label: "💾 index_recipes"}
+        FLOW_1_S0 -->|recipe_document| FLOW_1_S1
+        FLOW_1_S1 -->|recipe_chunk| FLOW_1_S2
+        FLOW_1_S2 -->|embedded_chunk| FLOW_1_S3
+    end
+
+    subgraph RESOURCES ["🔧 Shared Resources"]
+        direction LR
+        AUTH_AWS_AUTH@{shape: hex, label: "🔐 aws_auth (AWS)"}
+        MODEL_CLAUDE_SONNET@{shape: rounded, label: "✨ claude_sonnet (aws-bedrock)" }
+        MODEL_CLAUDE_SONNET -.->|uses| AUTH_AWS_AUTH
+        MODEL_TITAN_EMBED@{shape: rounded, label: "✨ titan_embed (aws-bedrock)" }
+        MODEL_TITAN_EMBED -.->|uses| AUTH_AWS_AUTH
+        INDEX_RECIPE_INDEX@{shape: cyl, label: "�️ recipe_index"}
+        EMB_TITAN_EMBED@{shape: rounded, label: "🎯 titan_embed"}
+        INDEX_RECIPE_INDEX -.->|embeds| EMB_TITAN_EMBED
+        MEM_RECIPE_CHAT_MEMORY@{shape: win-pane, label: "🧠 recipe_chat_memory (10KT)"}
+    end
+
+    end
+
+    FLOW_0_S1 -.-> INDEX_RECIPE_INDEX
+    FLOW_0_S3 -.->|uses| MODEL_CLAUDE_SONNET
+    FLOW_0_S3 -.->|stores| MEM_RECIPE_CHAT_MEMORY
+    FLOW_1_S3 -.->|writes| INDEX_RECIPE_INDEX
+
+    %% Styling
+    classDef appBox fill:none,stroke:#495057,stroke-width:3px
+    classDef flowBox fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
+    classDef llmNode fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
+    classDef modelNode fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
+    classDef authNode fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
+    classDef telemetryNode fill:#fce4ec,stroke:#c2185b,stroke-width:2px
+    classDef resourceBox fill:#f5f5f5,stroke:#616161,stroke-width:1px
+
+    class APP appBox
+    class FLOW_0 flowBox
+    class RESOURCES resourceBox
+    class TELEMETRY telemetryNode