ostruct-cli 0.8.29__py3-none-any.whl → 1.0.0__py3-none-any.whl

ostruct/cli/plan_printing.py

@@ -0,0 +1,385 @@
+"""Plan printing for human-readable execution plan output.
+
+This module renders execution plans and run summaries for human consumption
+using the same data structures as JSON output per UNIFIED GUIDELINES.
+"""
+
+import json
+import sys
+from datetime import datetime
+from typing import Any, Dict, Optional, TextIO
+
+from .unicode_compat import safe_emoji, safe_format
+
+
+class PlanPrinter:
+    """Renders execution plans for human eyes using same dict as JSON output.
+
+    This class ensures consistent rendering logic by operating on the same
+    data structures produced by PlanAssembler.
+    """
+
+    @staticmethod
+    def human(plan: Dict[str, Any], file: Optional[TextIO] = None) -> None:
+        """Print human-readable version with colors and formatting.
+
+        Args:
+            plan: Plan dictionary from PlanAssembler
+            file: Output file (defaults to stdout)
+        """
+        if file is None:
+            file = sys.stdout
+
+        plan_type = plan.get("type", "unknown").replace("_", " ").title()
+        emoji = safe_emoji("🔍")
+        if emoji:
+            print(f"{emoji} {plan_type}\n", file=file)
+        else:
+            print(f"{plan_type}\n", file=file)
+
+        # Header with timestamp
+        timestamp = plan["timestamp"]
+        if isinstance(timestamp, str):
+            # Handle ISO format timestamp
+            try:
+                timestamp_dt = datetime.fromisoformat(
+                    timestamp.replace("Z", "+00:00")
+                )
+            except ValueError:
+                # Fallback for other string formats
+                timestamp_dt = datetime.now()
+        else:
+            # Handle numeric timestamp (legacy)
+            timestamp_dt = datetime.fromtimestamp(timestamp)
+
+        formatted_time = timestamp_dt.strftime("%Y-%m-%d %H:%M:%S")
+        print(safe_format("🕐 Generated: {}", formatted_time), file=file)
+
+        # Template and schema
+        template = plan.get("template", {})
+        schema = plan.get("schema", {})
+
+        template_status = (
+            safe_emoji("✅", "[OK]")
+            if template.get("exists", False)
+            else safe_emoji("❌", "[ERROR]")
+        )
+        schema_status = (
+            safe_emoji("✅", "[OK]")
+            if schema.get("exists", False)
+            else safe_emoji("❌", "[ERROR]")
+        )
+
+        # Show more helpful template warning information
+        template_path = template.get("path", "unknown")
+        template_warning = template.get("warning")
+
+        if template_warning:
+            # Use warning indicator for configuration issues with existing files
+            warning_status = (
+                safe_emoji("⚠️", "[WARNING]")
+                if template.get("exists", False)
+                else safe_emoji("❌", "[ERROR]")
+            )
+            print(
+                safe_format(
+                    "📄 Template: {} {}", warning_status, template_path
+                ),
+                file=file,
+            )
+            print(
+                f"   Warning: {template_warning}",
+                file=file,
+            )
+        elif template_path == "---":
+            # Special case for YAML frontmatter display issue (legacy)
+            print(
+                safe_format(
+                    "📄 Template: {} {}", template_status, template_path
+                ),
+                file=file,
+            )
+            print(
+                "   Note: Template content shown below",
+                file=file,
+            )
+        else:
+            print(
+                safe_format(
+                    "📄 Template: {} {}", template_status, template_path
+                ),
+                file=file,
+            )
+
+        print(
+            safe_format(
+                "📋 Schema: {} {}",
+                schema_status,
+                schema.get("path", "unknown"),
+            ),
+            file=file,
+        )
+
+        # Model
+        if "model" in plan:
+            print(safe_format("🤖 Model: {}", plan["model"]), file=file)
+
+        # Security
+        security = plan.get("security", {})
+        if security:
+            print(
+                safe_format(
+                    "🔒 Security: {}", security.get("mode", "unknown")
+                ),
+                file=file,
+            )
+            allowed_paths = security.get("allowed_paths", [])
+            if allowed_paths:
+                print(
+                    f"   Allowed paths: {len(allowed_paths)} configured",
+                    file=file,
+                )
+
+        # Tools
+        tools = plan.get("tools", {})
+        if tools:
+            enabled_tools = [
+                name for name, enabled in tools.items() if enabled
+            ]
+            if enabled_tools:
+                print(
+                    safe_format("🛠️  Tools: {}", ", ".join(enabled_tools)),
+                    file=file,
+                )
+
+        print()  # Blank line before attachments
+
+        # Attachments
+        attachments = plan.get("attachments", [])
+        print(safe_format("📎 Attachments ({}):", len(attachments)), file=file)
+
+        if not attachments:
+            print("   (none)", file=file)
+        else:
+            for att in attachments:
+                exists_status = (
+                    safe_emoji("✅", "[OK]")
+                    if att.get("exists", False)
+                    else safe_emoji("❌", "[ERROR]")
+                )
+                targets = ", ".join(att.get("targets", []))
+                path = att.get("path", "unknown")
+                alias = att.get("alias", "unknown")
+
+                print(
+                    f"   {exists_status} {alias} → {targets}: {path}",
+                    file=file,
+                )
+
+                # Show additional details for directories
+                if att.get("type") == "directory":
+                    details = []
+                    if att.get("recursive"):
+                        details.append("recursive")
+                    if att.get("pattern"):
+                        details.append(f"pattern: {att['pattern']}")
+                    if details:
+                        print(f"      ({', '.join(details)})", file=file)
+
+        # Download validation for Code Interpreter
+        download_validation = plan.get("download_validation", {})
+        if download_validation.get("enabled"):
+            print(safe_format("\n📥 Download Configuration:"), file=file)
+            print(
+                f"   Directory: {download_validation.get('directory', 'N/A')}",
+                file=file,
+            )
+
+            # Show writability status
+            if download_validation.get("writable"):
+                print(
+                    safe_format(
+                        "   {} Directory writable", safe_emoji("✅", "[OK]")
+                    ),
+                    file=file,
+                )
+            else:
+                print(
+                    safe_format(
+                        "   {} Directory not writable",
+                        safe_emoji("❌", "[ERROR]"),
+                    ),
+                    file=file,
+                )
+
+            # Show issues if any
+            issues = download_validation.get("issues", [])
+            if issues:
+                print(
+                    safe_format(
+                        "   {}  Issues:", safe_emoji("⚠️", "[WARNING]")
+                    ),
+                    file=file,
+                )
+                for issue in issues:
+                    print(f"      - {issue}", file=file)
+
+            # Show potential conflicts
+            conflicts = download_validation.get("conflicts", [])
+            if conflicts:
+                print(
+                    safe_format(
+                        "   {}  Potential conflicts: {}",
+                        safe_emoji("⚠️", "[WARNING]"),
+                        ", ".join(conflicts),
+                    ),
+                    file=file,
+                )
+
+        # Variables
+        variables = plan.get("variables", {})
+        if variables:
+            print(
+                safe_format("\n📊 Variables ({}):", len(variables)), file=file
+            )
+            for name, value in variables.items():
+                # Truncate long values for readability
+                value_str = str(value)
+                if len(value_str) > 50:
+                    value_str = value_str[:47] + "..."
+                print(f"   {name}: {value_str}", file=file)
+
+        # Cost estimate
+        cost = plan.get("cost_estimate", {})
+        if cost and cost.get("approx_usd", 0) > 0:
+            estimated_note = " (estimated)" if cost.get("estimated") else ""
+            print(
+                safe_format(
+                    "\n💰 Cost: ~${:.4f}{}",
+                    cost.get("approx_usd", 0),
+                    estimated_note,
+                ),
+                file=file,
+            )
+            if "tokens" in cost:
+                print(f"   Tokens: ~{cost['tokens']:,}", file=file)
+
+        # Execution time (for run summaries)
+        if plan.get("type") == "run_summary":
+            exec_time = plan.get("execution_time")
+            success = plan.get("success", True)
+
+            status_icon = (
+                safe_emoji("✅", "[OK]")
+                if success
+                else safe_emoji("❌", "[ERROR]")
+            )
+            print(
+                safe_format(
+                    "\n{} Status: {}",
+                    status_icon,
+                    "Success" if success else "Failed",
+                ),
+                file=file,
+            )
+
+            if exec_time is not None:
+                print(
+                    safe_format("⏱️  Execution time: {:.2f}s", exec_time),
+                    file=file,
+                )
+
+            # Show error if present
+            if "error" in plan:
+                print(
+                    safe_format(
+                        "{} Error: {}",
+                        safe_emoji("❌", "[ERROR]"),
+                        plan["error"],
+                    ),
+                    file=file,
+                )
+
+            # Show cost breakdown if present
+            if "cost_breakdown" in plan:
+                cost_breakdown = plan["cost_breakdown"]
+                print(
+                    safe_format(
+                        "💰 Final cost: ${:.4f}",
+                        cost_breakdown.get("total", 0),
+                    ),
+                    file=file,
+                )
+
+    @staticmethod
+    def json(
+        plan: Dict[str, Any], file: Optional[TextIO] = None, indent: int = 2
+    ) -> None:
+        """Print JSON version of plan.
+
+        Args:
+            plan: Plan dictionary from PlanAssembler
+            file: Output file (defaults to stdout)
+            indent: JSON indentation level
+        """
+        if file is None:
+            file = sys.stdout
+
+        json.dump(plan, file, indent=indent, default=str)
+        file.write("\n")
+
+    @staticmethod
+    def summary_line(plan: Dict[str, Any]) -> str:
+        """Generate a one-line summary of the plan.
+
+        Args:
+            plan: Plan dictionary from PlanAssembler
+
+        Returns:
+            Single line summary string
+        """
+        plan_type = plan.get("type", "unknown")
+
+        if plan_type == "execution_plan":
+            attachments = len(plan.get("attachments", []))
+            variables = len(plan.get("variables", {}))
+            return f"Plan: {attachments} attachments, {variables} variables, model {plan.get('model', 'unknown')}"
+
+        elif plan_type == "run_summary":
+            success = plan.get("success", True)
+            exec_time = plan.get("execution_time")
+            status = "Success" if success else "Failed"
+            time_str = f" in {exec_time:.2f}s" if exec_time else ""
+            return f"Summary: {status}{time_str}"
+
+        else:
+            return f"Plan: {plan_type}"
+
+    @staticmethod
+    def validate_and_print(
+        plan: Dict[str, Any],
+        output_format: str = "human",
+        file: Optional[TextIO] = None,
+    ) -> None:
+        """Validate plan structure and print in specified format.
+
+        Args:
+            plan: Plan dictionary from PlanAssembler
+            output_format: Output format ("human" or "json")
+            file: Output file (defaults to stdout)
+
+        Raises:
+            ValueError: If plan structure is invalid or format is unsupported
+        """
+        from .plan_assembly import PlanAssembler
+
+        # Validate plan structure
+        PlanAssembler.validate_plan(plan)
+
+        # Print in requested format
+        if output_format == "human":
+            PlanPrinter.human(plan, file)
+        elif output_format == "json":
+            PlanPrinter.json(plan, file)
+        else:
+            raise ValueError(f"Unsupported output format: {output_format}")

ostruct/cli/progress_reporting.py

@@ -47,17 +47,17 @@ class ProcessingResult:
 class EnhancedProgressReporter:
     """Enhanced progress reporter with user-friendly language and transparency."""
 
-    def __init__(self, verbose: bool = False, progress_level: str = "basic"):
+    def __init__(self, verbose: bool = False, progress: str = "basic"):
         """Initialize the progress reporter.
 
         Args:
             verbose: Enable verbose logging output
-            progress_level: Progress level (none, basic, detailed)
+            progress: Progress level (none, basic, detailed)
         """
         self.verbose = verbose
-        self.progress_level = progress_level
-        self.should_report = progress_level != "none"
-        self.detailed = progress_level == "detailed" or verbose
+        self.progress = progress
+        self.should_report = progress != "none"
+        self.detailed = progress == "detailed" or verbose
 
     def report_phase(self, phase_name: str, emoji: str = "⚙️") -> None:
         """Report the start of a major processing phase.
@@ -69,27 +69,6 @@ class EnhancedProgressReporter:
         if self.should_report:
             click.echo(f"{emoji} {phase_name}...", err=True)
 
-    def report_optimization(self, optimizations: List[str]) -> None:
-        """Report template optimization results with user-friendly language.
-
-        Args:
-            optimizations: List of optimization transformations applied
-        """
-        if not self.should_report or not optimizations:
-            return
-
-        if self.detailed:
-            click.echo("🔧 Template optimization:", err=True)
-            for optimization in optimizations:
-                # Convert technical language to user-friendly descriptions
-                user_friendly = self._humanize_optimization(optimization)
-                click.echo(f"  → {user_friendly}", err=True)
-        else:
-            click.echo(
-                f"🔧 Optimized template for better AI performance ({len(optimizations)} improvements)",
-                err=True,
-            )
-
     def report_file_routing(
         self,
         template_files: List[str],
@@ -322,33 +301,6 @@ class EnhancedProgressReporter:
                 else:
                     click.echo("✅ Validation passed", err=True)
 
-    def _humanize_optimization(self, technical_message: str) -> str:
-        """Convert technical optimization messages to user-friendly language.
-
-        Args:
-            technical_message: Technical optimization message
-
-        Returns:
-            User-friendly description of the optimization
-        """
-        # Convert technical messages to user-friendly descriptions
-        if (
-            "moved" in technical_message.lower()
-            and "appendix" in technical_message.lower()
-        ):
-            file_name = technical_message.split("Moved ")[-1].split(
-                " to appendix"
-            )[0]
-            return f"Moved large file '{file_name}' to organized appendix"
-        elif "built structured appendix" in technical_message.lower():
-            return "Organized file content into structured appendix for better AI processing"
-        elif "moved directory" in technical_message.lower():
-            return technical_message.replace(
-                "Moved directory", "Organized directory"
-            )
-        else:
-            return technical_message
-
 
 # Global progress reporter instance
 _progress_reporter: Optional[EnhancedProgressReporter] = None
@@ -367,16 +319,16 @@ def get_progress_reporter() -> EnhancedProgressReporter:
 
 
 def configure_progress_reporter(
-    verbose: bool = False, progress_level: str = "basic"
+    verbose: bool = False, progress: str = "basic"
 ) -> None:
     """Configure the global progress reporter.
 
     Args:
         verbose: Enable verbose logging output
-        progress_level: Progress level (none, basic, detailed)
+        progress: Progress level (none, basic, detailed)
     """
     global _progress_reporter
-    _progress_reporter = EnhancedProgressReporter(verbose, progress_level)
+    _progress_reporter = EnhancedProgressReporter(verbose, progress)
 
 
 def report_phase(phase_name: str, emoji: str = "⚙️") -> None:

ostruct/cli/quick_ref_help.py

@@ -0,0 +1,128 @@
+"""Quick reference help system for ostruct CLI.
+
+This module provides quick usage examples and patterns with rich formatting.
+Uses rich-click formatting for beautiful, organized output.
+"""
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.text import Text
+
+
+def show_quick_ref_help() -> None:
+    """Display quick reference help with rich formatting."""
+    console = Console(stderr=True)
+
+    # Main title
+    title = Text("🚀 OSTRUCT QUICK REFERENCE", style="bold bright_blue")
+    console.print(title)
+    console.print()
+
+    # File Attachment System
+    attachment_content = """[bold bright_blue]--file[/bold bright_blue] alias file.txt                     📄 Template access (default target)
+[bold bright_blue]--file[/bold bright_blue] ci:data file.csv                   💻 Code Interpreter upload
+[bold bright_blue]--file[/bold bright_blue] fs:docs file.pdf                   🔍 File Search vector store
+[bold bright_blue]--file[/bold bright_blue] prompt:config config.yaml         📄 Template access (explicit)
+
+[bold bright_blue]--dir[/bold bright_blue] alias ./src                         📁 Directory attachment (template)
+[bold bright_blue]--dir[/bold bright_blue] ci:data ./datasets                  📂 Code execution directory
+[bold bright_blue]--dir[/bold bright_blue] fs:docs ./documentation             📁 Search directory"""
+
+    attachment_panel = Panel(
+        attachment_content,
+        title="[bold]📎 File Attachment System[/bold]",
+        border_style="blue",
+        padding=(1, 2),
+    )
+    console.print(attachment_panel)
+
+    # Multi-tool Routing
+    routing_content = """[bold cyan]--file ci,fs:shared data.csv[/bold cyan]              Share file between Code Interpreter and File Search
+[bold cyan]--file prompt,ci:config settings.json[/bold cyan]    Make file available in template AND Code Interpreter"""
+
+    routing_panel = Panel(
+        routing_content,
+        title="[bold]🔄 Multi-Tool Routing[/bold]",
+        border_style="cyan",
+        padding=(1, 2),
+    )
+    console.print(routing_panel)
+
+    # File Collections
+    collections_content = """[bold green]--collect all:files @filelist.txt[/bold green]         📄 Attach multiple files from list
+[bold green]--collect ci:data @datasets.txt[/bold green]           💻 Upload file collection to Code Interpreter"""
+
+    collections_panel = Panel(
+        collections_content,
+        title="[bold]📝 File Collections[/bold]",
+        border_style="green",
+        padding=(1, 2),
+    )
+    console.print(collections_panel)
+
+    # Variables and Tools
+    vars_tools_content = """[bold yellow]Variables:[/bold yellow]
+[cyan]-V name=value[/cyan]                             Simple string variables
+[cyan]-J config='{"key":"value"}'[/cyan]               JSON structured data
+
+[bold yellow]Tools:[/bold yellow]
+[cyan]--enable-tool web-search[/cyan]                  🌐 Real-time web search for current info
+[cyan]--mcp-server label@https://server.com/sse[/cyan] MCP server integration
+[cyan]--timeout 7200[/cyan]                           2-hour timeout for long operations"""
+
+    vars_tools_panel = Panel(
+        vars_tools_content,
+        title="[bold]🏷️ Variables & 🔌 Tools[/bold]",
+        border_style="yellow",
+        padding=(1, 2),
+    )
+    console.print(vars_tools_panel)
+
+    # Common Patterns
+    console.print(Text("⚡ Common Patterns", style="bold bright_green"))
+    console.print()
+
+    patterns = [
+        (
+            "Basic template rendering",
+            "ostruct run template.j2 schema.json -V env=prod",
+        ),
+        (
+            "Data analysis with Code Interpreter",
+            "ostruct run analysis.j2 schema.json --file ci:data data.csv -V task=analyze",
+        ),
+        (
+            "Document search + processing",
+            "ostruct run search.j2 schema.json --file fs:docs docs/ --file config config.yaml",
+        ),
+        (
+            "Multi-tool workflow",
+            "ostruct run workflow.j2 schema.json --file ci:data raw_data.csv --file fs:knowledge knowledge/ --file config config.json",
+        ),
+        (
+            "Current information research",
+            'ostruct run research.j2 schema.json --enable-tool web-search -V topic="latest AI developments"',
+        ),
+    ]
+
+    for desc, cmd in patterns:
+        console.print(f"[dim]# {desc}[/dim]")
+        syntax = Syntax(
+            cmd, "bash", theme="monokai", background_color="default"
+        )
+        console.print(syntax)
+        console.print()
+
+    # Footer with help links
+    footer_content = """📖 [cyan]ostruct run --help[/cyan]           Detailed options reference
+📖 [cyan]ostruct run --help-debug[/cyan]      Troubleshooting guide
+📖 [dim]https://ostruct.readthedocs.io[/dim]   Full documentation"""
+
+    footer_panel = Panel(
+        footer_content,
+        title="[bold]📖 More Help[/bold]",
+        border_style="blue",
+        padding=(1, 2),
+    )
+    console.print(footer_panel)