venn-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{venn_cli-0.1.0 → venn_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: venn-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: CLI for the Venn ToolIQ API
 Project-URL: Homepage, https://github.com/moda-labs/venn-cli
 Project-URL: Repository, https://github.com/moda-labs/venn-cli
@@ -21,6 +21,7 @@ Requires-Python: >=3.11
 Requires-Dist: click>=8.1
 Requires-Dist: httpx>=0.27
 Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'

{venn_cli-0.1.0 → venn_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "venn-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "CLI for the Venn ToolIQ API"
 requires-python = ">=3.11"
 license = "MIT"
@@ -21,6 +21,7 @@ classifiers = [
 dependencies = [
     "click>=8.1",
     "httpx>=0.27",
+    "pyyaml>=6.0",
     "rich>=13.0",
     "python-dotenv>=1.0",
 ]

venn_cli-0.2.0/src/venn_cli/cli.py

@@ -0,0 +1,461 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv
+
+from venn_cli.client import VennClient
+from venn_cli import output
+
+
+def _load_env() -> None:
+    for p in [Path.cwd() / ".env", Path(__file__).resolve().parents[2] / ".env"]:
+        if p.exists():
+            load_dotenv(p)
+            return
+    load_dotenv()
+
+
+def _client(ctx: click.Context) -> VennClient:
+    return ctx.obj["client"]
+
+
+def _mode(ctx: click.Context) -> str:
+    return ctx.obj["mode"]
+
+
+def _out(ctx: click.Context, *, yaml_fn, table_fn, data):
+    mode = _mode(ctx)
+    if mode == "json":
+        output.print_json(data)
+    elif mode == "table":
+        table_fn()
+    else:
+        yaml_fn()
+
+
+@click.group()
+@click.option("--api-key", envvar="VENN_API_KEY", help="Venn API key (or set VENN_API_KEY)")
+@click.option("--base-url", envvar="VENN_BASE_URL", default=None, help="Override API base URL")
+@click.option("--json", "use_json", is_flag=True, help="Output raw JSON")
+@click.option("--table", "use_table", is_flag=True, help="Output rich tables (for terminals)")
+@click.version_option(package_name="venn-cli")
+@click.pass_context
+def main(ctx: click.Context, api_key: str | None, base_url: str | None, use_json: bool, use_table: bool) -> None:
+    """Venn ToolIQ CLI — discover, inspect, and execute tools."""
+    _load_env()
+    ctx.ensure_object(dict)
+    if use_json:
+        ctx.obj["mode"] = "json"
+    elif use_table:
+        ctx.obj["mode"] = "table"
+    else:
+        ctx.obj["mode"] = "text"
+    api_key = api_key or os.environ.get("VENN_API_KEY")
+    if ctx.invoked_subcommand == "docs":
+        return
+    if not api_key:
+        click.echo("Error: VENN_API_KEY not set. Pass --api-key or add it to .env", err=True)
+        raise SystemExit(1)
+    kwargs = {"api_key": api_key}
+    if base_url:
+        kwargs["base_url"] = base_url
+    ctx.obj["client"] = VennClient(**kwargs)
+
+
+# ---------------------------------------------------------------------------
+# venn docs
+# ---------------------------------------------------------------------------
+
+DOCS = """\
+# Venn CLI
+
+Tool discovery and execution across connected MCP servers.
+Default output is compact text optimized for LLM context windows.
+Use `--json` for raw JSON or `--table` for rich terminal tables.
+
+## Setup
+
+Set VENN_API_KEY as an environment variable or in a .env file.
+
+## Typical workflow
+
+1. `venn help list_servers` — see connected servers and their IDs
+2. `venn tools search "<intent>"` — find tools by natural language
+3. `venn tools describe -s <server_id> -t <tool>` — get full schema and params
+4. `venn tools execute -s <server_id> -t <tool> -a '<json args>'` — run it
+   For write operations, add `--confirm` to auto-obtain a confirmation token.
+
+## Commands
+
+### venn tools search <query>
+Search for tools across all connected servers using semantic similarity.
+Returns ranked results — tools and skills.
+  -n, --limit INT       Max results (default: 10)
+  --offset INT          Skip N results (default: 0)
+  --min-score FLOAT     Minimum similarity (0-1, default: 0.3)
+  --refresh             Bypass cache
+Example: venn tools search "create calendar event" -n 5
+
+### venn tools list -s <slug>
+List all tools for a specific server/toolset.
+  -s, --slug TEXT          Toolset slug (e.g. "gmail", "slack")
+  -d, --directory-id TEXT  Server directory UUID
+  -i, --instance-id TEXT   Server instance UUID
+At least one identifier is required.
+Example: venn tools list -s gmail
+
+### venn tools describe -s <server_id> -t <tool_name>
+Get detailed schema for one or more tools — description, params, types.
+  -s, --server-id TEXT   Server identifier [required]
+  -t, --tool-name TEXT   Tool name, repeatable for multiple tools [required]
+  --refresh              Bypass cache
+Example: venn tools describe -s personal-gmail -t send_email -t create_draft
+
+### venn tools execute -s <server_id> -t <tool_name>
+Execute a tool on a connected server.
+  -s, --server-id TEXT   Server identifier [required]
+  -t, --tool-name TEXT   Tool name [required]
+  -a, --args TEXT        Tool arguments as a JSON string
+  --confirm              Auto-obtain confirmation token for write operations
+Example (read):    venn tools execute -s personal-gmail -t list_emails -a '{"maxResults": 5}'
+Example (write):   venn tools execute -s personal-gmail -t send_email --confirm -a '{"sender":"me","to":"bob@example.com","subject":"hi","body":"hello"}'
+
+### venn tools confirm
+Get a standalone confirmation token for write operations.
+Returns a single-use token and its expiry. Pass it to execute via --confirm
+or manually via the API.
+
+### venn workflow run
+Execute Python code in a sandboxed environment. Two async functions are
+injected automatically (no imports needed):
+
+  async_call_tool(server_id, tool_name, **kwargs) -> dict
+  async_call_skill(skill_name, **kwargs) -> dict
+
+Both must be awaited. Return results with `return`.
+
+Options:
+  -c, --code TEXT        Inline Python code
+  -f, --file PATH        Read code from a file
+  --timeout INT          Max execution seconds (1-360, default: 180)
+  --confirm              Obtain confirmation for write operations
+
+Sandbox builtins: len, sum, max, min, filter, map, sorted, range,
+  enumerate, zip, dict, set, list, isinstance, type, asyncio
+Not available: network (requests/httpx/urllib), filesystem (open),
+  subprocess, os, sys. Use async_call_tool for all external access.
+Do NOT use asyncio.run() or loop.run_until_complete() — use await and
+  asyncio.gather() only.
+
+Examples:
+
+  Single tool call:
+    venn workflow run -c "
+    result = await async_call_tool('personal-gmail', 'list_emails', userId='me', maxResults=5)
+    return result
+    "
+
+  Chain tool calls:
+    venn workflow run -c "
+    emails = await async_call_tool('personal-gmail', 'list_emails', userId='me', maxResults=1)
+    msg_id = emails['messages'][0]['id']
+    detail = await async_call_tool('personal-gmail', 'find_email', userId='me', id=msg_id)
+    return {'subject': detail.get('subject'), 'snippet': detail.get('snippet')}
+    "
+
+  Parallel execution:
+    venn workflow run -c "
+    import asyncio
+    results = await asyncio.gather(
+        async_call_tool('personal-gmail', 'list_emails', userId='me', maxResults=3),
+        async_call_tool('work-gmail', 'list_emails', userId='me', maxResults=3),
+    )
+    return {'personal': len(results[0].get('messages',[])), 'work': len(results[1].get('messages',[]))}
+    "
+
+  Write operation (requires --confirm):
+    venn workflow run --confirm -c "
+    result = await async_call_tool('personal-gmail', 'send_email', sender='me', to='bob@example.com', subject='hi', body='hello')
+    return result
+    "
+
+### venn help [action]
+Get help info, server status, and auth URLs.
+Actions: getting_started, connector_help, auth_helper, list_servers
+  -s, --server-id TEXT   Required for auth_helper
+  --refresh              Bypass cache
+Example: venn help list_servers
+
+### venn skills upsert -f <file.yaml>
+Create or update an executable skill from a YAML file.
+  -f, --file PATH        Skill YAML file [required]
+
+### venn history toolset <key>
+Show revision history for a 1st-party toolset.
+  -n, --limit INT        Max revisions (default: 50)
+  --before INT           Only show versions before this number
+
+### venn history server <directory_id>
+Show revision history for a server instance.
+  -n, --limit INT        Max revisions (default: 50)
+  --before INT           Only show versions before this number
+
+## Output modes
+
+Default output is YAML — structured, minimal tokens, ideal for agents.
+  --json    Raw JSON (full API response)
+  --table   Rich formatted tables (for human terminal use)
+
+## Write safety
+
+Tools with write operations require confirmation. The --confirm flag on
+`venn tools execute` and `venn workflow run` handles this automatically:
+it fetches a single-use token and includes it in the request. Without
+--confirm, write operations will be rejected by the server.\
+"""
+
+
+@main.command("docs")
+def docs_cmd():
+    """Print the full CLI reference for agent consumption."""
+    click.echo(DOCS)
+
+
+# ---------------------------------------------------------------------------
+# venn tools
+# ---------------------------------------------------------------------------
+
+@main.group()
+def tools():
+    """Discover, inspect, and execute tools."""
+
+
+@tools.command("list")
+@click.option("--slug", "-s", help="Toolset slug (e.g. 'salesforce', 'gmail')")
+@click.option("--directory-id", "-d", help="Server directory UUID")
+@click.option("--instance-id", "-i", help="Server instance UUID")
+@click.pass_context
+def tools_list(ctx, slug, directory_id, instance_id):
+    """List tools for a server."""
+    if not any([slug, directory_id, instance_id]):
+        click.echo("Provide at least one of: --slug, --directory-id, --instance-id", err=True)
+        raise SystemExit(1)
+    data = _client(ctx).list_tools(slug=slug, directory_id=directory_id, instance_id=instance_id)
+    result = data.get("result", {})
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_tool_list(result),
+         table_fn=lambda: output.table_tool_list(result),
+         data=data)
+
+
+@tools.command("search")
+@click.argument("query")
+@click.option("--limit", "-n", default=10, type=int, help="Max results")
+@click.option("--offset", default=0, type=int, help="Skip N results")
+@click.option("--min-score", default=0.3, type=float, help="Minimum similarity score")
+@click.option("--refresh", is_flag=True, help="Bypass cache")
+@click.pass_context
+def tools_search(ctx, query, limit, offset, min_score, refresh):
+    """Search tools by natural language query."""
+    data = _client(ctx).search_tools(query, limit=limit, offset=offset, min_score=min_score, refresh=refresh)
+    result = data.get("result", {})
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_search_results(result),
+         table_fn=lambda: output.table_search_results(result),
+         data=data)
+
+
+@tools.command("describe")
+@click.option("--server-id", "-s", required=True, help="Server identifier")
+@click.option("--tool-name", "-t", required=True, multiple=True, help="Tool name (repeatable)")
+@click.option("--refresh", is_flag=True, help="Bypass cache")
+@click.pass_context
+def tools_describe(ctx, server_id, tool_name, refresh):
+    """Get detailed schema for one or more tools."""
+    tool_ids = [{"server_id": server_id, "tool_name": t} for t in tool_name]
+    data = _client(ctx).describe_tools(tool_ids, refresh=refresh)
+    results = data.get("result", {}).get("results", [])
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_tool_details(results),
+         table_fn=lambda: output.table_tool_details(results),
+         data=data)
+
+
+@tools.command("execute")
+@click.option("--server-id", "-s", required=True, help="Server identifier")
+@click.option("--tool-name", "-t", required=True, help="Tool name")
+@click.option("--args", "-a", "tool_args", default=None, help="Tool arguments as JSON string")
+@click.option("--confirm", "do_confirm", is_flag=True, help="Auto-obtain confirmation token for write ops")
+@click.pass_context
+def tools_execute(ctx, server_id, tool_name, tool_args, do_confirm):
+    """Execute a tool."""
+    client = _client(ctx)
+    parsed_args = json.loads(tool_args) if tool_args else None
+
+    confirmation_token = None
+    if do_confirm:
+        confirm_data = client.confirm_write()
+        confirmation_token = confirm_data.get("result", {}).get("confirmation_token")
+
+    data = client.execute_tool(
+        server_id=server_id,
+        tool_name=tool_name,
+        tool_args=parsed_args,
+        confirmed=do_confirm,
+        confirmation_token=confirmation_token,
+    )
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_execute_result(data),
+         table_fn=lambda: output.table_execute_result(data),
+         data=data)
+
+
+@tools.command("confirm")
+@click.pass_context
+def tools_confirm(ctx):
+    """Get a confirmation token for write operations."""
+    data = _client(ctx).confirm_write()
+    result = data.get("result", {})
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_confirm(result),
+         table_fn=lambda: output.table_confirm(result),
+         data=data)
+
+
+# ---------------------------------------------------------------------------
+# venn workflow
+# ---------------------------------------------------------------------------
+
+@main.group()
+def workflow():
+    """Execute code in a sandboxed environment."""
+
+
+@workflow.command("run")
+@click.option("--code", "-c", help="Python code to execute")
+@click.option("--file", "-f", "code_file", type=click.Path(exists=True), help="Read code from file")
+@click.option("--timeout", default=180, type=int, help="Max execution time in seconds")
+@click.option("--confirm", "do_confirm", is_flag=True, help="Obtain confirmation for write ops")
+@click.pass_context
+def workflow_run(ctx, code, code_file, timeout, do_confirm):
+    """Execute Python code in the Venn sandbox.
+
+    Two async functions are injected (no imports needed):
+
+    \b
+      await async_call_tool(server_id, tool_name, **kwargs) -> dict
+      await async_call_skill(skill_name, **kwargs) -> dict
+
+    Return results with `return`. Use asyncio.gather() for parallel calls.
+    Run `venn docs` for full sandbox reference and examples.
+    """
+    if code_file:
+        code = Path(code_file).read_text()
+    if not code:
+        click.echo("Provide --code or --file", err=True)
+        raise SystemExit(1)
+
+    client = _client(ctx)
+    confirmation_token = None
+    if do_confirm:
+        confirm_data = client.confirm_write()
+        confirmation_token = confirm_data.get("result", {}).get("confirmation_token")
+
+    data = client.execute_workflow(
+        code=code,
+        timeout=timeout,
+        confirmed=do_confirm,
+        confirmation_token=confirmation_token,
+    )
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_execute_result(data),
+         table_fn=lambda: output.table_execute_result(data),
+         data=data)
+
+
+# ---------------------------------------------------------------------------
+# venn help
+# ---------------------------------------------------------------------------
+
+@main.command("help")
+@click.argument("action", required=False, type=click.Choice(
+    ["getting_started", "connector_help", "auth_helper", "list_servers"],
+    case_sensitive=False,
+))
+@click.option("--server-id", "-s", help="Server ID (required for auth_helper)")
+@click.option("--refresh", is_flag=True, help="Bypass cache")
+@click.pass_context
+def help_cmd(ctx, action, server_id, refresh):
+    """Get help, server status, or auth URLs."""
+    data = _client(ctx).help(action=action, server_id=server_id, refresh=refresh)
+    result = data.get("result")
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_help_result(result),
+         table_fn=lambda: output.table_help_result(result),
+         data=data)
+
+
+# ---------------------------------------------------------------------------
+# venn skills
+# ---------------------------------------------------------------------------
+
+@main.group()
+def skills():
+    """Manage executable skills."""
+
+
+@skills.command("upsert")
+@click.option("--file", "-f", "skill_file", required=True, type=click.Path(exists=True), help="Skill YAML file")
+@click.pass_context
+def skills_upsert(ctx, skill_file):
+    """Create or update a skill from a YAML file."""
+    content = Path(skill_file).read_text()
+    data = _client(ctx).upsert_skill(content)
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_skill_upsert(data),
+         table_fn=lambda: output.table_skill_upsert(data),
+         data=data)
+
+
+# ---------------------------------------------------------------------------
+# venn history
+# ---------------------------------------------------------------------------
+
+@main.group()
+def history():
+    """View catalog and server revision history."""
+
+
+@history.command("toolset")
+@click.argument("toolset_key")
+@click.option("--limit", "-n", default=50, type=int, help="Max revisions")
+@click.option("--before", "before_version", default=None, type=int, help="Only show versions before this")
+@click.pass_context
+def history_toolset(ctx, toolset_key, limit, before_version):
+    """Show revision history for a toolset."""
+    data = _client(ctx).toolset_history(toolset_key, limit=limit, before_version=before_version)
+    result = data.get("result", {})
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_history(result),
+         table_fn=lambda: output.table_history(result),
+         data=data)
+
+
+@history.command("server")
+@click.argument("directory_id")
+@click.option("--limit", "-n", default=50, type=int, help="Max revisions")
+@click.option("--before", "before_version", default=None, type=int, help="Only show versions before this")
+@click.pass_context
+def history_server(ctx, directory_id, limit, before_version):
+    """Show revision history for a server instance."""
+    data = _client(ctx).server_history(directory_id, limit=limit, before_version=before_version)
+    result = data.get("result", {})
+    _out(ctx,
+         yaml_fn=lambda: output.yaml_history(result),
+         table_fn=lambda: output.table_history(result),
+         data=data)

{venn_cli-0.1.0 → venn_cli-0.2.0}/src/venn_cli/client.py

@@ -14,7 +14,11 @@ class VennClient:
     def __init__(self, api_key: str, base_url: str = BASE_URL, timeout: float = 120):
         self._http = httpx.Client(
             base_url=base_url,
-            headers={"Authorization": f"Bearer {api_key}"},
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": "venn-cli/1.0",
+                "Accept": "*/*",
+            },
             timeout=timeout,
         )