ai-pipeline-core 0.3.0__py3-none-any.whl → 0.3.3__py3-none-any.whl

ai_pipeline_core/llm/model_response.py

@@ -28,7 +28,7 @@ class ModelResponse(ChatCompletion):
 
     Primary usage is adding to AIMessages for multi-turn conversations:
 
-        >>> response = await llm.generate("gpt-5", messages=messages)
+        >>> response = await llm.generate("gpt-5.1", messages=messages)
         >>> messages.append(response)  # Add assistant response to conversation
         >>> print(response.content)  # Access generated text
 
@@ -43,7 +43,7 @@ class ModelResponse(ChatCompletion):
         >>> from ai_pipeline_core import llm, AIMessages
         >>>
         >>> messages = AIMessages(["Explain quantum computing"])
-        >>> response = await llm.generate("gpt-5", messages=messages)
+        >>> response = await llm.generate("gpt-5.1", messages=messages)
         >>>
         >>> # Primary usage: add to conversation
         >>> messages.append(response)
@@ -81,7 +81,7 @@ class ModelResponse(ChatCompletion):
             >>> # Usually created internally by generate()
             >>> response = ModelResponse(
             ...     chat_completion=completion,
-            ...     model_options={"temperature": 0.7, "model": "gpt-4"},
+            ...     model_options={"temperature": 0.7, "model": "gpt-5.1"},
             ...     metadata={"time_taken": 1.5, "first_token_time": 0.3}
             ... )
         """
@@ -116,7 +116,7 @@ class ModelResponse(ChatCompletion):
             Generated text from the model, or empty string if none.
 
         Example:
-            >>> response = await generate("gpt-5", messages="Hello")
+            >>> response = await generate("gpt-5.1", messages="Hello")
             >>> text = response.content  # The generated response
             >>>
             >>> # Common pattern: add to messages then use content
@@ -185,7 +185,7 @@ class ModelResponse(ChatCompletion):
 
         Example:
             >>> response = await llm.generate(
-            ...     "gpt-5",
+            ...     "gpt-5.1",
             ...     context=large_doc,
             ...     messages="Summarize this"
             ... )

ai_pipeline_core/llm/model_types.py

@@ -15,17 +15,15 @@ from typing import Literal, TypeAlias
 ModelName: TypeAlias = (
     Literal[
         # Core models
-        "gemini-2.5-pro",
-        "gpt-5",
-        "grok-4",
+        "gemini-3-pro",
+        "gpt-5.1",
         # Small models
-        "gemini-2.5-flash",
+        "gemini-3-flash",
         "gpt-5-mini",
-        "grok-4-fast",
+        "grok-4.1-fast",
         # Search models
-        "gemini-2.5-flash-search",
+        "gemini-3-flash-search",
         "sonar-pro-search",
-        "gpt-4o-search",
     ]
     | str
 )
@@ -38,15 +36,15 @@ string for custom models. The type is a union of predefined literals
 and str, giving you the best of both worlds: suggestions for known
 models and flexibility for custom ones.
 
-Note: These are example common model names as of Q3 2025. Actual availability
+Note: These are example common model names as of Q1 2026. Actual availability
 depends on your LiteLLM proxy configuration and provider access.
 
 Model categories:
-    Core models (gemini-2.5-pro, gpt-5, grok-4):
+    Core models (gemini-3-pro, gpt-5.1):
         High-capability models for complex tasks requiring deep reasoning,
         nuanced understanding, or creative generation.
 
-    Small models (gemini-2.5-flash, gpt-5-mini, grok-4-fast):
+    Small models (gemini-3-flash, gpt-5-mini, grok-4.1-fast):
         Efficient models optimized for speed and cost, suitable for
         simpler tasks or high-volume processing.
 
@@ -64,7 +62,7 @@ Example:
     >>> from ai_pipeline_core import llm, ModelName
     >>>
     >>> # Predefined model with IDE autocomplete
-    >>> model: ModelName = "gpt-5"  # IDE suggests common models
+    >>> model: ModelName = "gpt-5.1"  # IDE suggests common models
     >>> response = await llm.generate(model, messages="Hello")
     >>>
     >>> # Custom model works directly
@@ -72,7 +70,7 @@ Example:
     >>> response = await llm.generate(model, messages="Hello")
     >>>
     >>> # Both types work seamlessly
-    >>> models: list[ModelName] = ["gpt-5", "custom-llm", "gemini-2.5-pro"]
+    >>> models: list[ModelName] = ["gpt-5.1", "custom-llm", "gemini-3-pro"]
 
 Note:
     The ModelName type includes both predefined literals and str,

ai_pipeline_core/logging/logging_mixin.py

@@ -117,7 +117,7 @@ class StructuredLoggerMixin(LoggerMixin):
 
         Example:
             self.log_metric("processing_time", 1.23, "seconds",
-                          document_type="pdf", model="gpt-4")
+                          document_type="pdf", model="gpt-5.1")
         """
         self.logger.info(
             f"Metric: {metric_name}",
@@ -140,7 +140,7 @@ class StructuredLoggerMixin(LoggerMixin):
 
         Example:
             self.log_span("llm_generation", 1234.5,
-                         model="gpt-4", tokens=500)
+                         model="gpt-5.1", tokens=500)
         """
         self.logger.info(
             f"Span: {operation}",

ai_pipeline_core/prompt_builder/prompt_builder.py

@@ -144,7 +144,7 @@ class PromptBuilder(BaseModel):
             options.service_tier = None
             options.cache_ttl = None
             cache_lock = False
-        if "grok-4-fast" in model:
+        if "grok-4.1-fast" in model:
             options.max_completion_tokens = 30000
 
         if self.mode == "test":
@@ -154,7 +154,7 @@ class PromptBuilder(BaseModel):
             options.reasoning_effort = "medium"
             options.verbosity = None
 
-        if model.startswith("gpt-5"):
+        if model.startswith("gpt-5.1"):
             options.service_tier = "flex"
 
         return options, cache_lock
@@ -224,7 +224,7 @@ class PromptBuilder(BaseModel):
         self, model: ModelName, prompt: str | AIMessages, options: ModelOptions | None = None
     ) -> str:
         options, _ = self._get_options(model, options)
-        if "gpt-5" not in model and "grok-4" not in model and "openrouter/" not in model:
+        if "gpt-5.1" not in model and "grok-4.1-fast" not in model and "openrouter/" not in model:
             options.stop = "</document>"
 
         response = await self.call(model, prompt, options)

ai_pipeline_core/tracing.py

@@ -276,6 +276,9 @@ class TraceInfo(BaseModel):
 # ---------------------------------------------------------------------------
 
 
+_debug_processor_initialized = False
+
+
 def _initialise_laminar() -> None:
     """Initialize Laminar SDK with project configuration.
 
@@ -287,17 +290,66 @@ def _initialise_laminar() -> None:
         - Uses settings.lmnr_project_api_key for authentication
         - Disables OPENAI instrument to prevent double-tracing
         - Called automatically by trace decorator on first use
+        - Optionally adds local debug processor if TRACE_DEBUG_PATH is set
 
     Note:
         This is an internal function called once per process.
         Multiple calls are safe (Laminar handles idempotency).
     """
+    global _debug_processor_initialized
+
     if settings.lmnr_project_api_key:
         Laminar.initialize(
             project_api_key=settings.lmnr_project_api_key,
             disabled_instruments=[Instruments.OPENAI] if Instruments.OPENAI else [],
         )
 
+    # Add local debug processor if configured (only once)
+    if not _debug_processor_initialized:
+        _debug_processor_initialized = True
+        debug_path = os.environ.get("TRACE_DEBUG_PATH")
+        if debug_path:
+            _setup_debug_processor(debug_path)
+
+
+def _setup_debug_processor(debug_path: str) -> None:
+    """Set up local debug trace processor."""
+    try:
+        from pathlib import Path  # noqa: PLC0415
+
+        from opentelemetry import trace  # noqa: PLC0415
+
+        from ai_pipeline_core.debug import (  # noqa: PLC0415
+            LocalDebugSpanProcessor,
+            LocalTraceWriter,
+            TraceDebugConfig,
+        )
+
+        config = TraceDebugConfig(
+            path=Path(debug_path),
+            max_element_bytes=int(os.environ.get("TRACE_DEBUG_MAX_INLINE", 10000)),
+            max_traces=int(os.environ.get("TRACE_DEBUG_MAX_TRACES", 20)) or None,
+        )
+
+        writer = LocalTraceWriter(config)
+        processor = LocalDebugSpanProcessor(writer)
+
+        # Add to tracer provider
+        provider = trace.get_tracer_provider()
+        add_processor = getattr(provider, "add_span_processor", None)
+        if add_processor is not None:
+            add_processor(processor)
+
+        # Register shutdown
+        import atexit  # noqa: PLC0415
+
+        atexit.register(processor.shutdown)
+
+    except Exception as e:
+        import logging  # noqa: PLC0415
+
+        logging.getLogger(__name__).warning(f"Failed to setup debug trace processor: {e}")
+
 
 # Overload for calls like @trace(name="...", level="debug")
 @overload
@@ -728,7 +780,7 @@ def set_trace_cost(cost: float | str) -> None:
         >>> @pipeline_task
         >>> async def enriched_generation(prompt: str) -> str:
         ...     # LLM cost tracked automatically via ModelResponse
-        ...     response = await llm.generate("gpt-5", messages=prompt)
+        ...     response = await llm.generate("gpt-5.1", messages=prompt)
         ...
         ...     # Add cost for post-processing
         ...     processing_cost = 0.02  # Fixed cost for enrichment

ai_pipeline_core/utils/deploy.py

@@ -18,10 +18,13 @@ Usage:
 
 import argparse
 import asyncio
+import json
 import subprocess
 import sys
+import tempfile
 import tomllib
 import traceback
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
 
@@ -70,6 +73,8 @@ class Deployer:
         with open(pyproject_path, "rb") as f:
             data = tomllib.load(f)
 
+        self._pyproject_data = data
+
         project = data.get("project", {})
         name = project.get("name")
         version = project.get("version")
@@ -160,6 +165,192 @@ class Deployer:
         self._success(f"Built {tarball_path.name} ({tarball_path.stat().st_size // 1024} KB)")
         return tarball_path
 
+    # -- Agent build/upload support --
+
+    def _load_agent_config(self) -> dict[str, dict[str, Any]]:
+        """Load [tool.deploy.agents] from pyproject.toml.
+
+        Returns:
+            Dict mapping agent name to config (path, extra_vendor).
+            Empty dict if no agents configured.
+        """
+        return self._pyproject_data.get("tool", {}).get("deploy", {}).get("agents", {})
+
+    def _get_cli_agents_source(self) -> str | None:
+        """Get cli_agents_source path from [tool.deploy]."""
+        return self._pyproject_data.get("tool", {}).get("deploy", {}).get("cli_agents_source")
+
+    def _build_wheel_from_source(self, source_dir: Path) -> Path:
+        """Build a wheel from a source directory.
+
+        Args:
+            source_dir: Directory containing pyproject.toml
+
+        Returns:
+            Path to built .whl file in a temp dist directory
+        """
+        if not (source_dir / "pyproject.toml").exists():
+            self._die(f"No pyproject.toml in {source_dir}")
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp_dist = Path(tmpdir) / "dist"
+            result = subprocess.run(
+                [sys.executable, "-m", "build", "--wheel", "--outdir", str(tmp_dist)],
+                cwd=source_dir,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                self._die(f"Wheel build failed for {source_dir.name}:\n{result.stderr}")
+
+            wheels = list(tmp_dist.glob("*.whl"))
+            if not wheels:
+                self._die(f"No wheel produced for {source_dir.name}")
+
+            # Copy to persistent dist/ under source_dir
+            dist_dir = source_dir / "dist"
+            dist_dir.mkdir(exist_ok=True)
+            output = dist_dir / wheels[0].name
+            output.write_bytes(wheels[0].read_bytes())
+            return output
+
+    def _build_agents(self) -> dict[str, dict[str, Any]]:
+        """Build agent wheels and manifests for all configured agents.
+
+        Returns:
+            Dict mapping agent name to build info:
+                {name: {"manifest_json": str, "files": {filename: Path}}}
+            Empty dict if no agents configured.
+        """
+        agent_config = self._load_agent_config()
+        if not agent_config:
+            return {}
+
+        cli_agents_source = self._get_cli_agents_source()
+        if not cli_agents_source:
+            self._die(
+                "Agents configured in [tool.deploy.agents] but "
+                "[tool.deploy].cli_agents_source is not set.\n"
+                "Add to pyproject.toml:\n"
+                '  [tool.deploy]\n  cli_agents_source = "vendor/cli-agents"'
+            )
+
+        self._info(f"Building {len(agent_config)} agent(s): {', '.join(agent_config)}")
+
+        # Build cli-agents wheel once (shared across all agents)
+        cli_agents_dir = Path(cli_agents_source).resolve()
+        if not (cli_agents_dir / "pyproject.toml").exists():
+            self._die(f"cli-agents source not found at {cli_agents_dir}")
+
+        cli_agents_wheel = self._build_wheel_from_source(cli_agents_dir)
+        self._success(f"Built cli-agents wheel: {cli_agents_wheel.name}")
+
+        builds: dict[str, dict[str, Any]] = {}
+
+        for agent_name, config in agent_config.items():
+            agent_path = Path(config["path"]).resolve()
+            if not (agent_path / "pyproject.toml").exists():
+                self._die(
+                    f"Agent '{agent_name}' path not found: {agent_path}\n"
+                    f"Check [tool.deploy.agents.{agent_name}].path in pyproject.toml"
+                )
+
+            # Read module_name from agent's pyproject.toml
+            with open(agent_path / "pyproject.toml", "rb") as f:
+                agent_pyproject = tomllib.load(f)
+
+            module_name = agent_pyproject.get("tool", {}).get("agent", {}).get("module")
+            if not module_name:
+                self._die(
+                    f"Agent '{agent_name}' missing [tool.agent].module in "
+                    f"{agent_path / 'pyproject.toml'}\n"
+                    f'Add:\n  [tool.agent]\n  module = "agent_{agent_name}"'
+                )
+
+            # Build agent wheel
+            agent_wheel = self._build_wheel_from_source(agent_path)
+            self._success(f"Built agent wheel: {agent_wheel.name}")
+
+            # Collect all files for this agent bundle
+            files: dict[str, Path] = {
+                agent_wheel.name: agent_wheel,
+                cli_agents_wheel.name: cli_agents_wheel,
+            }
+
+            # Build extra_vendor packages from repo root
+            vendor_packages: list[str] = []
+            extra_built: set[str] = set()
+            for vendor_name in config.get("extra_vendor", []):
+                extra_source_dir = Path(vendor_name).resolve()
+                if not (extra_source_dir / "pyproject.toml").exists():
+                    self._die(
+                        f"Extra vendor '{vendor_name}' for agent '{agent_name}' "
+                        f"not found at {extra_source_dir}\n"
+                        f"Ensure the directory exists at repo root with pyproject.toml"
+                    )
+                vendor_wheel = self._build_wheel_from_source(extra_source_dir)
+                files[vendor_wheel.name] = vendor_wheel
+                vendor_packages.append(vendor_wheel.name)
+                extra_built.add(extra_source_dir.name.replace("-", "_"))
+                self._success(f"Built vendor wheel: {vendor_wheel.name}")
+
+            # Collect existing vendor/*.whl and vendor/*.tar.gz from agent directory,
+            # skipping packages already built from extra_vendor
+            agent_vendor_dir = agent_path / "vendor"
+            if agent_vendor_dir.exists():
+                for pkg in list(agent_vendor_dir.glob("*.whl")) + list(
+                    agent_vendor_dir.glob("*.tar.gz")
+                ):
+                    pkg_base = pkg.name.split("-")[0].replace("-", "_")
+                    if pkg.name not in files and pkg_base not in extra_built:
+                        files[pkg.name] = pkg
+                        vendor_packages.append(pkg.name)
+
+            # Write manifest (plain JSON dict, compatible with AgentManifest schema)
+            manifest = {
+                "module_name": module_name,
+                "agent_wheel": agent_wheel.name,
+                "cli_agents_wheel": cli_agents_wheel.name,
+                "vendor_packages": vendor_packages,
+                "built_at": datetime.now(timezone.utc).isoformat(),
+            }
+            manifest_json = json.dumps(manifest, indent=2)
+
+            builds[agent_name] = {"manifest_json": manifest_json, "files": files}
+            self._success(f"Agent '{agent_name}' bundle ready ({module_name}, {len(files)} files)")
+
+        return builds
+
+    async def _upload_agents(self, agent_builds: dict[str, dict[str, Any]]):
+        """Upload agent bundles to GCS.
+
+        Args:
+            agent_builds: Output from _build_agents()
+        """
+        if not agent_builds:
+            return
+
+        flow_folder = self.config["folder"].split("/", 1)[1] if "/" in self.config["folder"] else ""
+        base_uri = f"gs://{self.config['bucket']}/flows"
+        base_storage = await Storage.from_uri(base_uri)
+        base_storage = base_storage.with_base(flow_folder)
+
+        for agent_name, build_info in agent_builds.items():
+            agent_storage = base_storage.with_base(f"agents/{agent_name}")
+            self._info(f"Uploading agent '{agent_name}' bundle to {agent_storage.url_for('')}")
+
+            # Upload manifest
+            await agent_storage.write_bytes(
+                "manifest.json",
+                build_info["manifest_json"].encode(),
+            )
+
+            # Upload wheels
+            for filename, filepath in build_info["files"].items():
+                await agent_storage.write_bytes(filename, filepath.read_bytes())
+
+            self._success(f"Agent '{agent_name}' uploaded ({len(build_info['files'])} files)")
+
     async def _upload_package(self, tarball: Path):
         """Upload package tarball to Google Cloud Storage using Storage abstraction.
 
@@ -184,13 +375,17 @@ class Deployer:
 
         self._success(f"Package uploaded to {self.config['folder']}/{tarball.name}")
 
-    async def _deploy_via_api(self):
+    async def _deploy_via_api(self, agent_builds: dict[str, dict[str, Any]] | None = None):
         """Create or update Prefect deployment using RunnerDeployment pattern.
 
         This is the official Prefect approach that:
         1. Automatically creates/updates the flow registration
         2. Handles deployment create vs update logic
         3. Properly formats all parameters for the API
+
+        Args:
+            agent_builds: Output from _build_agents(). If non-empty, sets
+                AGENT_BUNDLES_URI env var on the deployment.
         """
         # Define entrypoint (assumes flow function has same name as package)
         entrypoint = f"{self.config['package']}:{self.config['package']}"
@@ -244,6 +439,13 @@ class Deployer:
         # This is the official Prefect pattern that handles all the complexity
         self._info(f"Creating deployment for flow '{flow.name}'")
 
+        # Set AGENT_BUNDLES_URI env var if agents were built
+        job_variables: dict[str, Any] = {}
+        if agent_builds:
+            bundles_uri = f"gs://{self.config['bucket']}/{self.config['folder']}/agents"
+            job_variables["env"] = {"AGENT_BUNDLES_URI": bundles_uri}
+            self._info(f"Setting AGENT_BUNDLES_URI={bundles_uri}")
+
         deployment = RunnerDeployment(
             name=self.config["package"],
             flow_name=flow.name,
@@ -256,7 +458,7 @@ class Deployer:
             or f"Deployment for {self.config['package']} v{self.config['version']}",
             storage=_PullStepStorage(pull_steps),
             parameters={},
-            job_variables={},
+            job_variables=job_variables,
             paused=False,
         )
 
@@ -296,14 +498,20 @@ class Deployer:
         print("=" * 70)
         print()
 
-        # Phase 1: Build
+        # Phase 1: Build flow package
         tarball = self._build_package()
 
-        # Phase 2: Upload
+        # Phase 2: Build agent bundles (if configured)
+        agent_builds = self._build_agents()
+
+        # Phase 3: Upload flow package
         await self._upload_package(tarball)
 
-        # Phase 3: Deploy
-        await self._deploy_via_api()
+        # Phase 4: Upload agent bundles
+        await self._upload_agents(agent_builds)
+
+        # Phase 5: Create/update Prefect deployment
+        await self._deploy_via_api(agent_builds)
 
         print()
         print("=" * 70)

{ai_pipeline_core-0.3.0.dist-info → ai_pipeline_core-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-pipeline-core
-Version: 0.3.0
+Version: 0.3.3
 Summary: Core utilities for AI-powered processing pipelines using prefect
 Project-URL: Homepage, https://github.com/bbarwik/ai-pipeline-core
 Project-URL: Repository, https://github.com/bbarwik/ai-pipeline-core
@@ -22,6 +22,7 @@ Requires-Dist: httpx>=0.28.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: lmnr>=0.7.18
 Requires-Dist: openai>=1.109.1
+Requires-Dist: pillow>=10.0.0
 Requires-Dist: prefect-gcp[cloud-storage]>=0.6.10
 Requires-Dist: prefect>=3.4.21
 Requires-Dist: pydantic-settings>=2.10.1
@@ -124,7 +125,7 @@ async def analyze_flow(
     for doc in documents:
         # Use AIMessages for LLM interaction
         response = await llm.generate(
-            model="gpt-5",
+            model="gpt-5.1",
             messages=AIMessages([doc])
         )
 
@@ -151,7 +152,7 @@ class Analysis(BaseModel):
 
 # Generate structured output
 response = await llm.generate_structured(
-    model="gpt-5",
+    model="gpt-5.1",
     response_format=Analysis,
     messages="Analyze this product review: ..."
 )
@@ -246,7 +247,7 @@ from ai_pipeline_core import llm, AIMessages, ModelOptions
 
 # Simple generation
 response = await llm.generate(
-    model="gpt-5",
+    model="gpt-5.1",
     messages="Explain quantum computing"
 )
 print(response.content)
@@ -256,21 +257,21 @@ static_context = AIMessages([large_document])
 
 # First call: caches context
 r1 = await llm.generate(
-    model="gpt-5",
+    model="gpt-5.1",
     context=static_context,  # Cached for 120 seconds by default
     messages="Summarize"     # Dynamic query
 )
 
 # Second call: reuses cache
 r2 = await llm.generate(
-    model="gpt-5",
+    model="gpt-5.1",
     context=static_context,  # Reused from cache!
     messages="Key points?"   # Different query
 )
 
 # Custom cache TTL
 response = await llm.generate(
-    model="gpt-5",
+    model="gpt-5.1",
     context=static_context,
     messages="Analyze",
     options=ModelOptions(cache_ttl="300s")  # Cache for 5 minutes
@@ -278,7 +279,7 @@ response = await llm.generate(
 
 # Disable caching for dynamic contexts
 response = await llm.generate(
-    model="gpt-5",
+    model="gpt-5.1",
     context=dynamic_context,
     messages="Process",
     options=ModelOptions(cache_ttl=None)  # No caching
@@ -335,6 +336,68 @@ async def main_flow(
     return DocumentList(results)
 ```
 
+### Local Trace Debugging
+
+Save all trace spans to the local filesystem for LLM-assisted debugging:
+
+```bash
+export TRACE_DEBUG_PATH=/path/to/debug/output
+```
+
+This creates a hierarchical directory structure that mirrors the execution flow with automatic deduplication:
+
+```
+20260128_152932_abc12345_my_flow/
+├── _trace.yaml           # Trace metadata
+├── _index.yaml           # Span ID → path mapping
+├── _summary.md           # Unified summary for human inspection and LLM debugging
+├── artifacts/            # Deduplicated content storage
+│   └── sha256/
+│       └── ab/cd/        # Sharded by hash prefix
+│           └── abcdef...1234.txt  # Large content (>10KB)
+└── 0001_my_flow/         # Root span (numbered for execution order)
+    ├── _span.yaml        # Span metadata (timing, status, I/O refs)
+    ├── input.yaml        # Structured inputs (inline or refs)
+    ├── output.yaml       # Structured outputs (inline or refs)
+    ├── 0002_task_1/      # Child spans nested inside parent
+    │   ├── _span.yaml
+    │   ├── input.yaml
+    │   ├── output.yaml
+    │   └── 0003_llm_call/
+    │       ├── _span.yaml
+    │       ├── input.yaml   # LLM messages with inline/external content
+    │       └── output.yaml
+    └── 0004_task_2/
+        └── ...
+```
+
+**Key Features:**
+- **Automatic Deduplication**: Identical content (e.g., system prompts) stored once in `artifacts/`
+- **Smart Externalization**: Large content (>10KB) externalized with 2KB inline previews
+- **AI-Friendly**: Files capped at 50KB for easy LLM processing
+- **Lossless**: Full content reconstruction via `content_ref` pointers
+
+Example `input.yaml` with externalization:
+```yaml
+format_version: 3
+type: llm_messages
+messages:
+  - role: system
+    parts:
+      - type: text
+        size_bytes: 28500
+        content_ref:  # Large content → artifact
+          hash: sha256:a1b2c3d4...
+          path: artifacts/sha256/a1/b2/a1b2c3d4...txt
+        excerpt: "You are a helpful assistant...\n[TRUNCATED]"
+  - role: user
+    parts:
+      - type: text
+        content: "Hello!"  # Small content stays inline
+```
+
+Run `tree` on the output directory to visualize the entire execution hierarchy. Feed `_summary.md` to an LLM for debugging assistance - it combines high-level overview with detailed navigation for comprehensive trace analysis.
+
 ## Configuration
 
 ### Environment Variables
@@ -348,6 +411,9 @@ OPENAI_API_KEY=your-api-key
 LMNR_PROJECT_API_KEY=your-lmnr-key
 LMNR_DEBUG=true  # Enable debug traces
 
+# Optional: Local Trace Debugging
+TRACE_DEBUG_PATH=/path/to/trace/output  # Save traces locally for LLM-assisted debugging
+
 # Optional: Orchestration
 PREFECT_API_URL=http://localhost:4200/api
 PREFECT_API_KEY=your-prefect-key