yamlgraph 0.3.9__py3-none-any.whl

examples/codegen/tools/template_tools.py

@@ -0,0 +1,356 @@
+"""Template extraction tools for implementation agent.
+
+Extract reusable templates from existing code for consistent new code generation.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+
+def extract_function_template(file_path: str, function_name: str) -> dict:
+    """Extract reusable function template.
+
+    Args:
+        file_path: Path to the Python file
+        function_name: Name of the function to extract
+
+    Returns:
+        dict with 'template' string showing reusable pattern
+        or dict with 'error' key if failed
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return {"error": f"File not found: {file_path}"}
+
+    try:
+        source = path.read_text()
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        return {"error": f"Syntax error: {e}"}
+
+    # Find the function
+    target = None
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef) and node.name == function_name:
+            target = node
+            break
+
+    if target is None:
+        return {"error": f"Function '{function_name}' not found in {file_path}"}
+
+    # Extract template
+    lines = source.splitlines()
+    template_parts = []
+
+    # Build signature line
+    sig = _build_signature(target)
+    template_parts.append(sig)
+
+    # Extract docstring
+    docstring = ast.get_docstring(target)
+    if docstring:
+        template_parts.append(f'    """{docstring}"""')
+
+    # Extract body structure
+    body_template = _extract_body_structure(target, lines)
+    template_parts.append(body_template)
+
+    return {"template": "\n".join(template_parts)}
+
+
+def _build_signature(func: ast.FunctionDef) -> str:
+    """Build function signature with type hints."""
+    args = []
+    for arg in func.args.args:
+        if arg.annotation:
+            ann = _get_annotation(arg.annotation)
+            args.append(f"{arg.arg}: {ann}")
+        else:
+            args.append(arg.arg)
+
+    # Handle defaults
+    defaults = func.args.defaults
+    num_defaults = len(defaults)
+    if num_defaults > 0:
+        for i, default in enumerate(defaults):
+            idx = len(args) - num_defaults + i
+            default_val = _get_value(default)
+            args[idx] = f"{args[idx]} = {default_val}"
+
+    ret = ""
+    if func.returns:
+        ret = f" -> {_get_annotation(func.returns)}"
+
+    return f"def {func.name}({', '.join(args)}){ret}:"
+
+
+def _get_annotation(node: ast.expr) -> str:
+    """Extract type annotation as string."""
+    if isinstance(node, ast.Name):
+        return node.id
+    elif isinstance(node, ast.Constant):
+        return repr(node.value)
+    elif isinstance(node, ast.Subscript):
+        value = _get_annotation(node.value)
+        slice_val = _get_annotation(node.slice)
+        return f"{value}[{slice_val}]"
+    elif isinstance(node, ast.Attribute):
+        return f"{_get_annotation(node.value)}.{node.attr}"
+    elif isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr):
+        left = _get_annotation(node.left)
+        right = _get_annotation(node.right)
+        return f"{left} | {right}"
+    return "..."
+
+
+def _get_value(node: ast.expr) -> str:
+    """Extract default value as string."""
+    if isinstance(node, ast.Constant):
+        return repr(node.value)
+    elif isinstance(node, ast.Name):
+        return node.id
+    elif isinstance(node, ast.List):
+        return "[]"
+    elif isinstance(node, ast.Dict):
+        return "{}"
+    return "..."
+
+
+def _extract_body_structure(func: ast.FunctionDef, lines: list[str]) -> str:
+    """Extract body structure as template."""
+    body_parts = []
+
+    for node in func.body:
+        # Skip docstring
+        if (
+            isinstance(node, ast.Expr)
+            and isinstance(node.value, ast.Constant)
+            and isinstance(node.value.value, str)
+        ):
+            continue
+
+        if isinstance(node, ast.Try):
+            body_parts.append("    try:")
+            body_parts.append("        {try_block}")
+            for handler in node.handlers:
+                exc = _get_annotation(handler.type) if handler.type else "Exception"
+                body_parts.append(f"    except {exc}:")
+                body_parts.append("        {except_block}")
+        elif isinstance(node, ast.If):
+            body_parts.append("    if {condition}:")
+            body_parts.append("        {if_block}")
+        elif isinstance(node, ast.For):
+            body_parts.append("    for {item} in {iterable}:")
+            body_parts.append("        {loop_block}")
+        elif isinstance(node, ast.Return):
+            if node.value:
+                ret_val = _format_return(node.value)
+                body_parts.append(f"    return {ret_val}")
+            else:
+                body_parts.append("    return")
+        else:
+            # Generic statement
+            stmt_lines = lines[node.lineno - 1 : node.end_lineno]
+            for line in stmt_lines:
+                body_parts.append(line)
+
+    if not body_parts:
+        body_parts.append("    pass")
+
+    return "\n".join(body_parts)
+
+
+def _format_return(node: ast.expr) -> str:
+    """Format return value for template."""
+    if isinstance(node, ast.Dict):
+        items = []
+        for k, v in zip(node.keys, node.values, strict=False):
+            key = _get_value(k) if k else "..."
+            val = "{result}" if isinstance(v, ast.Name) else _get_value(v)
+            items.append(f"{key}: {val}")
+        return "{" + ", ".join(items) + "}"
+    elif isinstance(node, ast.Call):
+        return "{function_call}"
+    return "{result}"
+
+
+def extract_class_template(file_path: str, class_name: str) -> dict:
+    """Extract reusable class template.
+
+    Args:
+        file_path: Path to the Python file
+        class_name: Name of the class to extract
+
+    Returns:
+        dict with 'template' string showing reusable pattern
+        or dict with 'error' key if failed
+    """
+    path = Path(file_path)
+    if not path.exists():
+        return {"error": f"File not found: {file_path}"}
+
+    try:
+        source = path.read_text()
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        return {"error": f"Syntax error: {e}"}
+
+    # Find the class
+    target = None
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef) and node.name == class_name:
+            target = node
+            break
+
+    if target is None:
+        return {"error": f"Class '{class_name}' not found in {file_path}"}
+
+    template_parts = []
+
+    # Class signature with bases
+    bases = [_get_annotation(b) for b in target.bases]
+    if bases:
+        template_parts.append(f"class {class_name}({', '.join(bases)}):")
+    else:
+        template_parts.append(f"class {class_name}:")
+
+    # Docstring
+    docstring = ast.get_docstring(target)
+    if docstring:
+        template_parts.append(f'    """{docstring}"""')
+
+    # Class variables
+    for node in target.body:
+        if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            name = node.target.id
+            ann = _get_annotation(node.annotation)
+            if node.value:
+                val = _get_value(node.value)
+                template_parts.append(f"    {name}: {ann} = {val}")
+            else:
+                template_parts.append(f"    {name}: {ann}")
+
+    # Methods (signatures only)
+    for node in target.body:
+        if isinstance(node, ast.FunctionDef):
+            sig = _build_signature(node)
+            template_parts.append("")
+            template_parts.append(f"    {sig}")
+            # Method docstring
+            method_doc = ast.get_docstring(node)
+            if method_doc:
+                short_doc = method_doc.split("\n")[0]
+                template_parts.append(f'        """{short_doc}"""')
+            template_parts.append("        ...")
+
+    return {"template": "\n".join(template_parts)}
+
+
+def extract_test_template(test_file: str, target_module: str) -> dict:
+    """Extract test patterns for reuse.
+
+    Args:
+        test_file: Path to the test file
+        target_module: Module being tested
+
+    Returns:
+        dict with 'template' string showing test patterns
+        or dict with 'error' key if failed
+    """
+    path = Path(test_file)
+    if not path.exists():
+        return {"error": f"File not found: {test_file}"}
+
+    try:
+        source = path.read_text()
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        return {"error": f"Syntax error: {e}"}
+
+    template_parts = []
+    lines = source.splitlines()
+
+    # Find imports
+    imports = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == "pytest":
+                    imports.append("import pytest")
+        elif isinstance(node, ast.ImportFrom) and node.module and "mock" in node.module:
+            names = ", ".join(a.name for a in node.names)
+            imports.append(f"from {node.module} import {names}")
+
+    if imports:
+        template_parts.extend(imports)
+        template_parts.append("")
+
+    # Find fixtures
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef):
+            for decorator in node.decorator_list:
+                if isinstance(decorator, ast.Attribute) and decorator.attr == "fixture":
+                    template_parts.append("@pytest.fixture")
+                    sig = _build_signature(node)
+                    template_parts.append(f"{sig}")
+                    template_parts.append("    {fixture_implementation}")
+                    template_parts.append("")
+                elif isinstance(decorator, ast.Name) and "fixture" in decorator.id:
+                    template_parts.append(f"@{decorator.id}")
+                    sig = _build_signature(node)
+                    template_parts.append(f"{sig}")
+                    template_parts.append("    {fixture_implementation}")
+                    template_parts.append("")
+
+    # Find test classes
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef) and node.name.startswith("Test"):
+            template_parts.append(f"class {node.name}:")
+            docstring = ast.get_docstring(node)
+            if docstring:
+                template_parts.append(f'    """{docstring}"""')
+            template_parts.append("")
+
+            # Extract test method patterns
+            for method in node.body:
+                if isinstance(method, ast.FunctionDef) and method.name.startswith(
+                    "test_"
+                ):
+                    sig = _build_signature(method)
+                    template_parts.append(f"    {sig}")
+                    template_parts.append("        {test_implementation}")
+                    template_parts.append("")
+            break  # Just use first test class as pattern
+
+    # Find standalone test functions with patch
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef) and node.name.startswith("test_"):
+            # Check for patch usage in body
+            func_source = "\n".join(lines[node.lineno - 1 : node.end_lineno])
+            if "patch" in func_source:
+                template_parts.append("def {test_name}():")
+                template_parts.append('    with patch("{module}.{target}") as mock:')
+                template_parts.append("        mock.return_value = {mock_value}")
+                template_parts.append("        {test_implementation}")
+                break
+
+    if not template_parts:
+        # Provide minimal template
+        template_parts = [
+            "import pytest",
+            f"from {target_module} import {{symbols}}",
+            "",
+            "class Test{{ClassName}}:",
+            '    """Tests for {{symbol}}."""',
+            "",
+            "    def test_basic(self):",
+            "        {test_implementation}",
+        ]
+
+    return {"template": "\n".join(template_parts)}

examples/fastapi_interview.py

@@ -0,0 +1,167 @@
+"""FastAPI example with async graph execution.
+
+Demonstrates:
+- Async graph loading and compilation
+- Interrupt handling via HTTP endpoints
+- Thread-based session management
+
+Run:
+    pip install fastapi uvicorn
+    uvicorn examples.fastapi_interview:app --reload
+
+Usage:
+    # Start a new session
+    curl -X POST http://localhost:8000/chat/session1 -d '{"message": "start"}'
+
+    # Resume after interrupt (provide user's name)
+    curl -X POST http://localhost:8000/chat/session1/resume -d '{"answer": "Alice"}'
+"""
+
+import logging
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from langgraph.types import Command
+from pydantic import BaseModel
+
+from yamlgraph.executor_async import load_and_compile_async, run_graph_async
+
+logger = logging.getLogger(__name__)
+
+# Global compiled graph (loaded once at startup)
+_app = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Load graph at startup."""
+    global _app
+    try:
+        _app = await load_and_compile_async("graphs/interview-demo.yaml")
+        logger.info("✅ Graph loaded and compiled")
+    except FileNotFoundError:
+        logger.warning("⚠️ interview-demo.yaml not found, using mock mode")
+        _app = None
+    yield
+
+
+app = FastAPI(
+    title="YAMLGraph Interview Demo",
+    description="Async interview graph with interrupt support",
+    lifespan=lifespan,
+)
+
+
+class ChatRequest(BaseModel):
+    """Request to start or continue chat."""
+
+    message: str = "start"
+
+
+class ResumeRequest(BaseModel):
+    """Request to resume after interrupt."""
+
+    answer: str
+
+
+class ChatResponse(BaseModel):
+    """Response from chat endpoint."""
+
+    status: str
+    question: str | None = None
+    response: str | None = None
+    state: dict[str, Any] | None = None
+
+
+@app.post("/chat/{thread_id}", response_model=ChatResponse)
+async def chat(thread_id: str, request: ChatRequest) -> ChatResponse:
+    """Start or continue a chat session.
+
+    If graph hits an interrupt, returns status="waiting" with the question.
+    Otherwise returns status="complete" with the response.
+    """
+    if _app is None:
+        raise HTTPException(status_code=503, detail="Graph not loaded")
+
+    config = {"configurable": {"thread_id": thread_id}}
+
+    try:
+        result = await run_graph_async(
+            _app,
+            initial_state={"input": request.message},
+            config=config,
+        )
+    except Exception as e:
+        logger.error(f"Graph execution error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+    # Check for interrupt
+    if "__interrupt__" in result:
+        interrupt_value = result["__interrupt__"][0].value
+        question = interrupt_value.get("question") or interrupt_value.get(
+            "prompt", str(interrupt_value)
+        )
+        return ChatResponse(
+            status="waiting",
+            question=question,
+            state={k: v for k, v in result.items() if not k.startswith("_")},
+        )
+
+    return ChatResponse(
+        status="complete",
+        response=result.get("greeting") or result.get("response"),
+        state={k: v for k, v in result.items() if not k.startswith("_")},
+    )
+
+
+@app.post("/chat/{thread_id}/resume", response_model=ChatResponse)
+async def resume(thread_id: str, request: ResumeRequest) -> ChatResponse:
+    """Resume a paused chat session with user's answer.
+
+    Uses LangGraph's Command(resume=...) to continue execution.
+    """
+    if _app is None:
+        raise HTTPException(status_code=503, detail="Graph not loaded")
+
+    config = {"configurable": {"thread_id": thread_id}}
+
+    try:
+        result = await run_graph_async(
+            _app,
+            initial_state=Command(resume=request.answer),
+            config=config,
+        )
+    except Exception as e:
+        logger.error(f"Graph resume error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+    # Check for another interrupt
+    if "__interrupt__" in result:
+        interrupt_value = result["__interrupt__"][0].value
+        question = interrupt_value.get("question") or interrupt_value.get(
+            "prompt", str(interrupt_value)
+        )
+        return ChatResponse(
+            status="waiting",
+            question=question,
+            state={k: v for k, v in result.items() if not k.startswith("_")},
+        )
+
+    return ChatResponse(
+        status="complete",
+        response=result.get("greeting") or result.get("response"),
+        state={k: v for k, v in result.items() if not k.startswith("_")},
+    )
+
+
+@app.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {"status": "ok", "graph_loaded": _app is not None}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)

examples/npc/api/__init__.py

@@ -0,0 +1 @@
+"""NPC Encounter Web API."""

examples/npc/api/app.py

@@ -0,0 +1,100 @@
+"""NPC Encounter Web UI - FastAPI Application.
+
+HTMX-powered web interface for running NPC encounters.
+Uses YAMLGraph for encounter logic with session persistence.
+
+Usage:
+    uvicorn examples.npc.api.app:app --reload
+
+    # Or with custom port
+    uvicorn examples.npc.api.app:app --reload --port 8080
+"""
+
+import logging
+import uuid
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+
+from examples.npc.api.routes.encounter import router as encounter_router
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifecycle handler."""
+    logger.info("🚀 Starting NPC Encounter Web UI...")
+    logger.info("📍 Templates: examples/npc/api/templates")
+    logger.info("📦 Static files: examples/npc/api/static")
+    yield
+    logger.info("👋 Shutting down NPC Encounter Web UI...")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="NPC Encounter Web UI",
+    description="HTMX-powered web interface for running NPC encounters",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# Templates
+templates = Jinja2Templates(directory="examples/npc/api/templates")
+
+# Include routers
+app.include_router(encounter_router)
+
+# Mount static files (create directory if needed)
+try:
+    app.mount(
+        "/static", StaticFiles(directory="examples/npc/api/static"), name="static"
+    )
+except RuntimeError:
+    # Static directory doesn't exist, that's fine
+    logger.warning("⚠️ Static directory not found, skipping static mount")
+
+# Mount outputs directory for generated images
+try:
+    app.mount("/outputs", StaticFiles(directory="outputs"), name="outputs")
+    logger.info("📁 Mounted outputs directory for generated images")
+except RuntimeError:
+    logger.warning("⚠️ Outputs directory not found, skipping outputs mount")
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index(request: Request):
+    """Render the main encounter page."""
+    # Generate a unique session ID for this encounter
+    session_id = str(uuid.uuid4())[:8]
+
+    return templates.TemplateResponse(
+        request=request,
+        name="index.html",
+        context={"session_id": session_id},
+    )
+
+
+@app.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {"status": "healthy", "service": "npc-encounter-api"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "examples.npc.api.app:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+    )

examples/npc/api/routes/__init__.py

@@ -0,0 +1,5 @@
+"""API routes for NPC encounters."""
+
+from .encounter import router as encounter_router
+
+__all__ = ["encounter_router"]