feat(agent): Viral Tech Copywriter

examples/templates/viral_tech_copywriter/README.md

@@ -0,0 +1,45 @@
+# Viral Tech Copywriter
+
+## What it does
+
+- **Job:** Turns a **marketing brief** (collected in chat) into **structured brief JSON**,
+  then **hooks plus per-channel copy**, then **exports** the bundle as **HTML** and/or **Markdown**
+  (`save_data` / `append_data` / `serve_file_to_user` only—no extra tools package features).
+- **Flow:** `intake` (HITL) → `normalize-brief` → `write-package` → `deliver-exports` (terminal).
+  Delivery uses **hive-tools** MCP: `save_data`, `append_data`, `serve_file_to_user`,
+  `load_data`, `list_data_files`, `edit_data`.
+- **Honesty:** Prompts forbid inventing metrics, customers, or quotes. Uncertain claims belong
+  in `verify_flags` / notes.
+
+## Run
+
+`mcp_servers.json` **must** be present next to this package (it ships with the template).
+**`run`** and **`tui`** call `ViralTechCopywriterAgent.load_hive_tools_registry()` at startup and
+**exit with a clear error** if the file is missing, instead of failing later when delivery tools
+are invoked. The config starts the hive-tools MCP server from the repo `tools/` directory
+(`uv run python mcp_server.py --stdio`).
+
+```bash
+PYTHONPATH=core:examples/templates uv run python -m viral_tech_copywriter validate
+PYTHONPATH=core:examples/templates uv run python -m viral_tech_copywriter tui
+```
+
+Configure the LLM via `~/.hive/configuration.json` like other Hive agents.
+
+## Outputs
+
+- **`raw_brief`:** Plain text from intake.
+- **`structured_brief`:** JSON string (product, ICP, value props, platforms, etc.).
+- **`copy_package`:** JSON string (`hooks[]`, `channels{}`, optional `notes`).
+- **`delivered_artifacts`:** JSON string listing chosen formats and served files (URIs/paths).
+
+**HTML** is served with `open_in_browser=true` when possible. **Markdown** (e.g.
+`viral_copywriter_report.md`) is served as a **clickable file link** (`open_in_browser=false`)
+so the user can open it in an editor or preview.
+
+## Tests
+
+```bash
+PYTHONPATH=core:examples/templates uv run python -m pytest \
+  examples/templates/viral_tech_copywriter/tests/ -v
+```

examples/templates/viral_tech_copywriter/__init__.py

@@ -0,0 +1,40 @@
+"""
+Viral Tech Copywriter — conversational brief to multi-channel tech marketing copy.
+
+Flow: intake → normalize-brief → write-package → deliver-exports (HTML/Markdown via hive-tools MCP).
+"""
+
+from __future__ import annotations
+
+from .agent import (
+    ViralTechCopywriterAgent,
+    default_agent,
+    edges,
+    entry_node,
+    entry_points,
+    goal,
+    nodes,
+    pause_nodes,
+    skip_credential_validation,
+    terminal_nodes,
+)
+from .config import AgentMetadata, RuntimeConfig, default_config, metadata
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ViralTechCopywriterAgent",
+    "default_agent",
+    "goal",
+    "nodes",
+    "edges",
+    "entry_node",
+    "entry_points",
+    "pause_nodes",
+    "terminal_nodes",
+    "skip_credential_validation",
+    "RuntimeConfig",
+    "AgentMetadata",
+    "default_config",
+    "metadata",
+]

examples/templates/viral_tech_copywriter/__main__.py

@@ -0,0 +1,163 @@
+"""
+CLI for Viral Tech Copywriter — TUI, validate, info, and non-TUI run entry points.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+
+import click
+
+from .agent import ViralTechCopywriterAgent, default_agent
+
+
+def setup_logging(verbose: bool = False, debug: bool = False) -> None:
+    if debug:
+        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+    elif verbose:
+        level, fmt = logging.INFO, "%(message)s"
+    else:
+        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+    logging.getLogger("framework").setLevel(level)
+
+
+@click.group()
+@click.version_option(version="1.0.0")
+def cli() -> None:
+    """Viral Tech Copywriter — brief to hooks and channel copy."""
+    pass
+
+
+@cli.command("run")
+@click.option("--quiet", "-q", is_flag=True, help="Only output result JSON")
+@click.option("--verbose", "-v", is_flag=True, help="Show execution details")
+@click.option("--debug", is_flag=True, help="Show debug logging")
+def run_cmd(quiet: bool, verbose: bool, debug: bool) -> None:
+    """Execute one graph run (uses intake; best suited for TUI or scripted harness)."""
+    if not quiet:
+        setup_logging(verbose=verbose, debug=debug)
+
+    try:
+        result = asyncio.run(default_agent.run({}))
+    except FileNotFoundError as exc:
+        click.echo(str(exc), err=True)
+        sys.exit(1)
+
+    output_data = {
+        "success": result.success,
+        "steps_executed": result.steps_executed,
+        "output": result.output,
+    }
+    if result.error:
+        output_data["error"] = result.error
+
+    click.echo(json.dumps(output_data, indent=2, default=str))
+    sys.exit(0 if result.success else 1)
+
+
+@cli.command()
+@click.option("--verbose", "-v", is_flag=True, help="Show execution details")
+@click.option("--debug", is_flag=True, help="Show debug logging")
+def tui(verbose: bool, debug: bool) -> None:
+    """Launch the TUI for interactive copywriting."""
+    setup_logging(verbose=verbose, debug=debug)
+
+    try:
+        from framework.tui.app import AdenTUI
+    except ImportError:
+        click.echo("TUI requires the 'textual' package. Install with: uv pip install textual")
+        sys.exit(1)
+
+    from pathlib import Path
+
+    from framework.llm import LiteLLMProvider
+    from framework.runtime.agent_runtime import create_agent_runtime
+    from framework.runtime.execution_stream import EntryPointSpec
+
+    async def run_with_tui() -> None:
+        agent = ViralTechCopywriterAgent()
+        registry = ViralTechCopywriterAgent.load_hive_tools_registry()
+
+        storage_path = Path.home() / ".hive" / "agents" / "viral_tech_copywriter"
+        storage_path.mkdir(parents=True, exist_ok=True)
+
+        llm = LiteLLMProvider(
+            model=agent.config.model,
+            api_key=agent.config.api_key,
+            api_base=agent.config.api_base,
+        )
+
+        tools = list(registry.get_tools().values())
+        tool_executor = registry.get_executor()
+        graph = agent._build_graph()
+
+        runtime = create_agent_runtime(
+            graph=graph,
+            goal=agent.goal,
+            storage_path=storage_path,
+            entry_points=[
+                EntryPointSpec(
+                    id="start",
+                    name="Start copywriter",
+                    entry_node="intake",
+                    trigger_type="manual",
+                    isolation_level="isolated",
+                ),
+            ],
+            llm=llm,
+            tools=tools,
+            tool_executor=tool_executor,
+        )
+
+        await runtime.start()
+
+        try:
+            app = AdenTUI(runtime)
+            await app.run_async()
+        finally:
+            await runtime.stop()
+
+    try:
+        asyncio.run(run_with_tui())
+    except FileNotFoundError as exc:
+        click.echo(str(exc), err=True)
+        sys.exit(1)
+
+
+@cli.command()
+@click.option("--json", "output_json", is_flag=True)
+def info(output_json: bool) -> None:
+    """Show agent metadata and graph summary."""
+    info_data = default_agent.info()
+    if output_json:
+        click.echo(json.dumps(info_data, indent=2))
+    else:
+        click.echo(f"Agent: {info_data['name']}")
+        click.echo(f"Description: {info_data['description']}")
+        click.echo(f"\nNodes: {', '.join(info_data['nodes'])}")
+        click.echo(f"Client-facing: {', '.join(info_data['client_facing_nodes'])}")
+        click.echo(f"Entry: {info_data['entry_node']}")
+        click.echo(f"Terminal: {', '.join(info_data['terminal_nodes'])}")
+
+
+@cli.command()
+def validate() -> None:
+    """Validate graph structure."""
+    validation = default_agent.validate()
+    if validation["valid"]:
+        click.echo("Agent is valid")
+        for warning in validation["warnings"]:
+            click.echo(f"  WARNING: {warning}")
+    else:
+        click.echo("Agent has errors:")
+        for error in validation["errors"]:
+            click.echo(f"  ERROR: {error}")
+    sys.exit(0 if validation["valid"] else 1)
+
+
+if __name__ == "__main__":
+    cli()