hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/cli/commands/create_cmd.py

@@ -0,0 +1,208 @@
+"""Pipeline creation commands for HexDAG CLI."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+import yaml
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command("pipeline")
+def create_pipeline(
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            "-n",
+            help="Pipeline name",
+        ),
+    ] = None,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output file path (default: <name>.yaml)",
+        ),
+    ] = None,
+    template: Annotated[
+        str,
+        typer.Option(
+            "--template",
+            "-t",
+            help="Template type (minimal, example, full)",
+        ),
+    ] = "minimal",
+) -> None:
+    """Create a new pipeline YAML file from a template.
+
+    Examples
+    --------
+    hexdag create pipeline
+    hexdag create pipeline --name my-pipeline
+    hexdag create pipeline --template example --output pipeline.yaml
+    """
+    # Interactive mode if name not provided
+    if name is None:
+        name = Prompt.ask("[cyan]Pipeline name[/cyan]", default="my-pipeline")
+
+    # Determine output path
+    if output is None:
+        output = Path(f"{name}.yaml")
+
+    if output.exists():
+        if not Confirm.ask(f"[yellow]File {output} already exists. Overwrite?[/yellow]"):
+            console.print("[red]Aborted.[/red]")
+            raise typer.Exit(1)
+
+    if template == "minimal":
+        pipeline = {
+            "apiVersion": "hexdag/v1",
+            "kind": "Pipeline",
+            "metadata": {
+                "name": name,
+                "description": "TODO: Add description",
+            },
+            "spec": {
+                "nodes": [
+                    {
+                        "kind": "hexdag.builtin.nodes.FunctionNode",
+                        "metadata": {"name": "step1"},
+                        "spec": {
+                            "fn": "my_module.my_function",
+                            "input_mapping": {"x": "input.value"},
+                            "dependencies": [],
+                        },
+                    }
+                ]
+            },
+        }
+    elif template == "example":
+        pipeline = {
+            "apiVersion": "hexdag/v1",
+            "kind": "Pipeline",
+            "metadata": {
+                "name": name,
+                "description": "Example multi-step pipeline",
+                "version": "1.0",
+                "tags": ["example", "demo"],
+            },
+            "spec": {
+                "ports": {
+                    "llm": {
+                        "adapter": "hexdag.builtin.adapters.mock.MockLLM",
+                        "config": {},
+                    }
+                },
+                "nodes": [
+                    {
+                        "kind": "hexdag.builtin.nodes.FunctionNode",
+                        "metadata": {
+                            "name": "input_processor",
+                            "annotations": {"description": "Process input data"},
+                        },
+                        "spec": {
+                            "fn": "my_module.process_input",
+                            "input_mapping": {"data": "input.raw_data"},
+                            "dependencies": [],
+                        },
+                    },
+                    {
+                        "kind": "hexdag.builtin.nodes.LLMNode",
+                        "metadata": {
+                            "name": "analyzer",
+                            "annotations": {"description": "Analyze processed data"},
+                        },
+                        "spec": {
+                            "prompt_template": "Analyze this data: {{input_processor}}",
+                            "dependencies": ["input_processor"],
+                        },
+                    },
+                    {
+                        "kind": "hexdag.builtin.nodes.FunctionNode",
+                        "metadata": {
+                            "name": "output_formatter",
+                            "annotations": {"description": "Format final output"},
+                        },
+                        "spec": {
+                            "fn": "my_module.format_output",
+                            "input_mapping": {"result": "analyzer"},
+                            "dependencies": ["analyzer"],
+                        },
+                    },
+                ],
+            },
+        }
+    else:  # full
+        pipeline = {
+            "apiVersion": "hexdag/v1",
+            "kind": "Pipeline",
+            "metadata": {
+                "name": name,
+                "description": "Full-featured pipeline template",
+                "version": "1.0",
+                "author": "Your Name",
+                "tags": ["production", "template"],
+            },
+            "spec": {
+                "input_schema": {
+                    "type": "object",
+                    "properties": {"data": {"type": "string"}},
+                    "required": ["data"],
+                },
+                "ports": {
+                    "llm": {
+                        "adapter": "hexdag.builtin.adapters.mock.MockLLM",
+                        "config": {},
+                    }
+                },
+                "common_field_mappings": {"default_mapping": {"value": "input.data"}},
+                "nodes": [
+                    {
+                        "kind": "hexdag.builtin.nodes.FunctionNode",
+                        "metadata": {
+                            "name": "validator",
+                            "annotations": {
+                                "description": "Validate input",
+                                "timeout": "5s",
+                            },
+                        },
+                        "spec": {
+                            "fn": "my_module.validate_input",
+                            "input_mapping": {"data": "input.data"},
+                            "output_schema": {
+                                "type": "object",
+                                "properties": {"valid": {"type": "boolean"}},
+                            },
+                            "dependencies": [],
+                        },
+                    },
+                    {
+                        "kind": "hexdag.builtin.nodes.LLMNode",
+                        "metadata": {"name": "processor"},
+                        "spec": {
+                            "prompt_template": "Process: {{validator.result}}",
+                            "output_schema": {
+                                "type": "object",
+                                "properties": {"processed": {"type": "string"}},
+                            },
+                            "dependencies": ["validator"],
+                        },
+                    },
+                ],
+            },
+        }
+
+    # Write to file
+    with Path.open(output, "w") as f:
+        yaml.dump(pipeline, f, default_flow_style=False, sort_keys=False)
+
+    console.print(f"[green]✓[/green] Created pipeline: {output}")
+    console.print("\n[cyan]Next steps:[/cyan]")
+    console.print(f"  1. Edit {output} to customize your pipeline")
+    console.print(f"  2. Validate: [bold]hexdag validate {output}[/bold]")

hexdag/cli/commands/docs_cmd.py

@@ -0,0 +1,293 @@
+"""CLI commands for MkDocs documentation."""
+
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+app = typer.Typer(help="Generate and serve documentation with MkDocs")
+console = Console()
+
+
+@app.command("build")
+def build_docs(
+    clean: bool = typer.Option(
+        False,
+        "--clean",
+        "-c",
+        help="Clean site directory before building",
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        "-s",
+        help="Enable strict mode (warnings as errors)",
+    ),
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        help="Path to TOML configuration file (pyproject.toml or hexdag.toml)",
+    ),
+) -> None:
+    """Build documentation site with MkDocs.
+
+    Generates static HTML documentation from markdown files and the component
+    registry. The registry hooks automatically generate reference documentation
+    during the build process.
+
+    You can specify a custom TOML configuration to document your project's
+    specific components, plugins, and adapters.
+
+    Examples:
+        hexdag docs build
+        hexdag docs build --clean
+        hexdag docs build --strict
+        hexdag docs build --config /path/to/myproject/pyproject.toml
+    """
+    import os
+
+    try:
+        if config:
+            if not config.exists():
+                console.print(f"[red]✗[/red] Config file not found: {config}")
+                raise typer.Exit(1)
+            os.environ["HEXDAG_CONFIG_PATH"] = str(config.resolve())
+            console.print(
+                Panel.fit(
+                    "[bold cyan]Building Documentation[/bold cyan]\n"
+                    "Using MkDocs with registry hooks\n"
+                    f"Config: {config}",
+                    border_style="cyan",
+                )
+            )
+        else:
+            console.print(
+                Panel.fit(
+                    "[bold cyan]Building Documentation[/bold cyan]\n"
+                    "Using MkDocs with registry hooks",
+                    border_style="cyan",
+                )
+            )
+
+        cmd = ["mkdocs", "build"]
+        if clean:
+            cmd.append("--clean")
+        if strict:
+            cmd.append("--strict")
+
+        result = subprocess.run(cmd, capture_output=True, text=True, env=os.environ.copy())  # nosec B603
+
+        if result.returncode == 0:
+            console.print("\n[green]✓[/green] Documentation built successfully!")
+            console.print("\n[dim]Site output: ./site/[/dim]")
+            console.print("[dim]View locally: hexdag docs serve[/dim]")
+        else:
+            console.print("\n[red]✗[/red] Build failed:")
+            console.print(result.stderr)
+            raise typer.Exit(1)
+
+    except FileNotFoundError:
+        console.print("\n[red]✗[/red] MkDocs not found. Install with:")
+        console.print("  [cyan]pip install hexdag[docs][/cyan]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"\n[red]✗[/red] Error building documentation: {e}")
+        raise typer.Exit(1)
+
+
+@app.command("serve")
+def serve_docs(
+    port: int = typer.Option(
+        8000,
+        "--port",
+        "-p",
+        help="Port to serve on",
+    ),
+    host: str = typer.Option(
+        "127.0.0.1",
+        "--host",
+        "-h",
+        help="Host to bind to",
+    ),
+    watch_theme: bool = typer.Option(
+        False,
+        "--watch-theme",
+        help="Watch theme directory for changes",
+    ),
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        help="Path to TOML configuration file (pyproject.toml or hexdag.toml)",
+    ),
+) -> None:
+    """Serve documentation with live reload.
+
+    Starts MkDocs development server with live reload. The server watches for
+    changes in markdown files and automatically regenerates registry documentation.
+
+    You can specify a custom TOML configuration to document your project's
+    specific components, plugins, and adapters.
+
+    Examples:
+        hexdag docs serve
+        hexdag docs serve --port 8080
+        hexdag docs serve --watch-theme
+        hexdag docs serve --config /path/to/myproject/pyproject.toml
+    """
+    import os
+
+    try:
+        if config:
+            if not config.exists():
+                console.print(f"[red]✗[/red] Config file not found: {config}")
+                raise typer.Exit(1)
+            os.environ["HEXDAG_CONFIG_PATH"] = str(config.resolve())
+            console.print(
+                Panel.fit(
+                    "[bold cyan]MkDocs Development Server[/bold cyan]\n"
+                    f"URL: http://{host}:{port}\n"
+                    "Live reload: Enabled\n"
+                    f"Config: {config}",
+                    border_style="cyan",
+                )
+            )
+        else:
+            console.print(
+                Panel.fit(
+                    "[bold cyan]MkDocs Development Server[/bold cyan]\n"
+                    f"URL: http://{host}:{port}\n"
+                    "Live reload: Enabled",
+                    border_style="cyan",
+                )
+            )
+
+        cmd = ["mkdocs", "serve", "--dev-addr", f"{host}:{port}"]
+        if watch_theme:
+            cmd.append("--watch-theme")
+
+        console.print(f"\n[green]✓[/green] Starting server at [cyan]http://{host}:{port}[/cyan]")
+        console.print("\nPress [red]Ctrl+C[/red] to stop the server\n")
+
+        # Run mkdocs serve (blocking)
+        subprocess.run(cmd, env=os.environ.copy())  # nosec B603
+
+    except FileNotFoundError:
+        console.print("\n[red]✗[/red] MkDocs not found. Install with:")
+        console.print("  [cyan]pip install hexdag[docs][/cyan]")
+        raise typer.Exit(1)
+    except KeyboardInterrupt:
+        console.print("\n\n[yellow]Server stopped[/yellow]")
+    except Exception as e:
+        console.print(f"\n[red]✗[/red] Error starting server: {e}")
+        raise typer.Exit(1)
+
+
+@app.command("deploy")
+def deploy_docs(
+    remote_branch: str = typer.Option(
+        "gh-pages",
+        "--remote-branch",
+        "-b",
+        help="Remote branch to deploy to",
+    ),
+    message: str | None = typer.Option(
+        None,
+        "--message",
+        "-m",
+        help="Commit message for deploy",
+    ),
+) -> None:
+    """Deploy documentation to GitHub Pages.
+
+    Builds and deploys documentation to the specified remote branch (default: gh-pages).
+    Requires git repository with GitHub remote configured.
+
+    Examples:
+        hexdag docs deploy
+        hexdag docs deploy --message "Update docs"
+        hexdag docs deploy --remote-branch main
+    """
+    try:
+        console.print(
+            Panel.fit(
+                f"[bold cyan]Deploying Documentation[/bold cyan]\nRemote branch: {remote_branch}",
+                border_style="cyan",
+            )
+        )
+
+        cmd = ["mkdocs", "gh-deploy", "--remote-branch", remote_branch]
+        if message:
+            cmd.extend(["--message", message])
+
+        result = subprocess.run(cmd, capture_output=True, text=True)  # nosec B603
+
+        if result.returncode == 0:
+            console.print("\n[green]✓[/green] Documentation deployed successfully!")
+        else:
+            console.print("\n[red]✗[/red] Deploy failed:")
+            console.print(result.stderr)
+            raise typer.Exit(1)
+
+    except FileNotFoundError:
+        console.print("\n[red]✗[/red] MkDocs not found. Install with:")
+        console.print("  [cyan]pip install hexdag[docs][/cyan]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"\n[red]✗[/red] Error deploying documentation: {e}")
+        raise typer.Exit(1)
+
+
+@app.command("new")
+def new_page(
+    path: str = typer.Argument(..., help="Path for new page (e.g., guide/my-guide.md)"),
+    title: str | None = typer.Option(None, "--title", "-t", help="Page title"),
+) -> None:
+    """Create a new documentation page.
+
+    Creates a new markdown file with basic frontmatter and adds it to the
+    documentation structure.
+
+    Examples:
+        hexdag docs new guide/custom-nodes.md
+        hexdag docs new guide/advanced.md --title "Advanced Usage"
+    """
+    docs_dir = Path("docs")
+    if not docs_dir.exists():
+        console.print(f"[red]✗[/red] Documentation directory not found: {docs_dir}")
+        raise typer.Exit(1)
+
+    file_path = docs_dir / path
+    if file_path.exists():
+        console.print(f"[red]✗[/red] File already exists: {file_path}")
+        raise typer.Exit(1)
+
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Generate title from filename if not provided
+    if not title:
+        title = file_path.stem.replace("-", " ").replace("_", " ").title()
+
+    content = f"""# {title}
+
+Add your content here.
+
+## Overview
+
+...
+
+## Examples
+
+...
+
+## Next Steps
+
+...
+"""
+
+    file_path.write_text(content)
+
+    console.print(f"[green]✓[/green] Created new page: [cyan]{file_path}[/cyan]")
+    console.print("\nRemember to add it to [cyan]mkdocs.yml[/cyan] navigation:")
+    console.print(f"  - {title}: {path}")