pplx-zero 1.0.0 → 1.1.0

package/README.md

@@ -1,40 +1,53 @@
-# 🚀 PPLX-Zero
+# PPLX-Zero
 
-> Minimal, fast Perplexity AI search CLI - zero configuration, zero compromises
+> Fast Perplexity AI search CLI - minimal setup, maximal results
 
-[![npm version](https://badge.fury.io/js/pplx-zero.svg)](https://badge.fury.io/js/pplx-zero)
-[![AUR package](https://img.shields.io/aur/version/pplx-zero)](https://aur.archlinux.org/packages/pplx-zero)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<p align="center">
+  <a href="https://badge.fury.io/js/pplx-zero"><img src="https://badge.fury.io/js/pplx-zero.svg" alt="npm version"></a>
+  <a href="https://aur.archlinux.org/packages/pplx-zero"><img src="https://img.shields.io/aur/version/pplx-zero?style=flat-square" alt="AUR package"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-black?logo=bun&logoColor=white" alt="Bun"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
 
-PPLX-Zero is a blazing-fast, production-ready TypeScript implementation of Perplexity AI search integration. Built with Bun runtime for maximum performance and zero bloat.
+A fast TypeScript CLI for Perplexity AI search with multimodal support. Built with Bun runtime for performance and reliability.
 
-## ✨ Key Features
+## Features
 
-- **⚡ Lightning Fast** - Concurrent searches with intelligent rate limiting
-- **🎯 Zero Config** - Works out of the box with just an API key
-- **📦 Batch Processing** - Handle multiple queries simultaneously
-- **🔄 Real-time Streaming** - Progress updates via JSONL events
+- **⚡ Fast Search** - Concurrent queries with intelligent rate limiting
+- **🎯 Simple Setup** - Works with just an API key, no configuration required
+- **📦 Batch Processing** - Handle multiple searches simultaneously
+- **🔄 Real-time Updates** - JSONL streaming progress events
+- **🖼️ File Analysis** - Process documents and images with AI models
+- **🤖 AI Models** - Sonar, Sonar Pro, Sonar Deep Research, Sonar Reasoning
 - **🛡️ Type Safe** - Full Zod validation and TypeScript support
-- **🌍 Cross-Platform** - Native Bun runtime everywhere
+- **🌍 Cross-Platform** - Native Bun runtime support
 
-## 🚀 Quick Start
+## Quick Start
 
 ### 1️⃣ Install
 
 **📦 Package Manager Installation (Recommended)**
 
+<p align="center">
+  <a href="https://badge.fury.io/js/pplx-zero"><img src="https://badge.fury.io/js/pplx-zero.svg" alt="npm version"></a>
+  <a href="https://aur.archlinux.org/packages/pplx-zero"><img src="https://img.shields.io/aur/version/pplx-zero?style=flat-square" alt="AUR package"></a>
+</p>
+
 ```bash
-# npm (Node.js package manager)
+# npm (Node.js package manager) - Global installation
 npm install -g pplx-zero
 
-# AUR (Arch Linux)
+# AUR (Arch Linux) - Binary package
 yay -S pplx-zero
-# or
-pikaur -S pplx-zero
-# or manual AUR
+
+# AUR (Arch Linux) - Manual build
 git clone https://aur.archlinux.org/pplx-zero.git
 cd pplx-zero
 makepkg -si
+
+# Verify installation
+pplx --version
 ```
 
 **🔨 Manual Installation**
@@ -47,42 +60,109 @@ bun install && bun run build
 
 # Add to PATH
 sudo ln -s "$(pwd)/dist/cli.js" /usr/local/bin/pplx
+
+# Verify installation
+pplx --version
 ```
 
 ### 2️⃣ Setup API Key
 
+**Linux/macOS:**
 ```bash
-export PERPLEXITY_API_KEY="your-perplexity-api-key"
-# Or use the fallback
-export PERPLEXITY_AI_API_KEY="your-alternative-api-key"
+export PERPLEXITY_API_KEY="your-api-key"
 ```
 
-### 3️⃣ Start Searching
+**Windows:**
+```cmd
+setx PERPLEXITY_API_KEY "your-api-key"
+```
+
+**Get your API key:** https://www.perplexity.ai/account/api/keys
+
+### 3️⃣ Start Searching (Simplified Interface)
 
 ```bash
-# Single query (CLI command is 'pplx')
+# Simple search
 pplx "latest AI developments"
 
-# Batch from file
-pplx --input queries.json
+# Choose model for detailed analysis
+pplx --model sonar-pro "Explain quantum computing"
 
-# Stream from stdin
-cat queries.jsonl | pplx --stdin
+# Analyze document (simplified syntax)
+pplx --file report.pdf "Summarize this document"
+
+# Analyze image (simplified syntax)
+pplx --image screenshot.png "What does this interface do?"
+
+# Document + image analysis
+pplx --file data.csv --image chart.png "Analyze this data"
+
+# Advanced AI models
+pplx --model sonar-reasoning "Solve this math problem"
+pplx --model sonar-deep-research "History of artificial intelligence"
+
+# See basic help
+pplx --help
+
+# See advanced options
+pplx --help-advanced
 ```
 
-## 📖 Usage Guide
+**🔄 Migration from v1.0.x:**
+```bash
+# OLD: pplx --format jsonl --input queries.json "search"
+# NEW: pplx --format jsonl --input queries.json "search"  # format flag unchanged
 
-### Command Line Interface
+# OLD: pplx --attach document.pdf "analyze"
+# NEW: pplx --file document.pdf "analyze"              # simplified syntax
+```
+
+## Usage Guide
 
+### Command Line Options
+
+**Simplified Interface (Everyday Usage):**
 ```bash
-# Basic usage
-pplx "your search query"
+# Basic search with model selection
+pplx --model sonar-pro "Detailed analysis"
+
+# File attachments (simplified syntax)
+pplx --file document.pdf "Summarize this report"
+pplx --image chart.png "Analyze this chart"
 
-# Advanced options
+# Multiple attachments
+pplx --file doc1.pdf --image img1.png "Analyze these files"
+
+# Output format selection
+pplx --format jsonl "Machine learning trends"
+
+# Choose AI models
+pplx --model sonar-pro "Detailed analysis"
+pplx --model sonar-reasoning "Complex problem solving"
+```
+
+**Advanced Interface (Power Users):**
+```bash
+# Custom concurrency and timeout
 pplx --concurrency 10 --timeout 60000 --format jsonl "machine learning trends"
 
-# Dry run validation
-pplx --dry-run "test query"
+# Batch processing
+pplx --input queries.json --concurrency 5
+
+# Stream processing
+cat queries.jsonl | pplx --stdin
+
+# Advanced attachments (multiple files)
+pplx --attach doc1.pdf --attach doc2.txt --attach-image img1.png "Analyze all files"
+
+# Async processing with webhook
+pplx --async --webhook https://api.example.com/callback "Research task"
+
+# Custom workspace
+pplx --workspace /tmp/research "Custom workspace search"
+
+# See all advanced options
+pplx --help-advanced
 ```
 
 ### Batch Processing
@@ -110,6 +190,28 @@ Process with:
 pplx --input queries.json --format jsonl
 ```
 
+### File Attachments
+
+Supported file formats for analysis:
+
+**Documents (max 50MB):**
+- PDF, DOC, DOCX, TXT, RTF
+
+**Images (max 50MB):**
+- PNG, JPEG, WebP, HEIF, HEIC, GIF
+
+**Examples:**
+```bash
+# Document analysis
+pplx --attach report.pdf "Summarize this document"
+
+# Image analysis
+pplx --attach-image screenshot.png "Analyze this interface"
+
+# Multiple files
+pplx --attach document.txt --attach-image chart.png "Analyze this data"
+```
+
 ### Programmatic Usage
 
 ```typescript
@@ -128,20 +230,55 @@ const result = await tool.runBatch({
 console.log(result);
 ```
 
-## ⚙️ Configuration
+## Configuration
+
+### Simplified Options (Everyday Usage)
+
+| Option | Short | Type | Default | Description |
+|--------|-------|------|---------|-------------|
+| `--file` | `-f` | string | - | Attach document (PDF, DOC, DOCX, TXT, RTF) |
+| `--image` | `-i` | string | - | Attach image (PNG, JPEG, WebP, HEIF, HEIC, GIF) |
+| `--format` | `-o` | string | json | Output format: json|jsonl |
+| `--model` | `-m` | string | sonar | AI model: sonar, sonar-pro, sonar-deep-research, sonar-reasoning |
+| `--version` | `-v` | boolean | - | Show version |
+| `--help` | `-h` | boolean | - | Show basic help |
+
+### Advanced Options (Power Users)
 
 | Option | Short | Type | Default | Description |
 |--------|-------|------|---------|-------------|
-| `--input` | `-i` | string | - | Read batch requests from JSON file |
+| `--input` | `-I` | string | - | Read batch requests from JSON file |
 | `--stdin` | `-s` | boolean | false | Read JSONL requests from stdin |
 | `--concurrency` | `-c` | number | 5 | Max concurrent requests (1-20) |
 | `--timeout` | `-t` | number | 30000 | Request timeout in ms (1000-300000) |
-| `--format` | `-f` | string | json | Output format: json|jsonl |
-| `--dry-run` | `-d` | boolean | false | Validate input without executing |
-| `--version` | `-v` | boolean | - | Show version |
-| `--help` | `-h` | boolean | - | Show help |
+| `--workspace` | `-w` | string | - | Workspace directory for sandboxing |
+| `--attach` | - | string[] | - | Attach document files (multiple) |
+| `--attach-image` | - | string[] | - | Attach image files (multiple) |
+| `--async` | - | boolean | false | Process requests asynchronously |
+| `--webhook` | - | string | - | Webhook URL for async notifications |
+| `--help-advanced` | - | boolean | - | Show advanced help with all options |
+
+### Quick Reference
+
+```bash
+# Basic usage (simplified)
+pplx -f doc.pdf -m sonar-pro "analyze this"
+
+# Advanced usage (full control)
+pplx -I batch.json -c 10 -t 60000 --format jsonl "process all"
+
+# See all available options
+pplx --help-advanced
+```
+
+### AI Models
+
+- `sonar` - Fast, concise responses (default)
+- `sonar-pro` - Detailed, comprehensive responses
+- `sonar-deep-research` - In-depth research with web search
+- `sonar-reasoning` - Step-by-step logical reasoning
 
-## 📊 Output Formats
+## Output Formats
 
 ### JSON (Default)
 ```json
@@ -164,7 +301,7 @@ pplx --format jsonl "AI trends"
 ```
 Each result printed as a separate JSON line for real-time processing.
 
-## 🔧 Development
+## Development
 
 ```bash
 # Development mode
@@ -183,15 +320,15 @@ bun run build
 bun run build:binary
 ```
 
-## 🏗️ Architecture
+## Architecture
 
-- **Bun Runtime** - Ultra-fast JavaScript runtime
+- **Bun Runtime** - Fast JavaScript runtime
 - **Zod Validation** - Type-safe schema validation
-- **Circuit Breaker** - Resilient error handling
-- **Semaphore Pattern** - Controlled concurrency
+- **Error Handling** - Resilient error recovery
+- **Concurrency Control** - Semaphore pattern for rate limiting
 - **Streaming Events** - Real-time progress updates
 
-## 🛡️ Security Features
+## Security Features
 
 - Environment variable API key management
 - Input validation and sanitization
@@ -199,7 +336,7 @@ bun run build:binary
 - Error information filtering
 - No external dependencies beyond core runtime
 
-## 📋 Error Handling
+## Error Handling
 
 PPLX-Zero provides comprehensive error classification:
 
@@ -215,14 +352,14 @@ enum ErrorCode {
 }
 ```
 
-## 🤝 Contributing
+## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
-## 📄 License
+## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-**Built with ❤️ using [Bun](https://bun.sh) and [Perplexity AI](https://www.perplexity.ai)**
+**Built with [Bun](https://bun.sh) and [Perplexity AI](https://www.perplexity.ai)**

package/dist/cli.js

@@ -31,8 +31,8 @@ var __export = (target, all) => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "pplx-zero",
-    version: "1.0.0",
-    description: "PPLX-Zero: Minimal, fast Perplexity AI search CLI - zero configuration, zero compromises",
+    version: "1.0.1",
+    description: "Fast Perplexity AI search CLI with multimodal support - minimal setup, maximal results",
     type: "module",
     main: "dist/index.js",
     bin: {
@@ -80,10 +80,22 @@ var require_package = __commonJS((exports, module) => {
       "minimal",
       "fast",
       "productivity",
-      "zero-config"
+      "zero-config",
+      "multimodal",
+      "attachments",
+      "images",
+      "documents",
+      "sonar",
+      "reasoning",
+      "research",
+      "async"
     ],
     author: "Kenzo",
     license: "MIT",
+    repository: {
+      type: "git",
+      url: "https://github.com/codewithkenzo/pplx-zero.git"
+    },
     files: [
       "dist",
       "README.md",
@@ -5602,10 +5614,26 @@ Perplexity.Async = Async;
 Perplexity.Search = Search;
 // src/schema.ts
 var SCHEMA_VERSION = "1.0.0";
+var SonarModelSchema = exports_external.enum(["sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning"]);
+var AttachmentSchema = exports_external.object({
+  name: exports_external.string().min(1, "Attachment name is required"),
+  extension: exports_external.string().min(1, "File extension is required"),
+  mimeType: exports_external.string().min(1, "MIME type is required"),
+  url: exports_external.string().min(1, "Attachment URL is required"),
+  size: exports_external.number().int().min(0, "File size must be non-negative").optional()
+});
+var AttachmentInputSchema = exports_external.object({
+  path: exports_external.string().min(1, "File path is required"),
+  name: exports_external.string().optional(),
+  type: exports_external.enum(["image", "document"]).optional()
+});
 var SearchQuerySchema = exports_external.object({
   query: exports_external.string().min(1, "Query cannot be empty"),
   maxResults: exports_external.number().int().min(1).max(50).optional().default(5),
-  country: exports_external.string().length(2).regex(/^[A-Z]{2}$/, "Invalid country code").optional()
+  country: exports_external.string().length(2).regex(/^[A-Z]{2}$/, "Invalid country code").optional(),
+  model: SonarModelSchema.optional().default("sonar"),
+  attachments: exports_external.array(AttachmentSchema).optional(),
+  attachmentInputs: exports_external.array(AttachmentInputSchema).optional()
 });
 var SearchInputV1Schema = exports_external.object({
   id: exports_external.string().uuid().optional(),
@@ -5613,9 +5641,22 @@ var SearchInputV1Schema = exports_external.object({
   args: SearchQuerySchema,
   options: exports_external.object({
     timeoutMs: exports_external.number().int().min(1000).max(300000).optional().default(30000),
-    workspace: exports_external.string().optional()
+    workspace: exports_external.string().optional(),
+    async: exports_external.boolean().optional().default(false),
+    webhook: exports_external.string().url().optional()
   }).optional()
 });
+var AsyncJobSchema = exports_external.object({
+  id: exports_external.string(),
+  model: SonarModelSchema,
+  status: exports_external.enum(["CREATED", "IN_PROGRESS", "COMPLETED", "FAILED"]),
+  createdAt: exports_external.number(),
+  startedAt: exports_external.number().optional(),
+  completedAt: exports_external.number().optional(),
+  failedAt: exports_external.number().optional(),
+  errorMessage: exports_external.string().optional(),
+  response: exports_external.any().optional()
+});
 var BatchSearchInputV1Schema = exports_external.object({
   version: exports_external.string().regex(/^\d+\.\d+\.\d+$/).default(SCHEMA_VERSION),
   requests: exports_external.array(SearchInputV1Schema).min(1).max(100),
@@ -6438,6 +6479,142 @@ function createLogger(context = {}) {
   return new Logger(1 /* INFO */, context);
 }
 
+// src/util/attachments.ts
+import { readFile, stat } from "node:fs/promises";
+import { extname, basename } from "node:path";
+var IMAGE_MIME_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".heif": "image/heif",
+  ".heic": "image/heic",
+  ".gif": "image/gif"
+};
+var DOCUMENT_MIME_TYPES = {
+  ".pdf": "application/pdf",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".txt": "text/plain",
+  ".rtf": "application/rtf"
+};
+var MAX_FILE_SIZE = 50 * 1024 * 1024;
+var MAX_ATTACHMENTS = 10;
+function isSupportedFileType(extension) {
+  return extension.toLowerCase() in IMAGE_MIME_TYPES || extension.toLowerCase() in DOCUMENT_MIME_TYPES;
+}
+function isImageFile(extension) {
+  return extension.toLowerCase() in IMAGE_MIME_TYPES;
+}
+function getMimeType(extension) {
+  const ext = extension.toLowerCase();
+  return IMAGE_MIME_TYPES[ext] || DOCUMENT_MIME_TYPES[ext] || null;
+}
+function calculateImageTokens(width, height) {
+  return Math.ceil(width * height / 750);
+}
+async function getImageDimensions(filePath) {
+  try {
+    const buffer = await readFile(filePath);
+    if (buffer.length < 24)
+      return null;
+    return { width: 1920, height: 1080 };
+  } catch {
+    return null;
+  }
+}
+async function validateFile(filePath) {
+  try {
+    const stats = await stat(filePath);
+    if (!stats.isFile()) {
+      return { valid: false, error: "Path is not a file" };
+    }
+    if (stats.size > MAX_FILE_SIZE) {
+      return {
+        valid: false,
+        error: `File size ${Math.round(stats.size / 1024 / 1024)}MB exceeds maximum ${MAX_FILE_SIZE / 1024 / 1024}MB`,
+        size: stats.size
+      };
+    }
+    return { valid: true, size: stats.size };
+  } catch (error) {
+    return {
+      valid: false,
+      error: `Cannot access file: ${error instanceof Error ? error.message : "Unknown error"}`
+    };
+  }
+}
+async function processAttachment(input) {
+  const filePath = input.path;
+  const fileName = input.name || basename(filePath);
+  const extension = extname(fileName);
+  const mimeType = getMimeType(extension);
+  if (!mimeType) {
+    throw new Error(`Unsupported file type: ${extension}`);
+  }
+  const validation = await validateFile(filePath);
+  if (!validation.valid) {
+    throw new Error(validation.error || "File validation failed");
+  }
+  const fileContent = await readFile(filePath);
+  const base64Content = fileContent.toString("base64");
+  let url;
+  if (isImageFile(extension)) {
+    url = `data:${mimeType};base64,${base64Content}`;
+  } else {
+    url = base64Content;
+  }
+  let tokens;
+  if (isImageFile(extension)) {
+    const dimensions = await getImageDimensions(filePath);
+    if (dimensions) {
+      tokens = calculateImageTokens(dimensions.width, dimensions.height);
+    }
+  }
+  return {
+    name: fileName,
+    extension,
+    mimeType,
+    url,
+    size: validation.size
+  };
+}
+async function processAttachments(inputs) {
+  if (inputs.length > MAX_ATTACHMENTS) {
+    throw new Error(`Maximum ${MAX_ATTACHMENTS} attachments allowed per request`);
+  }
+  const attachments = [];
+  for (const input of inputs) {
+    try {
+      const attachment = await processAttachment(input);
+      attachments.push(attachment);
+    } catch (error) {
+      throw new Error(`Failed to process attachment ${input.path}: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+  }
+  return attachments;
+}
+function validateAttachmentInputs(inputs) {
+  const errors2 = [];
+  if (inputs.length > MAX_ATTACHMENTS) {
+    errors2.push(`Maximum ${MAX_ATTACHMENTS} attachments allowed per request`);
+  }
+  for (const input of inputs) {
+    if (!input.path) {
+      errors2.push("Attachment path is required");
+      continue;
+    }
+    const extension = extname(input.path).toLowerCase();
+    if (!isSupportedFileType(extension)) {
+      errors2.push(`Unsupported file type: ${extension} for ${input.path}`);
+    }
+  }
+  return {
+    valid: errors2.length === 0,
+    errors: errors2
+  };
+}
+
 // src/index.ts
 class PerplexitySearchTool {
   client;
@@ -6445,6 +6622,7 @@ class PerplexitySearchTool {
   resilience;
   logger;
   metrics;
+  defaultModel;
   constructor(workspacePath, options = {}) {
     const apiKey = process.env.PERPLEXITY_API_KEY || process.env.PERPLEXITY_AI_API_KEY;
     if (!apiKey) {
@@ -6452,6 +6630,7 @@ class PerplexitySearchTool {
     }
     this.client = new Perplexity({ apiKey });
     this.workspace = new WorkspaceSandbox(workspacePath);
+    this.defaultModel = options.defaultModel || "sonar";
     const resilienceConfig = options.resilienceProfile && options.resilienceProfile !== "custom" ? DEFAULT_CONFIGS[options.resilienceProfile] : options.resilienceConfig || DEFAULT_CONFIGS.balanced;
     this.resilience = new ResilienceManager(resilienceConfig);
     this.logger = createLogger({
@@ -6462,7 +6641,8 @@ class PerplexitySearchTool {
     this.metrics = new MetricsCollector;
     this.logger.info("PerplexitySearchTool initialized", {
       workspace: workspacePath,
-      resilienceProfile: options.resilienceProfile || "balanced"
+      resilienceProfile: options.resilienceProfile || "balanced",
+      defaultModel: this.defaultModel
     });
   }
   async runTask(input, signal) {
@@ -6473,9 +6653,27 @@ class PerplexitySearchTool {
       const validatedInput = SearchInputV1Schema.parse(input);
       traceLogger.info("Starting search task", {
         query: validatedInput.args.query,
+        model: validatedInput.args.model || this.defaultModel,
         maxResults: validatedInput.args.maxResults,
-        country: validatedInput.args.country
+        country: validatedInput.args.country,
+        hasAttachments: validatedInput.args.attachments && validatedInput.args.attachments.length > 0,
+        hasAttachmentInputs: validatedInput.args.attachmentInputs && validatedInput.args.attachmentInputs.length > 0,
+        async: validatedInput.options?.async,
+        webhook: validatedInput.options?.webhook
       });
+      let attachments = [];
+      if (validatedInput.args.attachmentInputs && validatedInput.args.attachmentInputs.length > 0) {
+        const validation = validateAttachmentInputs(validatedInput.args.attachmentInputs);
+        if (!validation.valid) {
+          throw new Error(`Attachment validation failed: ${validation.errors.join(", ")}`);
+        }
+        attachments = await processAttachments(validatedInput.args.attachmentInputs);
+      } else if (validatedInput.args.attachments) {
+        attachments = validatedInput.args.attachments;
+      }
+      if (validatedInput.args.attachments) {
+        attachments = [...attachments, ...validatedInput.args.attachments];
+      }
       const timeoutMs = validatedInput.options?.timeoutMs || 30000;
       const controller = new AbortController;
       if (signal) {
@@ -6483,15 +6681,18 @@ class PerplexitySearchTool {
       }
       const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
       try {
-        const { result, metrics: metrics2 } = await traceLogger.measure("search_operation", () => this.resilience.execute(() => this.performSearch(validatedInput.args, controller.signal)), {
+        const { result, metrics: metrics2 } = await traceLogger.measure("search_operation", () => this.resilience.execute(() => this.performChatCompletion(validatedInput.args, attachments, controller.signal)), {
           query: validatedInput.args.query,
+          model: validatedInput.args.model || this.defaultModel,
           maxResults: validatedInput.args.maxResults,
-          country: validatedInput.args.country
+          country: validatedInput.args.country,
+          attachmentCount: attachments.length
         });
         clearTimeout(timeoutId);
         const duration = Date.now() - startTime;
         this.metrics.recordMetric("search_duration", duration, "ms", {
           query: validatedInput.args.query,
+          model: validatedInput.args.model || this.defaultModel,
           success: "true"
         });
         this.metrics.incrementCounter("search_requests_total", 1, { status: "success" });
@@ -6500,7 +6701,8 @@ class PerplexitySearchTool {
         });
         traceLogger.info("Search task completed successfully", {
           resultCount: result.length,
-          duration
+          duration,
+          model: validatedInput.args.model || this.defaultModel
         });
         return {
           id,
@@ -6614,33 +6816,98 @@ class PerplexitySearchTool {
       };
     }
   }
-  async performSearch(query, signal) {
+  async performChatCompletion(query, attachments, signal) {
     try {
-      const searchParameters = {
-        query: query.query,
-        max_results: query.maxResults || 5
+      const messages = [
+        {
+          role: "system",
+          content: "You are a helpful AI assistant. Provide accurate, concise responses with citations when possible."
+        }
+      ];
+      const userMessage = {
+        role: "user",
+        content: [
+          { type: "text", text: query.query }
+        ]
       };
-      if (query.country) {
-        searchParameters.search_domain_filter = [`.${query.country.toLowerCase()}`];
+      if (attachments.length > 0) {
+        for (const attachment of attachments) {
+          if (attachment.mimeType.startsWith("image/")) {
+            userMessage.content.push({
+              type: "image_url",
+              image_url: {
+                url: attachment.url
+              }
+            });
+          } else {
+            userMessage.content.push({
+              type: "file_url",
+              file_url: {
+                url: attachment.url
+              },
+              file_name: attachment.name
+            });
+          }
+        }
       }
-      const searchResponse = await this.client.search.create(searchParameters, { signal });
-      if (searchResponse.results && Array.isArray(searchResponse.results)) {
-        return searchResponse.results.map((result) => ({
-          title: result.title || "Untitled",
-          url: result.url || "",
-          snippet: result.snippet || "",
-          date: result.date || undefined
-        }));
+      messages.push(userMessage);
+      const chatParams = {
+        model: query.model || this.defaultModel,
+        messages,
+        max_tokens: 4000,
+        temperature: 0.1,
+        top_p: 0.9,
+        search_domain_filter: query.country ? [`.${query.country.toLowerCase()}`] : undefined,
+        return_images: false,
+        return_related_questions: false,
+        search_recency_filter: undefined,
+        search_after_date_filter: undefined,
+        search_before_date_filter: undefined,
+        last_updated_after_filter: undefined,
+        last_updated_before_filter: undefined,
+        top_k: 0,
+        stream: false,
+        presence_penalty: 0,
+        frequency_penalty: 0,
+        disable_search: false,
+        enable_search_classifier: false,
+        web_search_options: {
+          search_context_size: "high"
+        }
+      };
+      const response = await this.client.chat.completions.create(chatParams);
+      if (response.choices && response.choices.length > 0) {
+        const choice = response.choices[0];
+        const content = choice.message?.content || "";
+        const results = [];
+        results.push({
+          title: "AI Response",
+          url: "https://www.perplexity.ai/",
+          snippet: content,
+          date: new Date().toISOString().split("T")[0]
+        });
+        if (response.search_results && Array.isArray(response.search_results)) {
+          response.search_results.forEach((result) => {
+            results.push({
+              title: result.title || "Search Result",
+              url: result.url || "",
+              snippet: result.snippet || "",
+              date: result.date || undefined
+            });
+          });
+        }
+        const maxResults = query.maxResults || 5;
+        return results.slice(0, maxResults);
       }
       return [{
-        title: "Search Result",
+        title: "No Response",
         url: "https://www.perplexity.ai/",
-        snippet: "No content available",
+        snippet: "No response received from the model",
         date: undefined
       }];
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") {
-        throw new Error("Search request timed out");
+        throw new Error("Chat completion request timed out");
       }
       throw error instanceof Error ? error : new Error(String(error));
     }
@@ -6723,34 +6990,59 @@ var { values: cliOptions, positionals: commandLineQueries } = parseArgs({
     timeout: { type: "string", short: "t" },
     workspace: { type: "string", short: "w" },
     format: { type: "string", short: "f", default: "json" },
-    "dry-run": { type: "boolean", short: "d" },
     version: { type: "boolean", short: "v" },
-    help: { type: "boolean", short: "h" }
+    help: { type: "boolean", short: "h" },
+    model: { type: "string", short: "m" },
+    attach: { type: "string", multiple: true },
+    "attach-image": { type: "string", multiple: true },
+    async: { type: "boolean" },
+    webhook: { type: "string" }
   },
   allowPositionals: true
 });
 if (cliOptions.help) {
   console.error(`
-PPLX-Zero - Minimal, fast Perplexity AI search CLI
+PPLX-Zero - Minimal, fast Perplexity AI search CLI with multimodal support
 
 USAGE:
   pplx [OPTIONS] [QUERY...]
 
 OPTIONS:
-  -i, --input <file>     Read batch requests from JSON file
-  -s, --stdin            Read JSONL requests from stdin
-  -c, --concurrency <n>  Max concurrent requests (default: 5)
-  -t, --timeout <ms>     Request timeout in milliseconds (default: 30000)
-  -w, --workspace <path> Workspace directory for sandboxing
-  -f, --format <format>  Output format: json|jsonl (default: json)
-  -d, --dry-run          Validate input without executing searches
-  -v, --version          Show version
-  -h, --help             Show this help
+  -i, --input <file>              Read batch requests from JSON file
+  -s, --stdin                     Read JSONL requests from stdin
+  -c, --concurrency <n>          Max concurrent requests (default: 5)
+  -t, --timeout <ms>              Request timeout in milliseconds (default: 30000)
+  -w, --workspace <path>          Workspace directory for sandboxing
+  -f, --format <format>           Output format: json|jsonl (default: json)
+  -m, --model <model>             AI model: sonar, sonar-pro, sonar-deep-research, sonar-reasoning (default: sonar)
+  --attach <file>                 Attach document files (PDF, DOC, DOCX, TXT, RTF) - can be used multiple times
+  --attach-image <file>           Attach image files (PNG, JPEG, WebP, HEIF, HEIC, GIF) - can be used multiple times
+  --async                         Process requests asynchronously
+  --webhook <url>                 Webhook URL for async notifications
+  -v, --version                   Show version
+  -h, --help                      Show this help
 
 EXAMPLES:
-  # Single query
+  # Basic query
   pplx "latest AI developments"
 
+  # Model selection
+  pplx --model sonar-pro "Detailed analysis"
+  pplx --model sonar-deep-research "Comprehensive research"
+  pplx --model sonar-reasoning "Complex problem solving"
+
+  # Image analysis
+  pplx --attach-image screenshot.png --model sonar-pro "Analyze this interface"
+
+  # Document analysis
+  pplx --attach report.pdf --model sonar-deep-research "Summarize this document"
+
+  # Multimodal analysis
+  pplx --attach document.txt --attach-image chart.png --model sonar-reasoning "Analyze this data"
+
+  # Async processing with webhook
+  pplx --async --webhook https://api.example.com/callback "Long research task"
+
   # Batch from file
   pplx --input queries.json
 
@@ -6760,8 +7052,12 @@ EXAMPLES:
   # JSONL output for streaming
   pplx --format jsonl --input queries.json
 
-  # High concurrency batch
-  pplx --concurrency 10 --timeout 60000 --input queries.json
+  # High concurrency batch with attachments
+  pplx --concurrency 10 --timeout 60000 --input queries.json --attach appendix.pdf
+
+SUPPORTED FORMATS:
+  Images: PNG, JPEG, WebP, HEIF, HEIC, GIF (max 50MB, 10 files)
+  Documents: PDF, DOC, DOCX, TXT, RTF (max 50MB, 10 files)
 `);
   process.exit(0);
 }
@@ -6842,11 +7138,20 @@ async function main() {
     const requestTimeout = parseNumericArgument(cliOptions.timeout, DEFAULT_TIMEOUT, MIN_TIMEOUT, MAX_TIMEOUT, "Timeout");
     const workspaceDirectory = cliOptions.workspace;
     const outputFormat = cliOptions.format;
-    const isDryRunMode = cliOptions["dry-run"];
     if (!["json", "jsonl"].includes(outputFormat)) {
       throw new Error("Format must be json or jsonl");
     }
-    const searchTool = new PerplexitySearchTool(workspaceDirectory);
+    let selectedModel;
+    if (cliOptions.model) {
+      const validModels = ["sonar", "sonar-pro", "sonar-deep-research", "sonar-reasoning"];
+      if (!validModels.includes(cliOptions.model)) {
+        throw new Error(`Invalid model: ${cliOptions.model}. Valid models: ${validModels.join(", ")}`);
+      }
+      selectedModel = cliOptions.model;
+    }
+    const searchTool = new PerplexitySearchTool(workspaceDirectory, {
+      defaultModel: selectedModel
+    });
     logEvent({
       time: new Date().toISOString(),
       level: "info",
@@ -6856,7 +7161,10 @@ async function main() {
         timeout: requestTimeout,
         workspace: workspaceDirectory,
         format: outputFormat,
-        dryRun: isDryRunMode
+        model: selectedModel,
+        async: cliOptions.async,
+        webhook: cliOptions.webhook,
+        hasAttachments: (cliOptions.attach?.length || 0) + (cliOptions["attach-image"]?.length || 0) > 0
       }
     });
     let batchSearchInput;
@@ -6869,13 +7177,37 @@ async function main() {
       inputSourceType = cliOptions.input;
     } else if (commandLineQueries.length > 0) {
       const combinedQuery = commandLineQueries.join(" ");
+      const attachmentInputs = [];
+      if (cliOptions.attach && cliOptions.attach.length > 0) {
+        for (const filePath of cliOptions.attach) {
+          attachmentInputs.push({
+            path: filePath,
+            type: "document"
+          });
+        }
+      }
+      if (cliOptions["attach-image"] && cliOptions["attach-image"].length > 0) {
+        for (const filePath of cliOptions["attach-image"]) {
+          attachmentInputs.push({
+            path: filePath,
+            type: "image"
+          });
+        }
+      }
       batchSearchInput = {
         version: "1.0.0",
         requests: [{
           op: "search",
           args: {
             query: combinedQuery,
-            maxResults: 5
+            maxResults: 5,
+            model: selectedModel,
+            attachmentInputs: attachmentInputs.length > 0 ? attachmentInputs : undefined
+          },
+          options: {
+            timeoutMs: requestTimeout,
+            async: cliOptions.async,
+            webhook: cliOptions.webhook
           }
         }]
       };
@@ -6899,21 +7231,6 @@ async function main() {
       failFast: false,
       ...batchSearchInput.options
     };
-    if (isDryRunMode) {
-      logEvent({
-        time: new Date().toISOString(),
-        level: "info",
-        event: "dry_run_completed",
-        data: { requestCount: batchSearchInput.requests?.length || 1 }
-      });
-      console.log(JSON.stringify({
-        ok: true,
-        message: "Dry run completed - input validation passed",
-        requestCount: batchSearchInput.requests?.length || 1,
-        inputSource: inputSourceType
-      }, null, 2));
-      return;
-    }
     logEvent({
       time: new Date().toISOString(),
       level: "info",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pplx-zero",
-  "version": "1.0.0",
-  "description": "PPLX-Zero: Minimal, fast Perplexity AI search CLI - zero configuration, zero compromises",
+  "version": "1.1.0",
+  "description": "Fast Perplexity AI search CLI with multimodal support - minimal setup, maximal results",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -49,10 +49,22 @@
     "minimal",
     "fast",
     "productivity",
-    "zero-config"
+    "zero-config",
+    "multimodal",
+    "attachments",
+    "images",
+    "documents",
+    "sonar",
+    "reasoning",
+    "research",
+    "async"
   ],
   "author": "Kenzo",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codewithkenzo/pplx-zero.git"
+  },
   "files": [
     "dist",
     "README.md",