deepsieve-cli 0.1.0__tar.gz

deepsieve_cli-0.1.0/.gitignore

@@ -0,0 +1,116 @@
+# =========================================================================
+# AI Project Template — .gitignore
+# Trim or extend per project, but treat the secrets/build/data sections as
+# load-bearing: removing them is what causes accidental credential commits.
+# =========================================================================
+
+# --- Secrets & local config ---
+.env
+.env.local
+.env.*.local
+.env.development
+.env.staging
+.env.production
+.env.backup.*
+
+# --- AWS credentials ---
+.aws/
+
+# --- Node / Next.js (site) ---
+site/node_modules/
+site/.next/
+site/.next-*/
+site/out/
+site/public/assets/*
+!site/public/assets/.gitkeep
+*.tsbuildinfo
+
+# --- Python (api) ---
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+
+# --- App database / local data ---
+*.db
+*.sqlite
+*.sqlite3
+app-db/data/
+data/
+
+# --- Docker / LocalStack ---
+ops/localstack/volume/
+localstack-volume/
+
+# --- Langfuse local artifacts ---
+ops/langfuse/storage/
+ops/langfuse/turbo-cache/
+
+# --- CloudFormation outputs / task defs ---
+task-def*.json
+new-task-def*.json
+task_def_out.json
+cloudformation-outputs/
+backups/cloudformation-*.yaml
+scripts/aws/*.log
+
+# --- OS / editor noise ---
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*:Zone.Identifier
+
+# --- Cursor / Claude local settings (keep settings.json, drop settings.local.json) ---
+.cursor/*
+.claude/settings.local.json
+.claude/scheduled_tasks.lock
+
+# --- Test outputs ---
+coverage/
+.coverage
+htmlcov/
+junit.xml
+
+# --- Tooling caches ---
+.next/
+.turbo/
+.playwright-mcp/
+
+# --- Manual-testing artifacts (screenshots, diff captures, etc.) ---
+# These accumulate at repo-root during ad-hoc UI testing and shouldn't
+# land in commits. If you need to keep a screenshot, move it under
+# docs/ or supplemental/ with an explicit name.
+/*.png
+/*.jpg
+/*.jpeg
+
+# Playwright snapshot artifacts
+*.playwright-mcp/
+editor-*.md
+builder*.md
+
+# onboarding stress-test scratch harness
+_stress/
+api/_stress/
+
+# Local user-testing artifacts (reports, screenshots, transcripts) — not shipped.
+# Root-anchored: an unanchored `user-testing/` would also swallow the reusable
+# skill at .claude/skills/user-testing/, which IS committed.
+/user-testing/
+
+# Stray Playwright accessibility-snapshot dumps from browser-driven QA.
+ctx*-run.md
+page-*.yml
+user-testing/

deepsieve_cli-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: deepsieve-cli
+Version: 0.1.0
+Summary: DeepSieve CLI — run cited deep research from your terminal
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# deepsieve-cli
+
+Run cited deep research from your terminal.
+
+```bash
+uv tool install deepsieve-cli   # or: pipx install deepsieve-cli
+deepsieve login
+```
+
+`login` opens your browser, you approve a short code, and the CLI stores a
+scoped API key. Nothing to copy, nothing pasted into your shell history. The
+credential appears in **Settings → API keys** on your deployment and can be
+revoked there at any time.
+
+## Commands
+
+```bash
+deepsieve whoami                              # identity, workspace, scopes
+deepsieve runs create --query "..." --dry-run # free simulated run (~15s)
+deepsieve runs create --query "..." --wait    # real run: spends credits
+deepsieve runs list
+deepsieve runs get <id>                       # exit 4 while still running
+deepsieve runs cancel <id>
+deepsieve data catalog                        # entities + columns (never guess)
+deepsieve data get companies --receipts       # rows with per-cell citations
+deepsieve setup mcp                           # MCP registration for this origin
+```
+
+Add `--json` to anything for machine-readable output.
+
+## Profiles: several deployments side by side
+
+```bash
+deepsieve login --profile staging --origin https://staging.deepsieve.ai
+deepsieve --profile staging runs list
+```
+
+Each profile is its own `(origin, credential)` pair, so staging and production
+never overwrite one another. `DEEPSIEVE_PROFILE` sets the default.
+
+## CI and containers
+
+Skip `login` entirely — set `DEEPSIEVE_API_KEY` (and `DEEPSIEVE_BASE_URL` if not
+production). Environment variables take precedence over any stored profile.
+
+```bash
+DEEPSIEVE_API_KEY=ds_live_... deepsieve --json data get companies
+```
+
+## What it deliberately cannot do
+
+No billing, no organization or member management, no API-key management, and it
+cannot edit an active Blueprint. Those are decisions for a human in the app —
+and the restriction is enforced server-side by the credential's scopes, not just
+by the absence of a subcommand.
+
+Starting a real (billable) run asks for confirmation, and refuses outright in a
+non-interactive shell unless you pass `--yes`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | failure |
+| 2 | usage error |
+| 3 | not authenticated |
+| 4 | run still in progress |
+
+Full docs: <https://deepsieve.ai/developers/cli>

deepsieve_cli-0.1.0/README.md

@@ -0,0 +1,70 @@
+# deepsieve-cli
+
+Run cited deep research from your terminal.
+
+```bash
+uv tool install deepsieve-cli   # or: pipx install deepsieve-cli
+deepsieve login
+```
+
+`login` opens your browser, you approve a short code, and the CLI stores a
+scoped API key. Nothing to copy, nothing pasted into your shell history. The
+credential appears in **Settings → API keys** on your deployment and can be
+revoked there at any time.
+
+## Commands
+
+```bash
+deepsieve whoami                              # identity, workspace, scopes
+deepsieve runs create --query "..." --dry-run # free simulated run (~15s)
+deepsieve runs create --query "..." --wait    # real run: spends credits
+deepsieve runs list
+deepsieve runs get <id>                       # exit 4 while still running
+deepsieve runs cancel <id>
+deepsieve data catalog                        # entities + columns (never guess)
+deepsieve data get companies --receipts       # rows with per-cell citations
+deepsieve setup mcp                           # MCP registration for this origin
+```
+
+Add `--json` to anything for machine-readable output.
+
+## Profiles: several deployments side by side
+
+```bash
+deepsieve login --profile staging --origin https://staging.deepsieve.ai
+deepsieve --profile staging runs list
+```
+
+Each profile is its own `(origin, credential)` pair, so staging and production
+never overwrite one another. `DEEPSIEVE_PROFILE` sets the default.
+
+## CI and containers
+
+Skip `login` entirely — set `DEEPSIEVE_API_KEY` (and `DEEPSIEVE_BASE_URL` if not
+production). Environment variables take precedence over any stored profile.
+
+```bash
+DEEPSIEVE_API_KEY=ds_live_... deepsieve --json data get companies
+```
+
+## What it deliberately cannot do
+
+No billing, no organization or member management, no API-key management, and it
+cannot edit an active Blueprint. Those are decisions for a human in the app —
+and the restriction is enforced server-side by the credential's scopes, not just
+by the absence of a subcommand.
+
+Starting a real (billable) run asks for confirmation, and refuses outright in a
+non-interactive shell unless you pass `--yes`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 1 | failure |
+| 2 | usage error |
+| 3 | not authenticated |
+| 4 | run still in progress |
+
+Full docs: <https://deepsieve.ai/developers/cli>

deepsieve_cli-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "deepsieve-cli"
+version = "0.1.0"
+description = "DeepSieve CLI — run cited deep research from your terminal"
+requires-python = ">=3.11"
+readme = "README.md"
+dependencies = ["httpx>=0.27"]
+
+[project.scripts]
+deepsieve = "deepsieve_cli.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deepsieve_cli"]

deepsieve_cli-0.1.0/src/deepsieve_cli/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .main import main
+
+sys.exit(main())

deepsieve_cli-0.1.0/src/deepsieve_cli/client.py

@@ -0,0 +1,149 @@
+"""HTTP client for `/v1`, plus the device-authorization login flow.
+
+Deliberately a thin httpx wrapper rather than a dependency on the generated
+SDK: the CLI needs the unauthenticated device endpoints before any credential
+exists, and keeping the dependency surface at httpx keeps `uvx deepsieve`
+startup fast. The same choice the stdio MCP package made.
+
+Errors are surfaced as the typed `/v1` envelope so the CLI can print the
+message the API actually gave — a 403 must never render as "something failed".
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+USER_AGENT = "deepsieve-cli"
+
+
+class ApiError(Exception):
+    def __init__(self, code: str, message: str, *, request_id: str | None = None) -> None:
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        tail = f" (request id {self.request_id})" if self.request_id else ""
+        return f"{self.message}{tail}"
+
+
+@dataclass
+class DeviceAuthorization:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+class Client:
+    def __init__(self, origin: str, api_key: str | None = None, timeout: float = 60.0) -> None:
+        self.origin = origin.rstrip("/")
+        self.api_key = api_key
+        self._timeout = timeout
+
+    def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        h = {"User-Agent": USER_AGENT, **(extra or {})}
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        raw: bool = False,
+    ) -> Any:
+        url = f"{self.origin}{path}"
+        try:
+            with httpx.Client(timeout=self._timeout, follow_redirects=True) as c:
+                r = c.request(
+                    method, url, params=params, json=json_body, headers=self._headers(headers)
+                )
+        except httpx.RequestError as exc:
+            raise ApiError("network_error", f"Could not reach {self.origin}: {exc}") from exc
+
+        if raw and r.is_success:
+            return r.text
+        try:
+            body = r.json()
+        except ValueError:
+            if r.is_success:
+                return {"raw": r.text}
+            raise ApiError("http_error", f"HTTP {r.status_code} from {path}") from None
+        if not r.is_success:
+            err = (body or {}).get("error") or {}
+            raise ApiError(
+                err.get("code", f"http_{r.status_code}"),
+                err.get("message", f"HTTP {r.status_code} from {path}"),
+                request_id=err.get("request_id"),
+            )
+        return body
+
+    # ── device authorization ────────────────────────────────────────────────
+
+    def start_device_authorization(
+        self, client_name: str, preset: str = "cli"
+    ) -> DeviceAuthorization:
+        # Ask for the CLI preset, not the broad `agent` one. The consent screen
+        # lists what it asks for, and asking a security-attentive developer to
+        # approve "manage webhook endpoints" for a tool that has no webhook
+        # command is how you lose their trust at the first screen.
+        body = self.request(
+            "POST",
+            "/v1/auth/device/code",
+            json_body={"client_name": client_name, "preset": preset},
+        )
+        return DeviceAuthorization(
+            device_code=body["device_code"],
+            user_code=body["user_code"],
+            verification_uri=body["verification_uri"],
+            verification_uri_complete=body.get("verification_uri_complete")
+            or body["verification_uri"],
+            expires_in=int(body.get("expires_in", 600)),
+            interval=int(body.get("interval", 5)),
+        )
+
+    def poll_for_credential(
+        self, auth: DeviceAuthorization, *, on_tick=None, sleep=time.sleep
+    ) -> dict[str, Any]:
+        """Poll until approved, denied, or expired.
+
+        Honours the server's `interval`, and backs off on `slow_down` as
+        RFC 8628 requires — a CLI that ignores that is how a device flow turns
+        into a self-inflicted denial of service.
+        """
+        interval = auth.interval
+        deadline = time.monotonic() + auth.expires_in
+        while time.monotonic() < deadline:
+            sleep(interval)
+            if on_tick:
+                on_tick()
+            try:
+                return self.request(
+                    "POST", "/v1/auth/device/token", json_body={"device_code": auth.device_code}
+                )
+            except ApiError as exc:
+                if exc.code == "authorization_pending":
+                    continue
+                if exc.code == "slow_down":
+                    interval += 5
+                    continue
+                # A shared limiter bucket or a transient blip must not abort a
+                # sign-in the human is in the middle of approving: back off and
+                # keep waiting until the authorization itself expires.
+                if exc.code in ("rate_limited", "network_error") or exc.code.startswith("http_5"):
+                    interval = min(interval + 5, 30)
+                    continue
+                raise
+        raise ApiError("expired_token", "Timed out waiting for approval. Run login again.")

deepsieve_cli-0.1.0/src/deepsieve_cli/config.py

@@ -0,0 +1,116 @@
+"""Profiles and credential storage.
+
+A profile is `(origin, api_key)` under a name. That is what makes it safe to
+work against staging and production side by side: they are separate profiles,
+never a global "current login" a developer has to remember the state of.
+
+Credentials live in a 0600 file under the user's config directory, never in
+shell history and never in the repo. `DEEPSIEVE_API_KEY` in the environment
+always wins, so CI needs no login and no file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_ORIGIN = "https://deepsieve.ai"
+ENV_KEY = "DEEPSIEVE_API_KEY"
+ENV_ORIGIN = "DEEPSIEVE_BASE_URL"
+ENV_PROFILE = "DEEPSIEVE_PROFILE"
+
+
+def config_path() -> Path:
+    """`$XDG_CONFIG_HOME/deepsieve/config.json`, or the OS equivalent."""
+    override = os.environ.get("DEEPSIEVE_CONFIG")
+    if override:
+        return Path(override)
+    base = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(base) if base else Path.home() / ".config"
+    return root / "deepsieve" / "config.json"
+
+
+@dataclass
+class Profile:
+    name: str
+    origin: str
+    api_key: str | None = None
+    key_name: str | None = None
+    scopes: list[str] | None = None
+
+    @property
+    def is_env_credential(self) -> bool:
+        return bool(os.environ.get(ENV_KEY)) and self.api_key == os.environ.get(ENV_KEY)
+
+
+def _read() -> dict:
+    path = config_path()
+    if not path.exists():
+        return {"profiles": {}}
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {"profiles": {}}
+    data.setdefault("profiles", {})
+    return data
+
+
+def _write(data: dict) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # chmod BEFORE the secret is written, so it is never briefly world-readable.
+    tmp = path.with_suffix(".tmp")
+    tmp.touch(mode=0o600, exist_ok=True)
+    os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
+    tmp.write_text(json.dumps(data, indent=2) + "\n")
+    tmp.replace(path)
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+
+
+def profile_name(explicit: str | None = None) -> str:
+    return explicit or os.environ.get(ENV_PROFILE) or "default"
+
+
+def load_profile(name: str | None = None) -> Profile:
+    """Resolve a profile, with environment variables taking precedence.
+
+    Env-first is what makes the same binary work in CI without a login step —
+    and it means a compromised config file cannot silently override an
+    explicitly-provided CI credential.
+    """
+    resolved = profile_name(name)
+    stored = _read()["profiles"].get(resolved, {})
+    return Profile(
+        name=resolved,
+        origin=(os.environ.get(ENV_ORIGIN) or stored.get("origin") or DEFAULT_ORIGIN).rstrip("/"),
+        api_key=os.environ.get(ENV_KEY) or stored.get("api_key"),
+        key_name=stored.get("key_name"),
+        scopes=stored.get("scopes"),
+    )
+
+
+def save_profile(profile: Profile) -> None:
+    data = _read()
+    data["profiles"][profile.name] = {
+        "origin": profile.origin,
+        "api_key": profile.api_key,
+        "key_name": profile.key_name,
+        "scopes": profile.scopes,
+    }
+    _write(data)
+
+
+def forget_profile(name: str) -> bool:
+    data = _read()
+    if name not in data["profiles"]:
+        return False
+    del data["profiles"][name]
+    _write(data)
+    return True
+
+
+def list_profiles() -> dict[str, dict]:
+    return _read()["profiles"]