pplx-zero 1.1.8 → 2.1.0

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,546 +1,133 @@
-# PPLX‑Zero
+# pplx-zero
 
-🚀 **Lightning-fast Perplexity AI in your terminal** — sub‑1s search responses with multimodal support. Built for developers, coding agents, and automation workflows that demand speed and reliability.
+[![npm version](https://img.shields.io/npm/v/pplx-zero.svg)](https://www.npmjs.com/package/pplx-zero)
+[![AUR version](https://img.shields.io/aur/version/pplx-zero)](https://aur.archlinux.org/packages/pplx-zero)
+![Bun](https://img.shields.io/badge/runtime-bun-f9f1e1)
+![License](https://img.shields.io/badge/license-MIT-blue)
 
-Perfect for rapid research, document analysis, image understanding, and batch processing with minimal configuration.
-
----
-
-## ✨ What Makes PPLX‑Zero Special
-
-- **⚡ Blazing Fast**: Get answers in under a second with optimized API calls
-- **🧠 Smart Models**: Choose from Sonar, Sonar‑Pro, Sonar‑Reasoning, and Deep‑Research models
-- **📎 Multimodal**: Analyze documents, images, and combinations seamlessly
-- **🔄 Auto‑Update**: Stay current with simplified update management
-- **⚙️ Developer‑First**: Built for CI/CD, agent pipelines, and programmatic use
-- **🎯 Minimal Setup**: One environment variable and you're ready to go
-
-## 📦 Installation
-
-Choose the installation method that works best for you:
-
-### 🚀 Quick Install (Recommended)
+Search the web with AI from your terminal. Zero bloat, maximum speed.
 
 ```bash
-# npm or bun (global)
-npm install -g pplx-zero
-# or
-bun install -g pplx-zero
-
-# Verify installation
-pplx --version
+pplx "what is bun"
 ```
 
-### 📦 Binary Download (No Node.js required)
+## Why pplx-zero?
 
-```bash
-# Download the appropriate binary for your platform
-# Linux (x64) - Most servers and desktops
-wget https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-linux-x64
-chmod +x pplx-v1.1.7-linux-x64
-sudo mv pplx-v1.1.7-linux-x64 /usr/local/bin/pplx
-
-# Linux (ARM64) - Raspberry Pi, ARM servers
-wget https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-linux-arm64
-chmod +x pplx-v1.1.7-linux-arm64
-sudo mv pplx-v1.1.7-linux-arm64 /usr/local/bin/pplx
-
-# macOS (Intel) - Macs with Intel processors
-wget https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-darwin-x64
-chmod +x pplx-v1.1.7-darwin-x64
-sudo mv pplx-v1.1.7-darwin-x64 /usr/local/bin/pplx
-
-# macOS (Apple Silicon) - Macs with M1/M2/M3 chips
-wget https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-darwin-arm64
-chmod +x pplx-v1.1.7-darwin-arm64
-sudo mv pplx-v1.1.7-darwin-arm64 /usr/local/bin/pplx
-
-# Windows (x64) - Most Windows computers
-# Download pplx-v1.1.7-windows-x64.exe from GitHub releases
-# Add to your PATH or run directly
-```
+- **Fast** — Bun-native, streams responses as they arrive
+- **Minimal** — ~400 lines of code, one dependency (zod)
+- **Powerful** — 5 models including deep research, file & image support
+- **Conversational** — Continue previous queries with `-c`
+- **Unix-friendly** — Pipes, JSON output, history, exit codes done right
 
-**Alternative Installation Script (Linux/macOS):**
+## Installation
 
 ```bash
-# Automated installation script
-curl -sSL https://github.com/codewithkenzo/pplx-zero/releases/latest/download/pplx-v1.1.7-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/x64/') -o pplx
-chmod +x pplx
-sudo mv pplx /usr/local/bin/pplx
-```
+# Bun (recommended)
+bun install -g pplx-zero
 
-### 🏛️ AUR (Arch Linux)
+# npm (requires bun installed)
+npm install -g pplx-zero
 
-```bash
-# Using yay (recommended)
+# Arch Linux
 yay -S pplx-zero
-
-# Using paru
-paru -S pplx-zero
-
-# Verify installation
-pplx --version
-```
-
-### 🔧 Build from Source
-
-```bash
-# 1) Clone the repository
-git clone https://github.com/codewithkenzo/pplx-zero.git
-cd pplx-zero
-
-# 2) Install dependencies and build
-bun install && bun run build
-
-# 3) Link the CLI (system-wide)
-sudo ln -s "$(pwd)/dist/index.js" /usr/local/bin/pplx
-
-# 4) Verify installation
-pplx --version
-```
-
----
-
-## ⚙️ Configuration
-
-### API Key Setup
-
-Set your Perplexity API key as an environment variable:
-
-**Linux/macOS:**
-```bash
-# Temporary (current session)
-export PERPLEXITY_API_KEY="your-api-key"
-
-# Permanent (add to ~/.bashrc, ~/.zshrc, etc.)
-echo 'export PERPLEXITY_API_KEY="your-api-key"' >> ~/.bashrc
-source ~/.bashrc
-```
-
-**Windows (PowerShell):**
-```powershell
-# Temporary (current session)
-$env:PERPLEXITY_API_KEY = "your-api-key"
-
-# Permanent
-[Environment]::SetEnvironmentVariable("PERPLEXITY_API_KEY", "your-api-key", "User")
-```
-
-**Windows (CMD):**
-```cmd
-# Permanent
-setx PERPLEXITY_API_KEY "your-api-key"
-```
-
-> 🔑 **Get your API key** from your [Perplexity account settings](https://www.perplexity.ai/settings/api) and keep it secure. Never share your API key or commit it to version control.
-
----
-
-## 🔄 Auto‑Update Management
-
-PPLX‑Zero includes a simplified auto‑update system that keeps you current with the latest features and security updates.
-
-### Basic Update Commands
-
-```bash
-# Check for available updates
-pplx update --check
-
-# Install updates and relaunch automatically
-pplx update --auto
-```
-
-### Update Workflow
-
-1. **Automatic Notifications**: PPLX‑Zero checks for updates once per day and notifies you when a new version is available
-2. **Smart Installation**: The updater detects your installation method (npm, AUR, binary) and uses the appropriate update mechanism
-3. **Seamless Relaunch**: When using `--auto`, PPLX‑Zero installs the update and relaunches with your original command
-
-### Advanced Update Options
-
-```bash
-# Force update check (ignores cache)
-pplx update --check
-
-# Update during automation without interaction
-pplx update --auto --quiet
-```
-
-### Troubleshooting Updates
-
-| Issue | Solution |
-|-------|----------|
-| **Permission denied** | Run with `sudo` or check installation directory permissions |
-| **Network timeout** | Check internet connection and try again |
-| **Update fails** | Manually install using your original installation method |
-| **Lock file error** | Wait for current update to complete or manually remove `~/.pplx-zero/.updating.lock` |
-
-The auto‑update system respects your system configuration and won't modify files without proper permissions.
-
----
-
-## 🚀 Quick Examples
-
-### Basic Search
-
-```bash
-# Simple search (default model: sonar)
-pplx "python type hints best practices"
-
-# Multiple queries in one command
-pplx "React hooks tutorial" "TypeScript generics" "Docker best practices"
-```
-
-### Advanced Models
-
-```bash
-# Research with Sonar Pro (more detailed analysis)
-pplx -m sonar-pro "React 19 Hooks new features"
-
-# Deep research with comprehensive web context
-pplx -m sonar-deep-research "best Rust web frameworks 2025"
-
-# Mathematical reasoning and proofs
-pplx -m sonar-reasoning "prove this algorithm runs in O(n log n)"
-```
-
-### Document & Image Analysis
-
-```bash
-# Summarize a PDF report quickly
-pplx -f report.pdf "summarize key findings and risks"
-
-# Understand an interface from a screenshot
-pplx -i screenshot.png "what is this UI and what are the next steps?"
-
-# Combine multiple files in one analysis
-pplx -f data.csv -i chart.png "spot anomalies and explain the chart"
-
-# Multiple file attachments
-pplx -f report.pdf --attach data.csv --attach summary.md "analyze all documents"
-
-# Multiple documents of same type using --attach
-pplx --attach doc1.pdf --attach doc2.pdf --attach doc3.txt "compare all reports"
-
-# Multiple images using --attach-image
-pplx --attach-image screenshot1.png --attach-image screenshot2.png "analyze the UI flow"
-
-# Mixed multiple files (documents + images)
-pplx -f main.pdf --attach appendix.md --attach-image chart.png --attach-image diagram.jpg "comprehensive analysis"
-
-# Multiple files with positional arguments (all treated as files)
-pplx file1.pdf file2.txt file3.md "what's in these files"
-```
-
-### Batch Processing
-
-```bash
-# Stream newline-delimited JSON for agents or UNIX pipes
-pplx -o jsonl "AI trends"
-
-# Batch from a JSON file with custom concurrency
-pplx -I queries.json -o jsonl -c 5 -t 30000
 ```
 
-**Batch JSON format:**
-```json
-{
-  "version": "1.0.0",
-  "requests": [
-    { "op": "search", "args": { "query": "AI trends", "maxResults": 5 } },
-    { "op": "search", "args": { "query": "TypeScript patterns", "maxResults": 3 } }
-  ],
-  "options": { "concurrency": 5, "timeoutMs": 30000 }
-}
-```
+## Setup
 
-### Advanced Workflows
+Get your API key from [Perplexity Settings](https://www.perplexity.ai/settings/api).
 
 ```bash
-# Fire-and-forget async with webhook callback
-pplx --async --webhook http://localhost:3000/callback "long research task"
-
-# Export results to file
-pplx --export results.json "machine learning trends"
-
-# Search with custom result limits
-pplx -n 10 "latest web development frameworks"
-
-# Query from stdin (for pipelines)
-echo '{"query": "best practices for API design"}' | pplx -s
+export PERPLEXITY_API_KEY="pplx-..."
 ```
 
-### Real‑World Scenarios
+## Usage
 
 ```bash
-# Security researcher: Analyze vulnerability report
-pplx -f vuln_report.pdf --attach screenshots/ "explain security implications"
-
-# Data analyst: Extract insights from datasets
-pplx -f sales_data.csv -i revenue_chart.png "identify growth opportunities"
-
-# Developer: Code review and optimization
-pplx -f app.py --attach perf_metrics.json "suggest performance improvements"
-
-# Product manager: Competitive analysis
-pplx -f competitor_data.pdf "summarize key differentiators and market position"
-```
-
-
----
-
-## 📋 Command Reference
-
-### Main Options
-
-| Flag | Short | Description | Example |
-|------|-------|-------------|---------|
-| `--model` | `-m` | AI model to use | `-m sonar-pro` |
-| `--max-results` | `-n` | Max results per query (1-20) | `-n 10` |
-| `--file` | `-f` | Attach document for analysis | `-f report.pdf` |
-| `--image` | `-i` | Attach image for analysis | `-i screenshot.png` |
-| `--format` | `-o` | Output format: json/jsonl | `-o jsonl` |
-| `--query` | `-q` | Search query (alternative to positional) | `-q "search term"` |
-| `--export` | | Export results to file | `--export results.json` |
-| `--input` | `-I` | Read queries from JSON file | `-I batch.json` |
-| `--stdin` | `-s` | Read queries from stdin | `cat query.json \| pplx -s` |
-| `--attach` | | Additional file attachments | `--attach file1.pdf --attach file2.txt` |
-| `--attach-image` | | Additional image attachments | `--attach-image img1.png --attach-image img2.jpg` |
-| `--async` | | Enable async mode for advanced models | `--async` |
-| `--webhook` | | Webhook URL for async results | `--webhook http://localhost:3000` |
-| `--workspace` | | Workspace directory for file operations | `--workspace ./project` |
-| `--use-search-api` | | Use search API (default: true) | `--use-search-api` |
-| `--batch-size` | | Batch size for processing (1-100) | `--batch-size 50` |
-
-### Performance & Control
-
-| Flag | Description | Default | Range |
-|------|-------------|---------|-------|
-| `--concurrency` | Max parallel requests for batch operations | 5 | 1-20 |
-| `--timeout` | Request timeout in milliseconds | 30000 | 1000-300000 |
-
-### Utility Commands
+# Quick search
+pplx "best practices for error handling in typescript"
 
-| Command | Description | Example |
-|---------|-------------|---------|
-| `update --check` | Check for available updates | `pplx update --check` |
-| `update --auto` | Install updates and relaunch | `pplx update --auto` |
-| `history [limit]` | Show search history | `pplx history 10` |
-| `version` | Show version information | `pplx version` |
-| `--help` | Show help message | `pplx --help` |
-| `--version` | Show version number | `pplx --version` |
+# Use a more powerful model
+pplx -m sonar-pro "explain quantum entanglement simply"
 
-### Supported File Formats
+# Deep research mode (takes longer, more comprehensive)
+pplx -m sonar-deep-research "comprehensive analysis of AI regulation in 2024"
 
-**Documents (up to 50MB):**
-- PDF, DOC, DOCX, TXT, RTF, MD
-- CSV, JSON (structured data)
-- XML, YAML (configuration files)
+# Analyze a document
+pplx -f report.pdf "summarize the key findings"
 
-**Images (up to 50MB):**
-- PNG, JPEG, WebP, HEIF/HEIC, GIF
-- BMP, TIFF (legacy formats)
+# Describe an image
+pplx -i screenshot.png "what's happening in this image"
 
-### AI Models
+# Continue a conversation
+pplx "what is rust"
+pplx -c "how does it compare to go?"
+pplx -c "which should I learn first?"
 
-| Model | Best For | Speed | Detail |
-|-------|----------|-------|--------|
-| `sonar` | Quick answers, general queries | ⚡ Fast | Standard detail |
-| `sonar-pro` | Detailed analysis, research | 🚀 Fast | Enhanced detail |
-| `sonar-reasoning` | Mathematical reasoning, logic | 🐢 Moderate | Step-by-step |
-| `sonar-deep-research` | Comprehensive research with web context | 🐌 Slow | Maximum detail |
+# Save research to markdown
+pplx -m sonar-deep-research "AI trends 2025" -o research.md
 
----
+# Get JSON output for scripting
+pplx --json "capital of france" | jq .answer
 
-## 💻 Programmatic Use
+# View query history
+pplx --history
 
-### TypeScript API
-
-Use the toolkit directly in TypeScript when embedding into agents or services.
-
-```ts
-import { PerplexitySearchTool } from 'pplx-zero';
-
-// Initialize the search tool
-const tool = new PerplexitySearchTool();
-
-// Single search query
-const result = await tool.search({
-  query: "TypeScript best practices",
-  model: "sonar-pro",
-  maxResults: 5
-});
-
-console.log(result);
-```
-
-### Batch Processing
-
-```ts
-import { PerplexitySearchTool } from 'pplx-zero';
-
-const tool = new PerplexitySearchTool();
-
-// Batch search with custom configuration
-const batchResult = await tool.runBatch({
-  version: "1.0.0",
-  requests: [
-    {
-      op: "search",
-      args: {
-        query: "TypeScript best practices",
-        maxResults: 5,
-        model: "sonar-pro"
-      }
-    },
-    {
-      op: "search",
-      args: {
-        query: "React performance optimization",
-        maxResults: 3,
-        model: "sonar"
-      }
-    }
-  ],
-  options: {
-    concurrency: 3,
-    timeoutMs: 30000
-  }
-});
-
-console.log('Batch results:', batchResult);
-```
-
-### Advanced Usage with Error Handling
-
-```ts
-import { PerplexitySearchTool } from 'pplx-zero';
-
-async function searchWithRetry(query: string, maxRetries = 3) {
-  const tool = new PerplexitySearchTool();
-
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      const result = await tool.search({
-        query,
-        model: "sonar-pro",
-        maxResults: 5
-      });
-
-      return result;
-    } catch (error) {
-      if (attempt === maxRetries) {
-        throw new Error(`Search failed after ${maxRetries} attempts: ${error}`);
-      }
-
-      // Exponential backoff
-      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
-    }
-  }
-}
-
-// Usage
-searchWithRetry("latest AI trends")
-  .then(result => console.log(result))
-  .catch(error => console.error(error));
+# Search without saving to history
+pplx --no-history "sensitive query"
 ```
 
----
+## Models
 
-## 🛠️ Troubleshooting
-
-### Common Issues & Solutions
-
-#### API Key Problems
-```bash
-# Error: "API key not found"
-export PERPLEXITY_API_KEY="your-api-key"
-
-# Verify key is set
-echo $PERPLEXITY_API_KEY
-```
+| Model | Best For |
+|-------|----------|
+| `sonar` | Quick answers (default) |
+| `sonar-pro` | Complex questions |
+| `sonar-reasoning` | Step-by-step thinking |
+| `sonar-reasoning-pro` | Advanced reasoning |
+| `sonar-deep-research` | Comprehensive research |
 
-#### File Attachment Issues
-```bash
-# Error: "File too large" (files must be < 50MB)
-ls -lh your-file.pdf
+## Options
 
-# Supported formats check
-file your-document.pdf  # Should show PDF format
-```
+| Flag | Description |
+|------|-------------|
+| `-m, --model <name>` | Select model |
+| `-f, --file <path>` | Attach document (PDF, TXT, MD, etc.) |
+| `-i, --image <path>` | Attach image (PNG, JPG, WebP, etc.) |
+| `-o, --output <path>` | Save output to file (.md, .txt) |
+| `-c, --continue` | Continue from last query |
+| `--history` | Show query history |
+| `--no-history` | Don't save query to history |
+| `--json` | Output as JSON |
+| `-h, --help` | Show help |
 
-#### Network/Timeout Issues
-```bash
-# Increase timeout for complex queries
-pplx -t 60000 "complex research question"
+## History & Sessions
 
-# Check internet connectivity
-curl -I https://api.perplexity.ai
-```
+pplx-zero keeps a local history of your queries at `~/.pplx/history.jsonl`.
 
-#### Permission Issues
 ```bash
-# Permission denied during installation
-npm install -g pplx-zero --unsafe-perm
+# View recent queries
+pplx --history
 
-# Or use npx to avoid global installation
-npx pplx-zero "your query"
-```
+# Filter with grep
+pplx --history | grep "typescript"
 
-### Debug Mode
-
-```bash
-# Enable verbose output for debugging
-DEBUG=pplx:* pplx "your query"
+# Continue last conversation
+pplx -c "tell me more"
 
-# Check configuration
-pplx --version
-pplx update --check
+# Skip history for sensitive queries
+pplx --no-history "private question"
 ```
 
-### Performance Tips
-
-| Scenario | Recommended Settings |
-|----------|---------------------|
-| **Quick searches** | Default settings (sonar model) |
-| **Deep research** | `-m sonar-deep-research -t 60000` |
-| **Batch processing** | `-c 10 -t 45000` |
-| **File analysis** | `-m sonar-pro -t 60000` |
-| **Real-time queries** | `-m sonar -n 3` |
-
----
-
-## 📚 Additional Resources
-
-- **GitHub Repository**: [github.com/codewithkenzo/pplx-zero](https://github.com/codewithkenzo/pplx-zero)
-- **Bug Reports & Issues**: [GitHub Issues](https://github.com/codewithkenzo/pplx-zero/issues)
-- **Perplexity API Documentation**: [docs.perplexity.ai](https://docs.perplexity.ai)
-- **Model Comparison**: Detailed model comparison in the [AI Models](#ai-models) section above
+History auto-rotates at 1000 entries to keep the file small.
 
----
+## Exit Codes
 
-### Quick Reference Commands
-
-```bash
-# Show all available options
-pplx --help
-
-# Check for updates
-pplx update --check
-
-# Auto-update
-pplx update --auto
-
-# Show version
-pplx --version
-
-# Search history
-pplx history 10
-
-# Quick test
-pplx "test query"
-```
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | API error |
+| `2` | Configuration error |
 
----
+## License
 
-*Built with ❤️ using [Bun](https://bun.sh) and powered by [Perplexity AI](https://www.perplexity.ai)*
+MIT

package/bin/pplx.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+const { spawn, execSync } = require('child_process');
+const { join } = require('path');
+
+const hasBun = () => {
+  try {
+    execSync('bun --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+if (hasBun()) {
+  const scriptPath = join(__dirname, '..', 'src', 'index.ts');
+  const proc = spawn('bun', ['run', scriptPath, ...process.argv.slice(2)], {
+    stdio: 'inherit'
+  });
+  proc.on('exit', (code) => process.exit(code ?? 1));
+} else {
+  console.error('\x1b[31mError: pplx-zero requires Bun to be installed.\x1b[0m');
+  console.error('\nInstall Bun:');
+  console.error('  curl -fsSL https://bun.sh/install | bash');
+  console.error('\nOr via npm:');
+  console.error('  npm install -g bun');
+  process.exit(1);
+}