applied-cli 0.5.7__tar.gz → 0.5.9__tar.gz

{applied_cli-0.5.7 → applied_cli-0.5.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: applied-cli
-Version: 0.5.7
+Version: 0.5.9
 Summary: CLI and shared client library for Applied Labs AI support agents
 Author: Applied Labs
 License-Expression: MIT

{applied_cli-0.5.7 → applied_cli-0.5.9}/applied_cli/__init__.py

@@ -4,6 +4,6 @@ from applied_cli import tools
 from applied_cli.client import AppliedClient
 from applied_cli.formatters import to_csv, to_json
 
-__version__ = "0.5.5"
+__version__ = "0.5.9"
 
 __all__ = ["AppliedClient", "tools", "to_csv", "to_json", "__version__"]

{applied_cli-0.5.7 → applied_cli-0.5.9}/applied_cli/client.py

@@ -1,5 +1,8 @@
 """Applied Labs API client."""
 
+import asyncio
+import json
+import uuid
 from typing import Any
 
 import httpx
@@ -250,6 +253,19 @@ class AppliedClient:
     # Flow Nodes
     # -------------------------------------------------------------------------
 
+    async def get_node(self, flow_id: str, node_id: str) -> dict | None:
+        """Get a single node with full configuration.
+
+        Returns None if node not found.
+        """
+        flow = await self.get_flow(flow_id)
+        graph = flow.get("graph", {})
+        nodes = graph.get("nodes", [])
+        for node in nodes:
+            if node.get("id") == node_id:
+                return node
+        return None
+
     async def create_node(
         self,
         flow_id: str,
@@ -341,10 +357,44 @@ class AppliedClient:
         self,
         flow_id: str,
         trigger_data: dict[str, Any] | None = None,
+        wait: bool = False,
+        wait_timeout: float = 60.0,
+        poll_interval: float = 1.0,
     ) -> dict:
-        """Execute a flow with trigger data."""
+        """Execute a flow with trigger data.
+
+        Args:
+            flow_id: The flow UUID
+            trigger_data: Trigger input data
+            wait: If True, poll until the run completes and include spans
+            wait_timeout: Max seconds to wait for completion (default 60)
+            poll_interval: Seconds between polls (default 1)
+
+        Returns:
+            Flow run with spans if wait=True
+        """
         body = {"trigger": trigger_data or {}}
-        return await self._request("POST", f"/v1/flows/{flow_id}/run/", body=body)
+        run = await self._request("POST", f"/v1/flows/{flow_id}/run/", body=body)
+
+        if not wait:
+            return run
+
+        # Poll until completion
+        run_id = run.get("id")
+        if not run_id:
+            return run
+
+        elapsed = 0.0
+        while elapsed < wait_timeout:
+            run = await self.get_flow_run(run_id)
+            status = run.get("status", "")
+            if status in ("Success", "Failed", "Cancelled"):
+                return run
+            await asyncio.sleep(poll_interval)
+            elapsed += poll_interval
+
+        # Timeout - return current state
+        return run
 
     async def list_flow_runs(
         self,
@@ -395,6 +445,31 @@ class AppliedClient:
     # Conversational Testing (via streaming /complete endpoint)
     # -------------------------------------------------------------------------
 
+    async def create_conversation(
+        self,
+        agent_id: str,
+        is_test: bool = True,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new conversation for an agent.
+
+        Args:
+            agent_id: The agent UUID
+            is_test: Whether this is a test conversation (default True)
+            metadata: Optional metadata for the conversation
+
+        Returns:
+            Dict with conversation id
+        """
+        body: dict[str, Any] = {
+            "agent_id": agent_id,
+            "is_test": is_test,
+        }
+        if metadata:
+            body["metadata"] = metadata
+
+        return await self._request("POST", "/v1/c/", body=body)
+
     async def send_message(
         self,
         agent_id: str,
@@ -410,6 +485,8 @@ class AppliedClient:
         This calls the /complete endpoint (streaming) and consumes the full
         response. Use this for testing conversational flows.
 
+        If no conversation_id is provided, a new conversation is created first.
+
         Args:
             agent_id: The agent UUID
             message: The user message to send
@@ -420,46 +497,51 @@ class AppliedClient:
             metadata: Optional metadata dict for the conversation
 
         Returns:
-            Dict with conversation_id, response_text, and status
+            Dict with conversation_id, response, and status
         """
-        headers = {
-            "Authorization": f"Bearer {self.token}",
+        # Build metadata with contact info
+        meta = metadata.copy() if metadata else {}
+        if contact_email:
+            meta["email"] = contact_email
+        if contact_name:
+            meta["name"] = contact_name
+        if contact_phone:
+            meta["phone"] = contact_phone
+
+        # Create conversation if needed
+        result_conversation_id = conversation_id
+        if not result_conversation_id:
+            conv = await self.create_conversation(
+                agent_id=agent_id,
+                is_test=True,
+                metadata=meta if meta else None,
+            )
+            result_conversation_id = conv["id"]
+
+        # /complete endpoint uses AllowAny - no auth header needed
+        headers: dict[str, str] = {
             "Content-Type": "application/json",
-            "Accept": "text/event-stream",
         }
-        if self.shop_id:
-            headers["X-Shop-Id"] = self.shop_id
 
         body: dict[str, Any] = {
-            "input": message,
+            "conversation_id": result_conversation_id,
             "transcript": [
                 {
+                    "id": str(uuid.uuid4()),
                     "role": "user",
                     "content": message,
                     "text": message,
-                    "format": "markdown",
+                    "format": "MARKDOWN",
                 }
             ],
         }
 
-        if conversation_id:
-            body["conversation_id"] = conversation_id
-
-        # Build metadata with contact info
-        meta = metadata or {}
-        if contact_email:
-            meta["email"] = contact_email
-        if contact_name:
-            meta["name"] = contact_name
-        if contact_phone:
-            meta["phone"] = contact_phone
         if meta:
             body["metadata"] = meta
 
         url = f"{self.base_url}/v1/agents/{agent_id}/complete/"
 
         response_text = ""
-        result_conversation_id = conversation_id
 
         async with (
             httpx.AsyncClient(timeout=120.0) as client,
@@ -467,32 +549,19 @@ class AppliedClient:
         ):
             response.raise_for_status()
 
+            # v1 streaming format: JSON objects on each line
             async for line in response.aiter_lines():
                 if not line:
                     continue
 
-                # Parse SSE format: "data: {...}"
-                if line.startswith("data: "):
-                    data_str = line[6:]  # Remove "data: " prefix
-                    if data_str == "[DONE]":
-                        break
-
-                    try:
-                        import json
-
-                        data = json.loads(data_str)
-
-                        # Extract conversation_id from first chunk
-                        if not result_conversation_id:
-                            result_conversation_id = data.get("conversation_id")
-
-                        # Accumulate response content
-                        if "content" in data:
-                            response_text += data["content"]
-
-                    except (json.JSONDecodeError, KeyError):
-                        # Skip malformed chunks
-                        pass
+                # Try to parse as JSON directly (v1 format)
+                try:
+                    data = json.loads(line)
+                    if "content" in data:
+                        response_text += data["content"]
+                except json.JSONDecodeError:
+                    # Skip non-JSON lines
+                    pass
 
         return {
             "conversation_id": result_conversation_id,

{applied_cli-0.5.7 → applied_cli-0.5.9}/applied_cli/tools.py

@@ -256,6 +256,7 @@ async def flow_list(
 async def flow_get(
     client: AppliedClient,
     flow_id: str,
+    output_format: str = "summary",
 ) -> str:
     """
     Get a flow with its full graph (nodes and edges).
@@ -263,15 +264,20 @@ async def flow_get(
     Args:
         client: Authenticated AppliedClient
         flow_id: The flow UUID
+        output_format: 'summary' (default), 'full' (includes node metadata/prompts),
+                       or 'json' (raw JSON)
 
     Returns:
-        Flow metadata, nodes table, and edges table
+        Flow metadata, nodes, and edges. Use 'full' to see node configurations.
     """
     flow = await client.get_flow(flow_id)
     graph = flow.get("graph", {})
     nodes = graph.get("nodes", [])
     edges = graph.get("edges", [])
 
+    if output_format == "json":
+        return to_json(flow)
+
     # Format header
     result = f"# Flow: {flow.get('name')}\n"
     result += f"id: {flow.get('id')}\n"
@@ -285,15 +291,48 @@ async def flow_get(
 
     # Format nodes
     result += f"\n## Nodes ({len(nodes)})\n"
-    node_rows = [
-        {
-            "id": n.get("id"),
-            "type": n.get("type", n.get("data", {}).get("name", "")),
-            "description": n.get("data", {}).get("description", "")[:50],
-        }
-        for n in nodes
-    ]
-    result += to_csv(node_rows, ["id", "type", "description"])
+
+    if output_format == "full":
+        # Full output: include metadata, prompt, schemas for each node
+        for n in nodes:
+            data = n.get("data", {})
+            node_name = data.get("name", n.get("id", ""))
+            node_type = n.get("type", data.get("executor_type", ""))
+
+            result += f"\n### {node_name}"
+            if node_type and node_type != node_name:
+                result += f" ({node_type})"
+            result += "\n"
+            result += f"id: {n.get('id')}\n"
+
+            if data.get("description"):
+                result += f"description: {data.get('description')}\n"
+
+            if data.get("prompt"):
+                prompt_preview = data.get("prompt", "")
+                if len(prompt_preview) > 300:
+                    prompt_preview = prompt_preview[:300] + "..."
+                result += f"prompt: {prompt_preview}\n"
+
+            metadata = data.get("metadata", {})
+            if metadata:
+                result += f"metadata: {json.dumps(metadata)}\n"
+
+            outputs = data.get("outputs", {})
+            if outputs and outputs.get("properties"):
+                props = list(outputs.get("properties", {}).keys())
+                result += f"output_fields: {', '.join(props)}\n"
+    else:
+        # Summary output: table format
+        node_rows = [
+            {
+                "id": n.get("id"),
+                "type": n.get("type", n.get("data", {}).get("name", "")),
+                "description": n.get("data", {}).get("description", "")[:50],
+            }
+            for n in nodes
+        ]
+        result += to_csv(node_rows, ["id", "type", "description"])
 
     # Format edges
     result += f"\n## Edges ({len(edges)})\n"
@@ -415,6 +454,60 @@ async def flow_delete(
 # -----------------------------------------------------------------------------
 
 
+async def flow_node_get(
+    client: AppliedClient,
+    flow_id: str,
+    node_id: str,
+) -> str:
+    """
+    Get a single node's full configuration.
+
+    Args:
+        client: Authenticated AppliedClient
+        flow_id: The flow UUID
+        node_id: The node UUID
+
+    Returns:
+        Full node config including metadata, prompt, executor type, and schemas
+    """
+    node = await client.get_node(flow_id, node_id)
+
+    if not node:
+        return f"Node {node_id} not found in flow {flow_id}"
+
+    data = node.get("data", {})
+
+    result = f"# Node: {data.get('name', node_id)}\n"
+    result += f"id: {node.get('id')}\n"
+    result += f"type: {node.get('type', data.get('executor_type', ''))}\n"
+
+    if data.get("description"):
+        result += f"description: {data.get('description')}\n"
+
+    if data.get("prompt"):
+        result += f"\n## Prompt\n{data.get('prompt')}\n"
+
+    # Full metadata
+    metadata = data.get("metadata", {})
+    if metadata:
+        result += "\n## Metadata\n"
+        result += json.dumps(metadata, indent=2) + "\n"
+
+    # Input schema
+    inputs = data.get("inputs", {})
+    if inputs:
+        result += "\n## Input Schema\n"
+        result += json.dumps(inputs, indent=2) + "\n"
+
+    # Output schema
+    outputs = data.get("outputs", {})
+    if outputs:
+        result += "\n## Output Schema\n"
+        result += json.dumps(outputs, indent=2) + "\n"
+
+    return result
+
+
 async def flow_node_create(
     client: AppliedClient,
     flow_id: str,
@@ -616,6 +709,8 @@ async def flow_run(
     client: AppliedClient,
     flow_id: str,
     trigger_data: dict | None = None,
+    wait: bool = True,
+    wait_timeout: float = 60.0,
 ) -> str:
     """
     Execute a flow with test input.
@@ -627,17 +722,76 @@ async def flow_run(
             {"message": "Hello"}
             {"message": "Help me", "contact": {"email": "user@example.com"}}
             {"conversation_id": "uuid-of-existing-conversation"}
+        wait: If True (default), wait for completion and return full trace.
+              If False, return immediately with just the run ID.
+        wait_timeout: Max seconds to wait (default 60)
 
     Returns:
-        Flow run ID, status, and actions summary
+        Flow run with execution trace (if wait=True) or just run ID
     """
-    run = await client.run_flow(flow_id, trigger_data)
+    run = await client.run_flow(
+        flow_id,
+        trigger_data,
+        wait=wait,
+        wait_timeout=wait_timeout,
+    )
 
     result = f"# Flow Run: {run.get('id')}\n"
     result += f"status: {run.get('status')}\n"
     result += f"started_at: {run.get('started_at')}\n"
-    result += f"ended_at: {run.get('ended_at')}\n"
 
+    if run.get("ended_at"):
+        result += f"ended_at: {run.get('ended_at')}\n"
+    if run.get("duration"):
+        result += f"duration: {run.get('duration')}s\n"
+
+    # Execution trace from spans
+    spans = run.get("spans", [])
+    if spans:
+        result += f"\n## Execution Trace ({len(spans)} spans)\n"
+        for i, span in enumerate(spans, 1):
+            name = span.get("span_name", "")
+            duration = span.get("duration", 0)
+            status = span.get("status_code", "")
+            status_msg = span.get("status_message", "")
+            attrs = span.get("span_attributes", {})
+
+            status_str = "OK" if "OK" in str(status) else "ERROR"
+            result += f"{i}. [{name}] {duration:.2f}s - {status_str}"
+            if status_msg:
+                result += f" - {status_msg}"
+            result += "\n"
+
+            # Show output for executor_run spans
+            if name == "executor_run" and attrs.get("output"):
+                try:
+                    output_data = json.loads(attrs["output"])
+                    for k, v in output_data.items():
+                        if k == "success":
+                            continue
+                        result += f"   output.{k}: {str(v)[:300]}\n"
+                except (json.JSONDecodeError, TypeError):
+                    result += f"   output: {str(attrs['output'])[:500]}\n"
+
+            # completion: show the LLM text output
+            elif name == "completion" and attrs.get("content"):
+                result += f"   completion: {str(attrs['content'])[:500]}\n"
+
+            # structured_completion: show parsed output
+            elif name == "structured_completion" and attrs.get("output"):
+                try:
+                    out = json.loads(attrs["output"])
+                    result += f"   output: {json.dumps(out, indent=None)[:400]}\n"
+                except (json.JSONDecodeError, TypeError):
+                    result += f"   output: {str(attrs['output'])[:400]}\n"
+
+            # branch: show routing decision
+            elif name == "branch":
+                selected = attrs.get("selected.path", "")
+                if selected:
+                    result += f"   selected: {selected}\n"
+
+    # Actions summary
     actions = run.get("actions", [])
     if actions:
         result += f"\n## Actions ({len(actions)})\n"
@@ -650,6 +804,21 @@ async def flow_run(
         ]
         result += to_csv(action_rows, ["node", "status"])
 
+    # Errors
+    errors = [s for s in spans if "ERROR" in str(s.get("status_code", ""))]
+    if errors:
+        result += "\n## Errors\n"
+        for err in errors:
+            attrs = err.get("span_attributes", {})
+            node_name = attrs.get("tool_name") or err.get("span_name") or "unknown"
+            error_msg = err.get("status_message", "")
+            result += f"**Node:** {node_name}\n"
+            if error_msg:
+                result += f"**Error:** {error_msg}\n"
+            if attrs.get("output"):
+                result += f"**Output:** {str(attrs.get('output'))[:500]}\n"
+            result += "\n"
+
     return result
 
 
@@ -949,82 +1118,415 @@ async def send_message(
 
 async def executor_list(
     client: AppliedClient,
-    output_format: str = "csv",
+    output_format: str = "full",
 ) -> str:
     """
-    List available node types (executors).
+    List available node types (executors) with their metadata schemas.
 
     Args:
         client: Authenticated AppliedClient (not used, list is hardcoded)
-        output_format: 'csv' or 'json'
+        output_format: 'full' (default, includes schemas), 'csv' (names only), 'json'
 
     Returns:
-        Available executor types with descriptions
+        Available executor types with descriptions and metadata field schemas
     """
-    # Hardcoded list of common executors
+    # Hardcoded list of executors with metadata schemas
     executors = [
         {
             "name": "completion",
-            "description": "LLM completion node - generates free-form text response",
-            "use_case": "Generate responses, summaries, or any text output",
+            "description": "LLM completion - generates free-form text",
+            "use_case": "Responses, summaries, any text output",
+            "metadata_fields": {
+                "model": "string - LLM model (default: agent's model)",
+                "temperature": "float - 0.0-1.0 (default: 0.7)",
+                "max_tokens": "int - max output tokens",
+            },
+            "output_fields": ["completion"],
         },
         {
             "name": "structured_completion",
             "description": "LLM completion with structured JSON output",
-            "use_case": "Extract data, classify, or generate typed responses",
+            "use_case": "Extract data, classify, typed responses",
+            "metadata_fields": {
+                "model": "string - LLM model",
+                "output_schema": "object - JSON Schema for output structure",
+            },
+            "output_fields": ["(defined by output_schema)"],
         },
         {
             "name": "branch",
-            "description": "Conditional branching based on LLM decision",
-            "use_case": "Route flow based on user intent or conditions",
+            "description": "Conditional branching based on comparison or LLM",
+            "use_case": "Route flow based on conditions",
+            "metadata_fields": {
+                "branch_type": "'comparison' or 'llm'",
+                "branches": "array - branch definitions with conditions",
+            },
+            "output_fields": ["selected_branch"],
         },
         {
-            "name": "loop",
-            "description": "Loop over a list and execute nodes for each item",
-            "use_case": "Process multiple items, batch operations",
+            "name": "code",
+            "description": "Execute Python code in sandbox",
+            "use_case": "Data transformation, calculations, API calls",
+            "metadata_fields": {
+                "language": "string - 'python' (required)",
+                "code": "string - Python code to execute (required)",
+                "packages": "array - pip packages to install, e.g. ['requests']",
+            },
+            "output_fields": ["result", "stdout", "stderr"],
         },
         {
             "name": "http_request",
             "description": "Make HTTP API calls",
             "use_case": "Integrate with external APIs",
+            "metadata_fields": {
+                "method": "string - GET, POST, PUT, DELETE",
+                "url": "string - endpoint URL (supports {var} interpolation)",
+                "headers": "object - request headers",
+                "body": "object - request body for POST/PUT",
+            },
+            "output_fields": ["status_code", "data", "headers"],
         },
         {
-            "name": "code",
-            "description": "Execute Python code",
-            "use_case": "Data transformation, calculations",
+            "name": "loop",
+            "description": "Loop over a list and execute subflow",
+            "use_case": "Process multiple items, batch operations",
+            "metadata_fields": {
+                "items_path": "string - variable path to iterate, e.g. {trigger.items}",
+                "max_iterations": "int - limit iterations",
+            },
+            "output_fields": ["results", "count"],
         },
         {
             "name": "memory",
             "description": "Store/retrieve data in conversation memory",
-            "use_case": "Remember user preferences, context",
+            "use_case": "Remember user preferences, context across turns",
+            "metadata_fields": {
+                "operation": "'get' or 'set'",
+                "key": "string - memory key",
+                "value": "any - value to store (for set)",
+            },
+            "output_fields": ["value"],
         },
         {
-            "name": "global",
-            "description": "Global handler for escalation or failure",
-            "use_case": "Catch-all for errors or escalation intents",
+            "name": "search",
+            "description": "Search knowledge base",
+            "use_case": "Find relevant documentation or Q&A",
+            "metadata_fields": {
+                "query": "string - search query (supports {var} interpolation)",
+                "limit": "int - max results",
+            },
+            "output_fields": ["results", "count"],
         },
         {
-            "name": "end_flow",
-            "description": "Explicitly end the flow",
-            "use_case": "Terminate flow execution",
+            "name": "global",
+            "description": "Global handler for escalation or failure",
+            "use_case": "Catch-all for errors, default handler",
+            "metadata_fields": {},
+            "output_fields": [],
         },
         {
             "name": "_escalate_conversation",
             "description": "Escalate conversation to human agent",
             "use_case": "Hand off to support team",
+            "metadata_fields": {
+                "reason": "string - escalation reason",
+            },
+            "output_fields": [],
         },
         {
             "name": "handoff",
             "description": "Hand off to another flow or agent",
             "use_case": "Transfer to specialized flow",
+            "metadata_fields": {
+                "target_flow_id": "string - flow to hand off to",
+            },
+            "output_fields": [],
         },
         {
-            "name": "search",
-            "description": "Search knowledge base",
-            "use_case": "Find relevant documentation or Q&A",
+            "name": "end_flow",
+            "description": "Explicitly end the flow",
+            "use_case": "Terminate flow execution early",
+            "metadata_fields": {},
+            "output_fields": [],
         },
     ]
 
     if output_format == "csv":
-        return to_csv(executors, ["name", "description", "use_case"])
-    return to_json(executors)
+        simple = [
+            {"name": e["name"], "description": e["description"]} for e in executors
+        ]
+        return to_csv(simple, ["name", "description"])
+
+    if output_format == "json":
+        return to_json(executors)
+
+    # Full output with schemas
+    result = "# Available Node Types (Executors)\n\n"
+    result += "Use these with flow_node_create(executor_type=...)\n\n"
+
+    for ex in executors:
+        result += f"## {ex['name']}\n"
+        result += f"{ex['description']}\n"
+        result += f"Use case: {ex['use_case']}\n"
+
+        if ex.get("metadata_fields"):
+            result += "\n**Metadata fields:**\n"
+            for field, desc in ex["metadata_fields"].items():
+                result += f"  - `{field}`: {desc}\n"
+
+        if ex.get("output_fields"):
+            result += f"\n**Output fields:** {', '.join(ex['output_fields'])}\n"
+
+        result += "\n"
+
+    result += "## Variable Reference Syntax\n"
+    result += "Reference previous node outputs in prompts and metadata:\n"
+    result += "- `{trigger.message}` - user's input message\n"
+    result += "- `{trigger.contact.email}` - contact email\n"
+    result += "- `{node_name.field}` - output from previous node\n"
+    result += "- `{code-abc123.result}` - code node output\n"
+    result += "- `{http_request-xyz.data.items}` - nested API response\n"
+
+    return result
+
+
+# -----------------------------------------------------------------------------
+# Flow Variables
+# -----------------------------------------------------------------------------
+
+
+def _extract_schema_paths(
+    schema: dict,
+    prefix: str = "",
+    defs: dict | None = None,
+    max_depth: int = 4,
+) -> list[dict]:
+    """
+    Recursively extract variable paths from a JSON Schema.
+
+    Returns list of {"path": "field.subfield", "type": "string", "description": "..."}
+    """
+    if max_depth <= 0:
+        return []
+
+    defs = defs or schema.get("$defs", {})
+    paths = []
+
+    # Handle $ref
+    if "$ref" in schema:
+        ref_name = schema["$ref"].split("/")[-1]
+        if ref_name in defs:
+            return _extract_schema_paths(defs[ref_name], prefix, defs, max_depth)
+        return []
+
+    # Handle anyOf/oneOf (take first option)
+    if "anyOf" in schema:
+        for option in schema["anyOf"]:
+            if option.get("type") != "null":
+                return _extract_schema_paths(option, prefix, defs, max_depth)
+        return []
+
+    schema_type = schema.get("type", "")
+
+    if schema_type == "object":
+        props = schema.get("properties", {})
+        for prop_name, prop_schema in props.items():
+            path = f"{prefix}.{prop_name}" if prefix else prop_name
+            prop_type = prop_schema.get("type", "any")
+            desc = prop_schema.get("description", "")
+
+            # Add this path
+            paths.append({"path": path, "type": prop_type, "description": desc[:60]})
+
+            # Recurse for nested objects/arrays
+            if prop_type == "object":
+                paths.extend(
+                    _extract_schema_paths(prop_schema, path, defs, max_depth - 1)
+                )
+            elif prop_type == "array":
+                items = prop_schema.get("items", {})
+                if items:
+                    # Add [0] and [*] access patterns
+                    paths.append(
+                        {
+                            "path": f"{path}[0]",
+                            "type": "item",
+                            "description": "First item",
+                        }
+                    )
+                    paths.append(
+                        {
+                            "path": f"{path}[*]",
+                            "type": "list",
+                            "description": "Map over all",
+                        }
+                    )
+                    # Recurse into array items
+                    paths.extend(
+                        _extract_schema_paths(items, f"{path}[0]", defs, max_depth - 1)
+                    )
+
+    elif schema_type == "array":
+        items = schema.get("items", {})
+        if items and prefix:
+            paths.append(
+                {"path": f"{prefix}[0]", "type": "item", "description": "First item"}
+            )
+            paths.extend(
+                _extract_schema_paths(items, f"{prefix}[0]", defs, max_depth - 1)
+            )
+
+    return paths
+
+
+def _topological_sort(nodes: list[dict], edges: list[dict]) -> list[dict]:
+    """Sort nodes in topological order based on edges."""
+    # Build adjacency and in-degree
+    node_map = {n["id"]: n for n in nodes}
+    in_degree = {n["id"]: 0 for n in nodes}
+    children = {n["id"]: [] for n in nodes}
+
+    for e in edges:
+        src, tgt = e.get("source"), e.get("target")
+        if src in node_map and tgt in node_map:
+            children[src].append(tgt)
+            in_degree[tgt] = in_degree.get(tgt, 0) + 1
+
+    # Kahn's algorithm
+    queue = [nid for nid, deg in in_degree.items() if deg == 0]
+    result = []
+
+    while queue:
+        nid = queue.pop(0)
+        result.append(node_map[nid])
+        for child in children.get(nid, []):
+            in_degree[child] -= 1
+            if in_degree[child] == 0:
+                queue.append(child)
+
+    return result
+
+
+async def flow_variables(
+    client: AppliedClient,
+    flow_id: str,
+    node_id: str | None = None,
+) -> str:
+    """
+    List available variables for a flow, showing what can be referenced in prompts
+    and node configurations using {node_name.field} syntax.
+
+    Args:
+        client: Authenticated AppliedClient
+        flow_id: The flow UUID
+        node_id: Optional - show only variables available to this specific node
+                 (predecessors in the graph). If omitted, shows all variables.
+
+    Returns:
+        Formatted list of available variables grouped by source node,
+        with paths, types, and descriptions.
+
+    Example output:
+        ## 1. trigger
+        {trigger.message}              string   User's message
+        {trigger.contact.email}        string   Contact email
+        {trigger.shop.is_open}         boolean  Business hours check
+
+        ## 2. http_request-abc123
+        {http_request-abc123.data}     object   Response data
+        {http_request-abc123.status_code} integer HTTP status
+    """
+    flow = await client.get_flow(flow_id)
+    graph = flow.get("graph", {})
+    nodes = graph.get("nodes", [])
+    edges = graph.get("edges", [])
+
+    # Sort nodes topologically
+    sorted_nodes = _topological_sort(nodes, edges)
+
+    # If node_id specified, find its predecessors
+    if node_id:
+        # Build predecessor set via BFS backwards
+        parents = {n["id"]: set() for n in nodes}
+        for e in edges:
+            tgt = e.get("target")
+            src = e.get("source")
+            if tgt and src:
+                parents[tgt].add(src)
+
+        # BFS to find all ancestors
+        ancestors = set()
+        queue = list(parents.get(node_id, set()))
+        while queue:
+            p = queue.pop(0)
+            if p not in ancestors:
+                ancestors.add(p)
+                queue.extend(parents.get(p, set()))
+
+        # Filter to only ancestor nodes
+        sorted_nodes = [n for n in sorted_nodes if n["id"] in ancestors]
+
+    result = "# Available Variables for Flow\n"
+    result += "Use {node_name.field} syntax in prompts and metadata.\n\n"
+
+    for idx, node in enumerate(sorted_nodes, 1):
+        node_data = node.get("data", {})
+        node_name = node_data.get("name", node.get("id", ""))
+        node_type = node.get("type", node_data.get("executor_type", ""))
+        outputs = node_data.get("outputs", {})
+
+        # Skip nodes without output schema
+        if not outputs or not outputs.get("properties"):
+            continue
+
+        result += f"## {idx}. {node_name}"
+        if node_type and node_type != node_name:
+            result += f" ({node_type})"
+        result += "\n"
+
+        # Extract paths from schema
+        paths = _extract_schema_paths(outputs)
+
+        for p in paths[:20]:  # Limit to avoid overwhelming output
+            var_path = f"{{{node_name}.{p['path']}}}"
+            type_str = p["type"][:10].ljust(10)
+            desc = p["description"][:40] if p["description"] else ""
+            result += f"  {var_path:<45} {type_str} {desc}\n"
+
+        if len(paths) > 20:
+            result += f"  ... and {len(paths) - 20} more fields\n"
+
+        result += "\n"
+
+    if not result.strip().endswith("\n\n"):
+        result += "\n"
+
+    result += "## Built-in Trigger Context (llm.call trigger)\n"
+    result += "The trigger node always provides these fields:\n\n"
+    result += "**{trigger.shop}** - Workspace/shop object:\n"
+    result += "  - {trigger.shop.is_open} (boolean) - whether shop is currently open\n"
+    result += "  - {trigger.shop.name} (string)\n"
+    result += "  - {trigger.shop.timezone} (string)\n"
+    result += "  - {trigger.shop.address} (string)\n"
+    result += "\n"
+    result += "**{trigger.contact}** - Customer contact:\n"
+    result += "  - {trigger.contact.email} (string)\n"
+    result += "  - {trigger.contact.name} (string)\n"
+    result += "  - {trigger.contact.phone} (string)\n"
+    result += "\n"
+    result += "**{trigger.conversation}** - Current conversation:\n"
+    result += "  - {trigger.conversation.id} (string)\n"
+    result += "  - {trigger.conversation.title} (string)\n"
+    result += "  - {trigger.conversation.resolution} (string)\n"
+    result += "\n"
+    result += "**{trigger.messages}** - Message history (array)\n"
+    result += "**{trigger.attachments}** - Uploaded files (array)\n"
+    result += "**{trigger.current_time}** - ISO timestamp (string)\n"
+    result += "\n"
+    result += "## Tips\n"
+    result += "- Use {trigger.shop.is_open} directly in branch conditions\n"
+    result += "- Reference previous nodes by full name: {completion-abc.completion}\n"
+    result += "- Access nested fields with dots: {trigger.contact.email}\n"
+    result += "- Access array items: {trigger.messages[0].text}\n"
+
+    return result

{applied_cli-0.5.7 → applied_cli-0.5.9}/applied_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: applied-cli
-Version: 0.5.7
+Version: 0.5.9
 Summary: CLI and shared client library for Applied Labs AI support agents
 Author: Applied Labs
 License-Expression: MIT

{applied_cli-0.5.7 → applied_cli-0.5.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "applied-cli"
-version = "0.5.7"
+version = "0.5.9"
 description = "CLI and shared client library for Applied Labs AI support agents"
 readme = "README.md"
 requires-python = ">=3.11"