powder-cli 0.1.0__tar.gz

powder_cli-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: powder-cli
+Version: 0.1.0
+Summary: CLI for the Powder financial document processing API
+Author-email: Powder <engineering@powderfi.com>
+License: Proprietary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+
+# powder-cli
+
+Python CLI for the Powder API — upload financial statements and extract structured data.
+
+## Installation
+
+```bash
+pip install powder-cli
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+### 1. Set Your API Token
+
+```bash
+export POWDER_API_TOKEN="your-token-here"
+```
+
+Add to `~/.zshrc` or `~/.bashrc` to persist. To get a token, contact support@powderfi.com.
+
+Alternatively, use `powder configure` for interactive setup (saves to `~/.config/powder/config.json`).
+
+### 2. Upload a Statement
+
+```bash
+powder upload statement.pdf
+```
+
+This returns an upload ID that you'll use to check status and retrieve data.
+
+### 3. Check Status
+
+```bash
+powder status 12345
+```
+
+Or watch until processing completes:
+
+```bash
+powder status 12345 --watch
+```
+
+### 4. Retrieve Data
+
+```bash
+powder data 12345
+```
+
+View data as a table:
+
+```bash
+powder data 12345 --format table
+```
+
+## Supported File Types
+
+| Format | Extensions |
+|--------|-----------|
+| PDF | `.pdf` |
+| Images | `.png`, `.jpg`, `.jpeg` |
+| Spreadsheets | `.xlsx` |
+
+Maximum file size: **50 MB**
+
+## JSON Output
+
+All CLI commands support `--json` for machine-readable output. The flag goes **before** the command:
+
+```bash
+powder --json upload statement.pdf
+powder --json status 12345
+powder --json data 12345
+```
+
+## Authentication
+
+The CLI checks for credentials in this order:
+
+1. `POWDER_API_TOKEN` environment variable
+2. `~/.config/powder/config.json` (created by `powder configure`)
+
+To get an API token, contact support@powderfi.com.
+
+## Claude Code Plugin
+
+A Claude Code plugin is available at [Powder-Finance/claude-code-powder-plugin](https://github.com/Powder-Finance/claude-code-powder-plugin) for conversational document uploads:
+
+```
+/Powder:setup     # Install CLI + verify token
+/Powder:upload    # Upload → process → extract → summarize
+/Powder:data      # Fetch data for an existing upload
+/Powder:status    # Check processing status
+```

powder_cli-0.1.0/README.md

@@ -0,0 +1,95 @@
+# powder-cli
+
+Python CLI for the Powder API — upload financial statements and extract structured data.
+
+## Installation
+
+```bash
+pip install powder-cli
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+### 1. Set Your API Token
+
+```bash
+export POWDER_API_TOKEN="your-token-here"
+```
+
+Add to `~/.zshrc` or `~/.bashrc` to persist. To get a token, contact support@powderfi.com.
+
+Alternatively, use `powder configure` for interactive setup (saves to `~/.config/powder/config.json`).
+
+### 2. Upload a Statement
+
+```bash
+powder upload statement.pdf
+```
+
+This returns an upload ID that you'll use to check status and retrieve data.
+
+### 3. Check Status
+
+```bash
+powder status 12345
+```
+
+Or watch until processing completes:
+
+```bash
+powder status 12345 --watch
+```
+
+### 4. Retrieve Data
+
+```bash
+powder data 12345
+```
+
+View data as a table:
+
+```bash
+powder data 12345 --format table
+```
+
+## Supported File Types
+
+| Format | Extensions |
+|--------|-----------|
+| PDF | `.pdf` |
+| Images | `.png`, `.jpg`, `.jpeg` |
+| Spreadsheets | `.xlsx` |
+
+Maximum file size: **50 MB**
+
+## JSON Output
+
+All CLI commands support `--json` for machine-readable output. The flag goes **before** the command:
+
+```bash
+powder --json upload statement.pdf
+powder --json status 12345
+powder --json data 12345
+```
+
+## Authentication
+
+The CLI checks for credentials in this order:
+
+1. `POWDER_API_TOKEN` environment variable
+2. `~/.config/powder/config.json` (created by `powder configure`)
+
+To get an API token, contact support@powderfi.com.
+
+## Claude Code Plugin
+
+A Claude Code plugin is available at [Powder-Finance/claude-code-powder-plugin](https://github.com/Powder-Finance/claude-code-powder-plugin) for conversational document uploads:
+
+```
+/Powder:setup     # Install CLI + verify token
+/Powder:upload    # Upload → process → extract → summarize
+/Powder:data      # Fetch data for an existing upload
+/Powder:status    # Check processing status
+```

powder_cli-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "powder-cli"
+dynamic = ["version"]
+description = "CLI for the Powder financial document processing API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Proprietary"}
+authors = [{name = "Powder", email = "engineering@powderfi.com"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "click>=8.0",
+    "requests>=2.28",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "responses>=0.23",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+powder = "powder.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "powder.__version__"}
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "I",     # isort
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "SIM",   # flake8-simplify
+    "RUF",   # ruff-specific rules
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["powder"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=powder --cov-report=term-missing --cov-fail-under=85"

powder_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

powder_cli-0.1.0/src/powder/__init__.py

@@ -0,0 +1,5 @@
+from powder.client import PowderClient
+from powder.errors import PowderAPIError, PowderAuthError, PowderTimeoutError
+
+__version__ = "0.1.0"
+__all__ = ["PowderAPIError", "PowderAuthError", "PowderClient", "PowderTimeoutError"]

powder_cli-0.1.0/src/powder/cli.py

@@ -0,0 +1,213 @@
+import json as json_lib
+from functools import wraps
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from powder import __version__
+from powder.client import PowderClient
+from powder.config import clear_token, save_token
+from powder.errors import PowderAPIError, PowderAuthError, PowderTimeoutError
+
+
+def handle_errors(f):
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        ctx = click.get_current_context()
+        json_output = ctx.find_root().params.get("json_output", False)
+        try:
+            return f(*args, **kwargs)
+        except PowderAuthError as e:
+            if json_output:
+                click.echo(json_lib.dumps({"error": str(e), "status_code": e.status_code}))
+            else:
+                click.echo(f"Error: {e}", err=True)
+                if "configure" not in str(e).lower():
+                    click.echo("Run 'powder configure' to set up your API key.", err=True)
+            ctx.exit(1)
+        except PowderTimeoutError as e:
+            if json_output:
+                click.echo(json_lib.dumps({"error": str(e), "upload_id": e.upload_id}))
+            else:
+                click.echo(f"Error: {e}", err=True)
+            ctx.exit(1)
+        except PowderAPIError as e:
+            if json_output:
+                click.echo(json_lib.dumps({"error": str(e), "status_code": e.status_code}))
+            else:
+                click.echo(f"Error: {e}", err=True)
+            ctx.exit(1)
+        except FileNotFoundError as e:
+            if json_output:
+                click.echo(json_lib.dumps({"error": str(e)}))
+            else:
+                click.echo(f"Error: {e}", err=True)
+            ctx.exit(1)
+        except (ValueError, PermissionError) as e:
+            if json_output:
+                click.echo(json_lib.dumps({"error": str(e)}))
+            else:
+                click.echo(f"Error: {e}", err=True)
+            ctx.exit(1)
+        except KeyboardInterrupt:
+            click.echo("\nAborted.", err=True)
+            ctx.exit(130)
+        except Exception as e:
+            if json_output:
+                click.echo(json_lib.dumps({"error": f"Unexpected error: {e}"}))
+            else:
+                click.echo(f"Unexpected error: {e}", err=True)
+            ctx.exit(1)
+
+    return wrapper
+
+
+@click.group(invoke_without_command=True)
+@click.option("--json", "json_output", is_flag=True, help="Output JSON for all commands")
+@click.option("--version", is_flag=True, help="Show version and exit")
+@click.pass_context
+def cli(ctx, json_output, version):
+    ctx.ensure_object(dict)
+    ctx.obj["json_output"] = json_output
+    if version:
+        click.echo(f"powder {__version__}")
+        ctx.exit(0)
+
+
+@cli.command(short_help="Set up API credentials")
+@click.option("--clear", is_flag=True, help="Remove stored credentials")
+@click.pass_context
+@handle_errors
+def configure(ctx, clear):
+    if clear:
+        clear_token()
+        click.echo("✓ Credentials removed.")
+        return
+
+    token = click.prompt("Enter your Powder API key", hide_input=True)
+
+    # Validate before saving — don't persist invalid tokens
+    client = PowderClient(token=token)
+    try:
+        client._request("GET", "file_uploads/")
+    except PowderAuthError:
+        click.echo("✗ API key rejected by Powder API", err=True)
+        ctx.exit(1)
+    except PowderAPIError:
+        pass  # Non-auth error means auth itself succeeded
+
+    save_token(token)
+    click.echo("✓ API key saved to ~/.config/powder/config.json")
+
+
+@cli.command(short_help="Upload a financial statement")
+@click.argument("path")
+@click.option(
+    "--type",
+    "statement_type",
+    default="brokerage",
+    help="Statement type (default: brokerage)",
+)
+@click.option("--portfolio", "portfolio_id", type=int, default=None, help="Portfolio ID")
+@click.pass_context
+@handle_errors
+def upload(ctx, path, statement_type, portfolio_id):
+    p = Path(path)
+
+    client = PowderClient()
+    result = client.upload(path, statement_type, portfolio_id)
+
+    if ctx.obj.get("json_output"):
+        click.echo(json_lib.dumps(result, indent=2))
+    else:
+        click.echo(f"✓ Uploaded {p.name}")
+        click.echo(f"  ID:          {result.get('id', 'N/A')}")
+        click.echo(f"  Status:      {result.get('status', 'N/A')}")
+        click.echo(f"  Portfolio:   {result.get('portfolio_id', 'N/A')}")
+
+
+@cli.command(short_help="Check processing status")
+@click.argument("upload_id")
+@click.option("--watch/--no-watch", default=False, help="Poll until processing completes")
+@click.option("--timeout", default=600, type=int, help="Watch timeout in seconds (default 600)")
+@click.pass_context
+@handle_errors
+def status(ctx, upload_id, watch, timeout):
+    client = PowderClient()
+
+    if watch:
+        result = client.watch(upload_id, timeout=timeout, callback=lambda r: click.echo(".", nl=False))
+        click.echo()
+    else:
+        result = client.status(upload_id)
+
+    if ctx.obj.get("json_output"):
+        click.echo(json_lib.dumps(result, indent=2))
+    else:
+        status_val = result.get("status", "unknown")
+        click.echo(f"Status: {status_val}")
+        if result.get("portfolio_id"):
+            click.echo(f"  Portfolio: {result['portfolio_id']}")
+        if status_val == "closed" and "error" in result:
+            err = result["error"]
+            if isinstance(err, dict):
+                click.echo(f"  Error:     {err.get('code', 'unknown')} — {err.get('message', '')}")
+            else:
+                click.echo(f"  Error:     {err}")
+            if "closed_at" in result:
+                click.echo(f"  Closed at: {result['closed_at']}")
+
+
+@cli.command(short_help="Retrieve extracted data")
+@click.argument("upload_id")
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["json", "table"]),
+    default="json",
+    help="Output format",
+)
+@click.option("--page", default=1, type=int, help="Page number (default: 1)")
+@click.pass_context
+@handle_errors
+def data(ctx, upload_id, fmt, page):
+    client = PowderClient()
+    result = client.data(upload_id, page=page)
+
+    if fmt == "json" or ctx.obj.get("json_output"):
+        click.echo(json_lib.dumps(result, indent=2))
+        return
+
+    data_dict = result.get("data", {})
+    rows = None
+    title = None
+
+    if isinstance(data_dict, dict):
+        ownerships = data_dict.get("ownerships")
+        transactions = data_dict.get("transactions")
+        if isinstance(ownerships, list):
+            rows = ownerships
+            title = "Ownerships"
+        elif isinstance(transactions, list):
+            rows = transactions
+            title = "Transactions"
+
+    if rows and isinstance(rows, list) and isinstance(rows[0], dict):
+        table = Table(title=title)
+        columns = list(rows[0].keys())
+        for col in columns:
+            table.add_column(str(col))
+        for item in rows:
+            table.add_row(*[str(item.get(col, "")) for col in columns])
+        Console().print(table)
+    else:
+        click.echo("Data structure too complex for table format, showing JSON.")
+        click.echo(json_lib.dumps(result, indent=2))
+        return
+
+    if result.get("count", 0) > 100:
+        total = result["count"]
+        total_pages = (total + 99) // 100
+        click.echo(f"\nShowing page {page} of {total_pages} ({total} total items). Use --page {page + 1} to see more.")

powder_cli-0.1.0/src/powder/client.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+import requests
+
+from powder.config import get_token
+from powder.errors import PowderAPIError, PowderAuthError, PowderTimeoutError
+
+BASE_URL = "https://api.powderfi.com/api/v1.0/public/"
+SUPPORTED_EXTENSIONS = {".pdf", ".png", ".jpg", ".jpeg", ".xlsx"}
+TERMINAL_STATUSES = {"done", "failed", "error", "deleted", "closed"}
+MAX_FILE_SIZE = 50 * 1024 * 1024  # 50MB
+
+VALIDATION_ERROR_MESSAGES = {
+    "PASSWORD_PROTECTED_PDF": "PDF is password-protected. Remove the password and try again.",
+    "CORRUPT_PDF": "PDF file is corrupt or damaged.",
+    "TRUNCATED_PDF": "PDF file appears truncated or incomplete.",
+    "UNREADABLE_PDF": "PDF file could not be read.",
+    "EMPTY_PDF": "PDF file has no pages.",
+    "INVALID_PDF_HEADER": "File does not appear to be a valid PDF.",
+    "PDF_FILE_READ_ERROR": "Error reading PDF file.",
+    "CORRUPT_EXCEL_ZIP": "Excel file is corrupt.",
+    "INVALID_EXCEL_FILE": "File is not a valid Excel file.",
+    "INVALID_EXCEL_FORMAT": "Unsupported Excel format.",
+    "EMPTY_EXCEL": "Excel file has no data.",
+    "EXCEL_FILE_TOO_LARGE": "Excel file is too large to process.",
+    "EXCEL_FILE_READ_ERROR": "Error reading Excel file.",
+    "PASSWORD_PROTECTED_EXCEL": "Excel file is password-protected. Remove the password and try again.",
+    "UNSUPPORTED_FILE_TYPE": "File type is not supported.",
+}
+
+
+class PowderClient:
+    def __init__(self, token: str | None = None, base_url: str | None = None):
+        """Initialize the Powder API client with auth token and base URL."""
+        self.token = token if token is not None else get_token()
+        self.base_url = base_url if base_url is not None else BASE_URL
+        if not self.base_url.endswith("/"):
+            self.base_url += "/"
+
+        self.session = requests.Session()
+        self.session.headers.update({"Authorization": f"Bearer {self.token}", "Accept": "application/json"})
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        """Make an authenticated request to the Powder API and handle errors."""
+        url = self.base_url + path.lstrip("/")
+        # Use longer timeout for uploads (POST with files)
+        default_timeout = 120 if "files" in kwargs else 30
+        kwargs.setdefault("timeout", default_timeout)
+        try:
+            response = self.session.request(method, url, **kwargs)
+        except requests.exceptions.SSLError:
+            raise PowderAPIError(message="SSL certificate error connecting to Powder API") from None
+        except requests.ConnectionError:
+            raise PowderAPIError(message="Cannot reach Powder API. Check your internet connection.") from None
+        except requests.Timeout:
+            raise PowderAPIError(message="Powder API request timed out (30s). Check your connection.") from None
+
+        try:
+            body = response.json()
+            if not isinstance(body, dict):
+                body = {"raw": body}
+        except (json.JSONDecodeError, ValueError):
+            if isinstance(response.text, str):
+                body = {"raw": response.text[:500]}
+            else:
+                body = {"raw": str(response.content[:500])}
+
+        status_code = response.status_code
+
+        if 200 <= status_code <= 299:
+            return body
+        elif status_code == 401:
+            raise PowderAuthError(message=body.get("message", "Authentication failed"), status_code=401, detail=body)
+        elif status_code == 422:
+            error_code = body.get("error_code")
+            human_msg = VALIDATION_ERROR_MESSAGES.get(error_code, body.get("message", "Validation error"))
+            raise PowderAPIError(message=human_msg, status_code=422, detail=body)
+        elif status_code == 400:
+            raise PowderAPIError(message=body.get("message", "Bad request"), status_code=400, detail=body)
+        elif status_code == 403:
+            raise PowderAPIError(message="Access denied", status_code=403, detail=body)
+        elif status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            msg = f"Rate limited. Retry after {retry_after}s" if retry_after else "Rate limited by Powder API"
+            raise PowderAPIError(message=msg, status_code=429, detail=body)
+        elif status_code >= 500:
+            raise PowderAPIError(message="Powder API server error", status_code=status_code, detail=body)
+
+        raise PowderAPIError(message=f"Unexpected error: {status_code}", status_code=status_code, detail=body)
+
+    def upload(self, file_path: str, statement_type: str = "brokerage", portfolio_id: int | None = None) -> dict:
+        """Upload a financial statement file and return the upload record."""
+        resolved = Path(file_path).resolve()
+
+        if not resolved.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        if resolved.suffix.lower() not in SUPPORTED_EXTENSIONS:
+            raise ValueError(
+                f"Unsupported file type '{resolved.suffix}'. Supported: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+            )
+
+        size = resolved.stat().st_size
+        if size == 0:
+            raise ValueError("File is empty")
+
+        if size > MAX_FILE_SIZE:
+            raise ValueError(f"File too large ({size / 1024 / 1024:.1f}MB). Maximum: 50MB")
+
+        try:
+            with open(resolved, "rb") as f:
+                files = {"file": (resolved.name, f)}
+                data = {"statement_type": statement_type}
+                if portfolio_id is not None:
+                    data["portfolio_id"] = portfolio_id
+                return self._request("POST", "file_uploads/", files=files, data=data)
+        except PermissionError:
+            raise PermissionError(f"Cannot read file (permission denied): {file_path}") from None
+
+    def status(self, upload_id: str) -> dict:
+        """Get the current status of an upload."""
+        return self._request("GET", f"file_uploads/{upload_id}/")
+
+    def watch(
+        self, upload_id: str, timeout: int = 600, interval: int = 3, callback: Callable[[dict], None] | None = None
+    ) -> dict:
+        """Poll upload status until completion or timeout, with optional progress callback."""
+        start = time.monotonic()
+        while True:
+            result = self.status(upload_id)
+            if callback:
+                callback(result)
+            if result.get("status") in TERMINAL_STATUSES:
+                return result
+            elapsed = time.monotonic() - start
+            if elapsed >= timeout:
+                raise PowderTimeoutError(upload_id=upload_id, elapsed_seconds=elapsed)
+            time.sleep(interval)
+
+    def data(self, upload_id: str, page: int = 1) -> dict:
+        """Retrieve extracted data from a processed upload."""
+        return self._request("GET", f"file_uploads/{upload_id}/data/", params={"page": page})