picsha-dropzone 1.2.0

Auto-summarizing Dropzone CLI for Picsha AI

📁 Picsha Dropzone CLI

picsha-dropzone is an ultra-fast, concurrent CLI utility designed for photographers, developers, and AI researchers to upload, analyze, and catalog local media directories with Picsha AI.

It processes media files in parallel, triggers AI analysis pipelines (labels, descriptions, reverse-geocoding, and transcoding), generates a predictive Delivery CDN thumbnail set, and outputs local JSON sidecars along with a neat README.md catalog sheet.

---

🚀 Getting Started

Installation

Install globally via pip:

pip install picsha-dropzone

---

⚙️ CLI Command Reference

usage: picsha-dropzone [-h] [-k API_KEY] [-u API_URL] [-w WORKERS] [-c CONFIG] [-d] directory

Positional Arguments

• directory: The path to the folder containing the images or documents you want to process. (Use . for the current active directory).

Optional Flags

• -k, --api-key: Your Picsha API Key (e.g. sk_live_...). If not provided, the CLI will look for the PICSHA_API_KEY environment variable.
• -u, --api-url: The Picsha API endpoint. Defaults to the production server https://api.picsha.ai. For local development testing, use http://localhost:3005.
• -w, --workers: Number of concurrent uploads and workers. Defaults to 5 to guarantee high speed without overloading servers.
• -c, --config: Customizes the ingestion pipeline. Accepts either a raw JSON string (e.g., '{"auto_summarize": false}') or a path to a .json file containing pipeline configurations.
• -d, --download-thumbnails: Tells the CLI to download small and medium thumbnails locally into a hidden .thumbnails/ folder and link them as relative paths in the JSON sidecar instead of using CDN URLs.

---

🛠️ Ingestion Configuration

The -c / --config parameter maps directly to Picsha's Ingestion Pipeline schema. You can toggle individual AI capabilities on or off to balance speed, cost, and metadata richness:

Key	Type	Default	Description
auto_tag	boolean	true	Runs AWS Rekognition for object, label, and face detection.
auto_summarize	boolean	true	Generates short descriptive AI captions/summaries (Claude 3 for images).
vectorize	boolean	true	Generates a Titan multimodal embedding vector for high-dimensional similarity search.
location_lookup	boolean	true	Reverse-geocodes EXIF GPS coordinates via Google Maps API.
adaptive_stream	boolean	false	Transcodes video uploads to adaptive HLS stream playlists using AWS MediaConvert.
render_on_upload	string	null	Semicolon-separated delivery parameters to pre-warm the CDN cache (e.g. "w=300; w=800").

Example JSON Config (settings.json):

{
  "auto_summarize": true,
  "auto_tag": false,
  "location_lookup": true
}

---

💡 Practical Examples

1. Ultra-Fast Upload & Analyze (Default)

Standard run uploading files in parallel using the default API key:

export PICSHA_API_KEY="sk_live_..."
picsha-dropzone /Volumes/Photos/AdobeStock

2. Disabling Costly AI Features

Turn off summarization and Rekognition labels for a raw upload pipeline:

picsha-dropzone . -k sk_live_... -c '{"auto_summarize": false, "auto_tag": false}'

3. Local DAM Mode (Offline Thumbnails)

Downloads low-resolution thumbnails locally into the directory so other offline applications can display them immediately without network requests:

picsha-dropzone . -k sk_live_... --download-thumbnails

Creates a .thumbnails/ folder next to your photos, downloading <filename>_small.jpg (300px width) and <filename>_medium.jpg (800px width).