venn-cli 0.1.0__py3-none-any.whl

venn_cli/cli.py

@@ -0,0 +1,265 @@
+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"]
+
+
+@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("--raw", is_flag=True, help="Output raw JSON instead of formatted tables")
+@click.version_option(package_name="venn-cli")
+@click.pass_context
+def main(ctx: click.Context, api_key: str | None, base_url: str | None, raw: bool) -> None:
+    """Venn ToolIQ CLI — discover, inspect, and execute tools."""
+    _load_env()
+    api_key = api_key or os.environ.get("VENN_API_KEY")
+    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.ensure_object(dict)
+    ctx.obj["client"] = VennClient(**kwargs)
+    ctx.obj["raw"] = raw
+
+
+# ---------------------------------------------------------------------------
+# 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)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_tool_list(data.get("result", {}))
+
+
+@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)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_search_results(data.get("result", {}))
+
+
+@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."""
+    tools_list = [{"server_id": server_id, "tool_name": t} for t in tool_name]
+    data = _client(ctx).describe_tools(tools_list, refresh=refresh)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_tool_details(data.get("result", {}).get("results", []))
+
+
+@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,
+    )
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_execute_result(data)
+
+
+@tools.command("confirm")
+@click.pass_context
+def tools_confirm(ctx):
+    """Get a confirmation token for write operations."""
+    data = _client(ctx).confirm_write()
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_confirm(data.get("result", {}))
+
+
+# ---------------------------------------------------------------------------
+# 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."""
+    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,
+    )
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_execute_result(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)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_help_result(data.get("result"))
+
+
+# ---------------------------------------------------------------------------
+# 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)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.console.print("[green]Skill upserted successfully.[/green]")
+        if data.get("result"):
+            output.print_json(data["result"])
+
+
+# ---------------------------------------------------------------------------
+# 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)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_history(data.get("result", {}))
+
+
+@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)
+    if ctx.obj["raw"]:
+        output.print_json(data)
+    else:
+        output.print_history(data.get("result", {}))

venn_cli/client.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import httpx
+
+
+BASE_URL = "https://app.venn.ai/api/tooliq"
+
+
+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}"},
+            timeout=timeout,
+        )
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        resp = self._http.get(path, params=params)
+        return self._handle(resp)
+
+    def _post(self, path: str, payload: dict | None = None) -> dict:
+        resp = self._http.post(path, json=payload or {})
+        return self._handle(resp)
+
+    @staticmethod
+    def _handle(resp: httpx.Response) -> dict:
+        try:
+            data = resp.json()
+        except Exception:
+            resp.raise_for_status()
+            return {}
+        if not data.get("success", True):
+            err = data.get("error", resp.text)
+            print(f"API error: {err}", file=sys.stderr)
+            raise SystemExit(1)
+        resp.raise_for_status()
+        return data
+
+    # -- tools ---------------------------------------------------------------
+
+    def list_tools(
+        self,
+        slug: str | None = None,
+        directory_id: str | None = None,
+        instance_id: str | None = None,
+    ) -> dict:
+        params: dict[str, Any] = {}
+        if slug:
+            params["slug"] = slug
+        if directory_id:
+            params["directory_id"] = directory_id
+        if instance_id:
+            params["instance_id"] = instance_id
+        return self._get("/tools/list", params)
+
+    def search_tools(
+        self,
+        query: str,
+        limit: int = 10,
+        offset: int = 0,
+        min_score: float = 0.3,
+        refresh: bool = False,
+    ) -> dict:
+        return self._post("/tools/search", {
+            "query": query,
+            "limit": limit,
+            "offset": offset,
+            "min_score": min_score,
+            "refresh": refresh,
+        })
+
+    def describe_tools(
+        self,
+        tools: list[dict[str, str]],
+        refresh: bool = False,
+    ) -> dict:
+        return self._post("/tools/describe", {"tools": tools, "refresh": refresh})
+
+    def execute_tool(
+        self,
+        server_id: str,
+        tool_name: str,
+        tool_args: dict | None = None,
+        confirmed: bool = False,
+        confirmation_token: str | None = None,
+    ) -> dict:
+        payload: dict[str, Any] = {
+            "server_id": server_id,
+            "tool_name": tool_name,
+            "confirmed": confirmed,
+        }
+        if tool_args:
+            payload["tool_args"] = tool_args
+        if confirmation_token:
+            payload["confirmation_token"] = confirmation_token
+        return self._post("/tools/execute", payload)
+
+    def confirm_write(self) -> dict:
+        return self._post("/tools/confirm")
+
+    # -- workflow ------------------------------------------------------------
+
+    def execute_workflow(
+        self,
+        code: str,
+        timeout: int = 180,
+        confirmed: bool = False,
+        confirmation_token: str | None = None,
+    ) -> dict:
+        payload: dict[str, Any] = {
+            "code": code,
+            "timeout": timeout,
+            "confirmed": confirmed,
+        }
+        if confirmation_token:
+            payload["confirmation_token"] = confirmation_token
+        return self._post("/tools/execute-workflow", payload)
+
+    # -- help ----------------------------------------------------------------
+
+    def help(
+        self,
+        action: str | None = None,
+        server_id: str | None = None,
+        refresh: bool = False,
+    ) -> dict:
+        payload: dict[str, Any] = {"refresh": refresh}
+        if action:
+            payload["action"] = action
+        if server_id:
+            payload["server_id"] = server_id
+        return self._post("/tools/help", payload)
+
+    # -- skills --------------------------------------------------------------
+
+    def upsert_skill(self, content: str) -> dict:
+        return self._post("/skills", {"content": content})
+
+    # -- history -------------------------------------------------------------
+
+    def toolset_history(
+        self,
+        toolset_key: str,
+        limit: int = 50,
+        before_version: int | None = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if before_version is not None:
+            params["before_version"] = before_version
+        return self._get(f"/toolset/{toolset_key}/history", params)
+
+    def server_history(
+        self,
+        directory_id: str,
+        limit: int = 50,
+        before_version: int | None = None,
+    ) -> dict:
+        params: dict[str, Any] = {"limit": limit}
+        if before_version is not None:
+            params["before_version"] = before_version
+        return self._get(f"/server/{directory_id}/history", params)

venn_cli/output.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.syntax import Syntax
+from rich.text import Text
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def print_json(data: Any) -> None:
+    console.print(Syntax(json.dumps(data, indent=2), "json"))
+
+
+def print_tool_list(result: dict) -> None:
+    name = result.get("name", "")
+    slug = result.get("slug", "")
+    version = result.get("toolset_version", "")
+    tools = result.get("tools", [])
+
+    header = f"{name}"
+    if slug:
+        header += f" ({slug})"
+    if version:
+        header += f"  v{version}"
+
+    table = Table(title=header, show_lines=False)
+    table.add_column("Tool", style="cyan", no_wrap=True)
+    table.add_column("Description")
+    table.add_column("CRUD", style="dim", width=8)
+    table.add_column("Risk", justify="center", width=5)
+    table.add_column("Status", style="dim", width=10)
+
+    for t in tools:
+        risk = str(t.get("risk_level", ""))
+        risk_style = "green" if int(risk or 0) <= 1 else "yellow" if int(risk or 0) <= 3 else "red"
+        table.add_row(
+            t["tool_name"],
+            t.get("short_description", ""),
+            t.get("crud_operation") or "",
+            Text(risk, style=risk_style),
+            t.get("status", ""),
+        )
+    console.print(table)
+
+
+def print_search_results(result: dict) -> None:
+    candidates = result.get("candidates", [])
+    total = result.get("total", 0)
+
+    if not candidates:
+        console.print("[dim]No results found.[/dim]")
+        return
+
+    table = Table(title=f"Search Results ({total} total)", show_lines=False)
+    table.add_column("#", style="dim", width=4, justify="right")
+    table.add_column("Type", width=6)
+    table.add_column("Server / Name", style="cyan")
+    table.add_column("Tool / Skill")
+    table.add_column("Description")
+
+    for c in candidates:
+        rank = str(c.get("rank", ""))
+        if c.get("type") == "skill":
+            table.add_row(rank, "skill", "", c["name"], c.get("description", ""))
+        else:
+            connected = "[green]●[/green]" if c.get("server_connected") else "[red]○[/red]"
+            table.add_row(
+                rank,
+                f"tool {connected}",
+                c.get("server_name", c.get("server_id", "")),
+                c.get("tool_name", ""),
+                c.get("short_description", ""),
+            )
+    console.print(table)
+
+
+def print_tool_details(results: list[dict]) -> None:
+    for t in results:
+        title = f"{t.get('server_name', '')} / {t['tool_name']}"
+        body_parts = []
+        if t.get("description"):
+            body_parts.append(t["description"])
+        if t.get("extended_description"):
+            body_parts.append(f"\n{t['extended_description']}")
+        if t.get("write_operation"):
+            body_parts.append(f"\n[yellow]Write operation:[/yellow] {t['write_operation']}")
+
+        console.print(Panel("\n".join(body_parts), title=title, border_style="cyan"))
+
+        if t.get("inputSchema"):
+            console.print(Syntax(json.dumps(t["inputSchema"], indent=2), "json", theme="monokai"))
+        console.print()
+
+
+def print_execute_result(data: dict) -> None:
+    result = data.get("result")
+    if isinstance(result, (dict, list)):
+        print_json(result)
+    elif result is not None:
+        console.print(result)
+
+
+def print_confirm(result: dict) -> None:
+    token = result.get("confirmation_token", "")
+    expires = result.get("expires_in_seconds", "")
+    console.print(f"[green]Confirmation token:[/green] {token}")
+    console.print(f"[dim]Expires in {expires}s[/dim]")
+    console.print(f"\n[dim]{result.get('usage', '')}[/dim]")
+
+
+def print_history(result: dict) -> None:
+    key = result.get("toolset_key") or result.get("directory_id", "")
+    revisions = result.get("revisions", [])
+
+    if not revisions:
+        console.print("[dim]No history found.[/dim]")
+        return
+
+    table = Table(title=f"History: {key}", show_lines=False)
+    table.add_column("Version", justify="right", width=8)
+    table.add_column("Date", width=22)
+    table.add_column("Source", style="dim")
+    table.add_column("Summary")
+
+    for r in revisions:
+        summary_parts = [f"{k}: {v}" for k, v in r.get("summary", {}).items()]
+        table.add_row(
+            str(r.get("version", "")),
+            r.get("issued_at", ""),
+            r.get("source") or "",
+            ", ".join(summary_parts),
+        )
+    console.print(table)
+
+
+def print_help_result(result: Any) -> None:
+    if isinstance(result, list):
+        for item in result:
+            if isinstance(item, dict):
+                _print_help_item(item)
+            else:
+                console.print(item)
+    elif isinstance(result, dict):
+        _print_help_item(result)
+    else:
+        console.print(result)
+
+
+def _print_help_item(item: dict) -> None:
+    name = item.get("name") or item.get("server_name") or ""
+    status = item.get("status") or item.get("connected") or ""
+    if name:
+        indicator = "[green]●[/green]" if status in (True, "connected") else "[red]○[/red]"
+        console.print(f"  {indicator} [cyan]{name}[/cyan]", end="")
+        remaining = {k: v for k, v in item.items() if k not in ("name", "server_name", "status", "connected")}
+        if remaining:
+            console.print(f"  [dim]{remaining}[/dim]")
+        else:
+            console.print()
+    else:
+        print_json(item)

venn_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: venn-cli
+Version: 0.1.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
+Project-URL: Issues, https://github.com/moda-labs/venn-cli/issues
+Author-email: Moda Labs <zach@modalabs.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'

venn_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+venn_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+venn_cli/cli.py,sha256=V9sZv9G4qflHGB_zJu_mTYlo0J9ITJGznPAuzjGULgk,9596
+venn_cli/client.py,sha256=O-BlREKh9ZxkXXy3_YYyHbi2k3SSrd5NSCRddIBuNgI,4952
+venn_cli/output.py,sha256=EvTlQZLUxsMuNnd_cjvZJsjkPkX6_CscuUeKiLzkUHM,5516
+venn_cli-0.1.0.dist-info/METADATA,sha256=QpcIyub5ngjjzOqWyb2xwjyTatmVeAm0nvK2svMOIT0,1028
+venn_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+venn_cli-0.1.0.dist-info/entry_points.txt,sha256=r47AOFwFdnb-ptJsHkvb8SQrvUUDmc2hx_LogYtVh8U,43
+venn_cli-0.1.0.dist-info/licenses/LICENSE,sha256=R1js932ljyYmujRLNCDR8NaPdroPHUXZYBrXAqQ179Y,1066
+venn_cli-0.1.0.dist-info/RECORD,,

venn_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

venn_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+venn = venn_cli.cli:main

venn_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moda Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.