constants-cli 0.1.0__tar.gz

constants_cli-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

constants_cli-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: constants-cli
+Version: 0.1.0
+Summary: CLI for running Constants.ai tools from the command line
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# constants-cli
+
+CLI for running [Constants](https://app.constants.ai) tools from the command line.
+
+## Install
+
+```bash
+uv tool install constants-cli
+```
+
+## Quick Start
+
+```bash
+# Authenticate (or set CONSTANTS_API_KEY env var)
+constants auth
+
+# List your tools
+constants list
+
+# Run a tool
+constants run my_tool_abc12345 query="hello world"
+
+# Run with file input (auto-uploaded)
+constants run pdf_tool_abc12345 pdf_file=./report.pdf
+
+# Run with JSON input
+constants run my_tool_abc12345 --input-json '{"query": "hello", "limit": 10}'
+```
+
+## Authentication
+
+Set your API key via environment variable:
+
+```bash
+export CONSTANTS_API_KEY="wk_your_key_here"
+```
+
+Or store it persistently:
+
+```bash
+constants auth
+```
+
+Get your API key at [app.constants.ai/settings](https://app.constants.ai/settings).

constants_cli-0.1.0/README.md

@@ -0,0 +1,44 @@
+# constants-cli
+
+CLI for running [Constants](https://app.constants.ai) tools from the command line.
+
+## Install
+
+```bash
+uv tool install constants-cli
+```
+
+## Quick Start
+
+```bash
+# Authenticate (or set CONSTANTS_API_KEY env var)
+constants auth
+
+# List your tools
+constants list
+
+# Run a tool
+constants run my_tool_abc12345 query="hello world"
+
+# Run with file input (auto-uploaded)
+constants run pdf_tool_abc12345 pdf_file=./report.pdf
+
+# Run with JSON input
+constants run my_tool_abc12345 --input-json '{"query": "hello", "limit": 10}'
+```
+
+## Authentication
+
+Set your API key via environment variable:
+
+```bash
+export CONSTANTS_API_KEY="wk_your_key_here"
+```
+
+Or store it persistently:
+
+```bash
+constants auth
+```
+
+Get your API key at [app.constants.ai/settings](https://app.constants.ai/settings).

constants_cli-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "constants-cli"
+version = "0.1.0"
+description = "CLI for running Constants.ai tools from the command line"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+    "click>=8.0",
+    "requests>=2.28",
+]
+
+[project.scripts]
+constants = "constants_cli.main:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/constants_cli"]

constants_cli-0.1.0/src/constants_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Constants CLI - Run Constants.ai tools from the command line."""
+
+__version__ = "0.1.0"

constants_cli-0.1.0/src/constants_cli/auth.py

@@ -0,0 +1,44 @@
+"""API key resolution: env var -> config file -> error."""
+
+import json
+import os
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".constants"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+ENV_VAR = "CONSTANTS_API_KEY"
+
+
+def get_api_key() -> str | None:
+    """Resolve API key from env var or config file."""
+    key = os.environ.get(ENV_VAR)
+    if key:
+        return key
+
+    if CONFIG_FILE.exists():
+        try:
+            data = json.loads(CONFIG_FILE.read_text())
+            return data.get("api_key")
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    return None
+
+
+def save_api_key(key: str) -> None:
+    """Persist API key to config file."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps({"api_key": key}, indent=2) + "\n")
+    CONFIG_FILE.chmod(0o600)
+
+
+def require_api_key() -> str:
+    """Get API key or raise with instructions."""
+    key = get_api_key()
+    if not key:
+        raise SystemExit(
+            "No API key found.\n"
+            f"Set {ENV_VAR} or run: constants auth\n"
+            "Get your key at https://app.constants.ai/settings"
+        )
+    return key

constants_cli-0.1.0/src/constants_cli/client.py

@@ -0,0 +1,151 @@
+"""HTTP client for the Constants v1 REST API."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from constants_cli.auth import require_api_key
+from constants_cli.exceptions import AuthError, NotFoundError, ExecutionError
+
+DEFAULT_BASE_URL = "https://app.constants.ai"
+ENV_BASE_URL = "CONSTANTS_API_URL"
+
+
+class ConstantsClient:
+    """Thin HTTP wrapper around /api/v1/* endpoints."""
+
+    def __init__(self, api_key: str | None = None, base_url: str | None = None):
+        self.api_key = api_key or require_api_key()
+        self.base_url = (base_url or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL).rstrip("/")
+        self._tools_cache: list[dict[str, Any]] | None = None
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _handle_error(self, resp: requests.Response) -> None:
+        if resp.status_code == 200 or resp.status_code == 201:
+            return
+
+        try:
+            body = resp.json()
+            message = body.get("message") or body.get("error") or resp.text
+        except Exception:
+            message = resp.text or f"HTTP {resp.status_code}"
+
+        if resp.status_code in (401, 403):
+            raise AuthError(message, resp.status_code)
+        if resp.status_code == 404:
+            raise NotFoundError(message, resp.status_code)
+        raise ExecutionError(message, resp.status_code)
+
+    # ── Tool listing ─────────────────────────────────────────────
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        """Fetch all available tools. Returns the raw tools array."""
+        resp = requests.get(f"{self.base_url}/api/v1/tools", headers=self._headers())
+        self._handle_error(resp)
+        tools = resp.json().get("tools", [])
+        self._tools_cache = tools
+        return tools
+
+    def get_tool(self, name: str) -> dict[str, Any] | None:
+        """Look up a single tool by name (uses cache if available)."""
+        tools = self._tools_cache if self._tools_cache is not None else self.list_tools()
+        for t in tools:
+            if t["name"] == name:
+                return t
+        return None
+
+    # ── Tool execution ───────────────────────────────────────────
+
+    def run_tool(self, name: str, args: dict[str, Any]) -> dict[str, Any]:
+        """Execute a tool and return the full response."""
+        resp = requests.post(
+            f"{self.base_url}/api/v1/run/{name}",
+            headers=self._headers(),
+            json=args,
+        )
+        self._handle_error(resp)
+        return resp.json()
+
+    # ── File upload ──────────────────────────────────────────────
+
+    def upload_file(self, tool_name: str, field_name: str, file_path: str | Path) -> str:
+        """Upload a local file for a tool field. Returns the upload ID."""
+        path = Path(file_path)
+        if not path.is_file():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        resp = requests.post(
+            f"{self.base_url}/api/v1/upload",
+            headers=self._headers(),
+            json={
+                "toolName": tool_name,
+                "fieldName": field_name,
+                "filename": path.name,
+            },
+        )
+        self._handle_error(resp)
+        data = resp.json()
+
+        signed_url = data["signedUrl"]
+        mime_type = data.get("mimeType", "application/octet-stream")
+
+        put_resp = requests.put(
+            signed_url,
+            headers={"Content-Type": mime_type},
+            data=path.read_bytes(),
+        )
+        if put_resp.status_code not in (200, 201):
+            raise ExecutionError(f"File upload PUT failed: HTTP {put_resp.status_code}")
+
+        return data["uploadId"]
+
+    def upload_directory(self, tool_name: str, field_name: str, dir_path: str | Path) -> str:
+        """Zip a directory and upload it. Returns the upload ID."""
+        import tempfile
+        import zipfile
+
+        path = Path(dir_path)
+        if not path.is_dir():
+            raise NotADirectoryError(f"Not a directory: {path}")
+
+        with tempfile.NamedTemporaryFile(suffix=".zip", delete=False) as tmp:
+            tmp_path = Path(tmp.name)
+
+        try:
+            with zipfile.ZipFile(tmp_path, "w", zipfile.ZIP_DEFLATED) as zf:
+                for file in path.rglob("*"):
+                    if file.is_file():
+                        zf.write(file, file.relative_to(path))
+
+            resp = requests.post(
+                f"{self.base_url}/api/v1/upload",
+                headers=self._headers(),
+                json={
+                    "toolName": tool_name,
+                    "fieldName": field_name,
+                    "filename": f"{path.name}.zip",
+                },
+            )
+            self._handle_error(resp)
+            data = resp.json()
+
+            put_resp = requests.put(
+                data["signedUrl"],
+                headers={"Content-Type": "application/zip"},
+                data=tmp_path.read_bytes(),
+            )
+            if put_resp.status_code not in (200, 201):
+                raise ExecutionError(f"Directory upload PUT failed: HTTP {put_resp.status_code}")
+
+            return data["uploadId"]
+        finally:
+            tmp_path.unlink(missing_ok=True)

constants_cli-0.1.0/src/constants_cli/commands/__init__.py

@@ -0,0 +1,5 @@
+"""CLI commands."""
+
+from constants_cli.commands.auth import auth  # noqa: F401
+from constants_cli.commands.list_tools import list_tools  # noqa: F401
+from constants_cli.commands.run import run  # noqa: F401

constants_cli-0.1.0/src/constants_cli/commands/auth.py

@@ -0,0 +1,29 @@
+"""constants auth - store API key."""
+
+import click
+
+from constants_cli.main import cli
+from constants_cli.auth import save_api_key
+from constants_cli.client import ConstantsClient
+from constants_cli.output import print_error
+
+
+@cli.command("auth")
+def auth():
+    """Store your Constants API key."""
+    key = click.prompt("Enter your API key", hide_input=True)
+
+    if not key.startswith("wk_"):
+        print_error("Invalid key format. Keys start with 'wk_'.")
+        raise SystemExit(1)
+
+    try:
+        client = ConstantsClient(api_key=key)
+        tools = client.list_tools()
+        click.echo(f"Authenticated. {len(tools)} tool(s) available.")
+    except Exception as e:
+        print_error(f"Key validation failed: {e}")
+        raise SystemExit(1)
+
+    save_api_key(key)
+    click.echo("API key saved to ~/.constants/config.json")

constants_cli-0.1.0/src/constants_cli/commands/list_tools.py

@@ -0,0 +1,29 @@
+"""constants list - list available tools."""
+
+import click
+
+from constants_cli.main import cli
+from constants_cli.client import ConstantsClient
+from constants_cli.auth import require_api_key
+from constants_cli.output import print_json, print_table, print_error
+
+
+@cli.command("list")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def list_tools(as_json: bool):
+    """List available tools."""
+    api_key = require_api_key()
+    client = ConstantsClient(api_key=api_key)
+
+    try:
+        tools = client.list_tools()
+    except Exception as e:
+        print_error(str(e))
+        raise SystemExit(1)
+
+    if as_json:
+        print_json(tools)
+        return
+
+    rows = [{"name": t["name"], "description": (t.get("description") or "")[:80]} for t in tools]
+    print_table(rows, [("name", "Name"), ("description", "Description")])

constants_cli-0.1.0/src/constants_cli/commands/run.py

@@ -0,0 +1,183 @@
+"""constants run - execute a tool with key=value args and automatic file upload."""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+
+from constants_cli.main import cli
+from constants_cli.auth import require_api_key
+from constants_cli.client import ConstantsClient
+from constants_cli.exceptions import ValidationError
+from constants_cli.output import print_json, print_error
+
+
+def _coerce_value(raw: str, schema_type: str | None) -> Any:
+    """Coerce a string value using the tool schema type."""
+    if schema_type == "boolean":
+        return raw.lower() in ("true", "1", "yes")
+    if schema_type in ("number", "integer"):
+        try:
+            return int(raw) if schema_type == "integer" else float(raw)
+        except ValueError:
+            return raw
+    return raw
+
+
+def _parse_key_value_args(
+    pairs: tuple[str, ...],
+    input_schema: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Parse key=value pairs, coercing types via the tool's input schema."""
+    type_map: dict[str, str] = {}
+    if input_schema:
+        for prop in input_schema.get("properties", {}):
+            if isinstance(prop, str):
+                info = input_schema["properties"][prop]
+                type_map[prop] = info.get("type", "string")
+            elif isinstance(prop, dict):
+                pass
+
+        if isinstance(input_schema.get("properties"), dict):
+            for name, info in input_schema["properties"].items():
+                type_map[name] = info.get("type", "string")
+
+    result: dict[str, Any] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            print_error(f"Invalid argument '{pair}'. Use key=value format.")
+            raise SystemExit(1)
+        key, value = pair.split("=", 1)
+        result[key] = _coerce_value(value, type_map.get(key))
+    return result
+
+
+def _validate_file_accept(file_path: Path, accept: list[str] | None) -> None:
+    """Validate a file's extension against accept patterns."""
+    if not accept:
+        return
+    name = file_path.name.lower()
+    ext = file_path.suffix.lower()
+    for pattern in accept:
+        if pattern.startswith(".") and ext == pattern.lower():
+            return
+        if "/" in pattern and fnmatch.fnmatch(f"x/{name}", f"x/{pattern.split('/')[1]}"):
+            return
+        if pattern == "*/*" or pattern == "*":
+            return
+    raise ValidationError(
+        f"File '{file_path.name}' does not match accepted types: {', '.join(accept)}"
+    )
+
+
+def _handle_file_uploads(
+    client: ConstantsClient,
+    tool_name: str,
+    args: dict[str, Any],
+    file_fields: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Detect local file paths in args, upload them, and substitute references."""
+    file_field_map = {f["name"]: f for f in file_fields}
+    result = dict(args)
+
+    for field_name, field_info in file_field_map.items():
+        value = result.get(field_name)
+        if value is None:
+            continue
+
+        field_type = field_info.get("type", "file")
+        accept = field_info.get("accept")
+        multiple = field_info.get("multiple", False)
+
+        if field_type == "directory":
+            dir_path = Path(str(value))
+            if dir_path.is_dir():
+                click.echo(f"Uploading directory {dir_path}...", err=True)
+                upload_id = client.upload_directory(tool_name, field_name, dir_path)
+                result[field_name] = upload_id
+            continue
+
+        if multiple:
+            paths = [Path(p.strip()) for p in str(value).split(",")]
+            upload_ids = []
+            for p in paths:
+                if p.is_file():
+                    _validate_file_accept(p, accept)
+                    click.echo(f"Uploading {p}...", err=True)
+                    upload_ids.append(client.upload_file(tool_name, field_name, p))
+                else:
+                    upload_ids.append(str(p))
+            result[field_name] = upload_ids
+        else:
+            file_path = Path(str(value))
+            if file_path.is_file():
+                _validate_file_accept(file_path, accept)
+                click.echo(f"Uploading {file_path}...", err=True)
+                upload_id = client.upload_file(tool_name, field_name, file_path)
+                result[field_name] = upload_id
+
+    return result
+
+
+@cli.command("run")
+@click.argument("tool_name")
+@click.argument("key_value_args", nargs=-1)
+@click.option("--input-json", "input_json", default=None, help="JSON string with tool arguments")
+@click.option("--raw", is_flag=True, help="Print only the output field")
+def run(tool_name: str, key_value_args: tuple[str, ...], input_json: str | None, raw: bool):
+    """Run a tool.
+
+    Pass arguments as key=value pairs or via --input-json.
+
+    \b
+    Examples:
+      constants run my_tool query="hello world"
+      constants run my_tool --input-json '{"query": "hello"}'
+      constants run pdf_tool pdf_file=./report.pdf
+    """
+    api_key = require_api_key()
+    client = ConstantsClient(api_key=api_key)
+
+    # Build args from key=value pairs
+    tool = client.get_tool(tool_name)
+    input_schema = tool.get("inputSchema") if tool else None
+    args = _parse_key_value_args(key_value_args, input_schema)
+
+    # Merge --input-json (takes precedence)
+    if input_json:
+        try:
+            json_args = json.loads(input_json)
+        except json.JSONDecodeError as e:
+            print_error(f"Invalid --input-json: {e}")
+            raise SystemExit(1)
+        args.update(json_args)
+
+    # Handle file uploads if tool has file fields
+    file_fields = tool.get("fileFields", []) if tool else []
+    if file_fields:
+        try:
+            args = _handle_file_uploads(client, tool_name, args, file_fields)
+        except ValidationError as e:
+            print_error(str(e))
+            raise SystemExit(1)
+
+    try:
+        result = client.run_tool(tool_name, args)
+    except Exception as e:
+        print_error(str(e))
+        raise SystemExit(1)
+
+    if raw:
+        output = result.get("output", result)
+        if isinstance(output, str):
+            print(output)
+        else:
+            print_json(output)
+    else:
+        print_json(result)

constants_cli-0.1.0/src/constants_cli/exceptions.py

@@ -0,0 +1,29 @@
+"""Typed exceptions for the Constants client."""
+
+
+class ConstantsError(Exception):
+    """Base exception for Constants API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(ConstantsError):
+    """Authentication or authorization failure (401/403)."""
+    pass
+
+
+class NotFoundError(ConstantsError):
+    """Tool or resource not found (404)."""
+    pass
+
+
+class ExecutionError(ConstantsError):
+    """Tool execution failed (500 or error in output)."""
+    pass
+
+
+class ValidationError(ConstantsError):
+    """Input validation failure (e.g., file type mismatch)."""
+    pass

constants_cli-0.1.0/src/constants_cli/main.py

@@ -0,0 +1,16 @@
+"""CLI entry point."""
+
+import click
+
+from constants_cli import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="constants")
+def cli():
+    """Constants CLI - Run Constants.ai tools from the command line."""
+    pass
+
+
+# Commands are registered via imports below
+from constants_cli.commands import auth, list_tools, run  # noqa: E402, F401

constants_cli-0.1.0/src/constants_cli/output.py

@@ -0,0 +1,37 @@
+"""Result formatting for CLI output."""
+
+import json
+import sys
+
+
+def print_json(data: object) -> None:
+    """Print data as formatted JSON to stdout."""
+    print(json.dumps(data, indent=2, default=str))
+
+
+def print_error(message: str) -> None:
+    """Print error message to stderr."""
+    print(f"Error: {message}", file=sys.stderr)
+
+
+def print_table(rows: list[dict], columns: list[tuple[str, str]]) -> None:
+    """Print a simple text table.
+
+    columns: list of (key, header) tuples.
+    """
+    if not rows:
+        print("(no results)")
+        return
+
+    widths = {key: len(header) for key, header in columns}
+    for row in rows:
+        for key, _ in columns:
+            val = str(row.get(key, ""))
+            widths[key] = max(widths[key], len(val))
+
+    header_line = "  ".join(h.ljust(widths[k]) for k, h in columns)
+    print(header_line)
+    print("  ".join("-" * widths[k] for k, _ in columns))
+    for row in rows:
+        line = "  ".join(str(row.get(k, "")).ljust(widths[k]) for k, _ in columns)
+        print(line)