Metadata-Version: 2.4
Name: picsha-dropzone
Version: 1.2.0
Summary: Auto-summarizing Dropzone CLI for Picsha AI
Author: Picsha AI
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0

# 📁 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:

```bash
pip install picsha-dropzone
```

---

## ⚙️ CLI Command Reference

```text
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`):
```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:
```bash
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:
```bash
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:
```bash
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).*
