pplx-zero 1.1.7 → 2.0.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,154 +1,46 @@
-# PPLX‑Zero
+# pplx-zero
 
-Use the Perplexity API straight from the terminal — sub‑1s search API, ideal for coding agents and automation.
-Minimal setup, fast results, and practical flags for files, images, streaming, and batch workflows.
+Minimal Perplexity AI CLI - search from terminal.
 
-### What you can do
-- Ask, research, and stream answers instantly from the CLI with sensible defaults for rapid iteration.
-- Summarize documents and analyze images using a single command with optional model control.
-- Run batch jobs with concurrency and timeouts for agent pipelines and CI flows.
-
-### Install
-Choose one:
+## Installation
 
 ```bash
-# npm or bun (global)
-npm install -g pplx-zero
-pplx --version
+bun install -g pplx-zero
 ```
 
-
-or
+Or with npm:
 
 ```bash
-# AUR (Arch Linux)
-yay -S pplx-zero
-pplx --version
-```
-
-
-or
-
-```bash
-# Build from source
-# 1) clone the repository
-# 2) enter the folder
-# 3) build and link the CLI
-bun install && bun run build
-sudo ln -s "$(pwd)/dist/cli.js" /usr/local/bin/pplx
-pplx --version
+npm install -g pplx-zero
 ```
 
+## Setup
 
-### Configure
-Set your API key as an environment variable before running commands.
-
-Linux/macOS:
 ```bash
 export PERPLEXITY_API_KEY="your-api-key"
 ```
 
+## Usage
 
-Windows:
-```cmd
-setx PERPLEXITY_API_KEY "your-api-key"
-```
-
-
-Get your key from your Perplexity account and keep it private to your machine or CI secrets manager.
-
-### Quick examples
-Simple search (default model: sonar)
-```bash
-pplx "python type hints best practices"
-```
-
-
-Deep research or sonar-pro or reasoning when you need more steps or web context
-```bash
-pplx -m sonar-pro "React 19 Hooks"
-pplx -m sonar-deep-research "best Rust web frameworks 2025"
-pplx -m sonar-reasoning "prove this algorithm runs in O(n log n)"
-```
-
-
-Summarize a PDF report quickly
-```bash
-pplx -f report.pdf "summarize key findings and risks"
-```
-
-
-Understand an interface from a screenshot
 ```bash
-pplx -i screenshot.png "what is this UI and what are the next steps?"
+pplx "what is bun"
+pplx -m sonar-pro "explain quantum computing"
+pplx -m sonar-deep-research "comprehensive analysis of AI trends"
+pplx -f report.pdf "summarize this document"
+pplx -i screenshot.png "what's in this image"
+pplx --json "get structured response"
 ```
 
+## Options
 
-Combine a doc and an image in one prompt
-```bash
-pplx -f data.csv -i chart.png "spot anomalies and explain the chart"
-```
-
-
-Stream newline‑delimited JSON for agents or UNIX pipes
-```bash
-pplx -o jsonl "ai trends"
-```
-
-
-Batch from a JSON file (concurrency and timeout shown)
-```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 }
-}
-```
-
-
-```bash
-pplx -I queries.json -o jsonl -c 5 -t 30000
-```
-
-
-Fire‑and‑forget async with a webhook callback (agent workflows)
-```bash
-pplx --async --webhook http://localhost:3000/callback "long research task"
-```
-
-
-### Flags
-- -m, --model: sonar | sonar-pro | sonar-deep-research | sonar-reasoning (default: sonar) 
-- -f, --file: attach a document (PDF, DOC, DOCX, TXT, RTF, MD; up to ~50MB)
-- -i, --image: attach an image (PNG, JPEG, WebP, HEIF/HEIC, GIF; up to ~50MB)
-- -o, --format: json | jsonl (default: json) 
-- -I, --input: read batch requests from a JSON file
-- -c, --concurrency: max parallel requests, e.g., 5 (default: 5)
-- -t, --timeout: request timeout in ms, e.g., 30000 (default: 30000)
-- --async: process requests asynchronously
-- --webhook: URL receiving async notifications
-- -h, --help: show help
-- -v, --version: show version
-
-### Programmatic use (optional)
-Use the toolkit directly in TypeScript when embedding into agents or services.
-```ts
-import { PerplexitySearchTool } from 'pplx-zero';
-
-const tool = new PerplexitySearchTool();
-
-const result = await tool.runBatch({
-  version: "1.0.0",
-  requests: [{ op: "search", args: { query: "TypeScript best practices", maxResults: 5 } }]
-});
-
-console.log(result);
-```
+| Flag | Description |
+|------|-------------|
+| `-m, --model` | Model: sonar, sonar-pro, sonar-reasoning, sonar-reasoning-pro, sonar-deep-research |
+| `-f, --file` | Attach a file (PDF, TXT, etc.) |
+| `-i, --image` | Attach an image (PNG, JPG, etc.) |
+| `--json` | Output as JSON |
+| `-h, --help` | Show help |
 
+## License
 
-### Notes
-- Use pplx --help to see all available options and short flags without scanning long docs.
-- Keep output in jsonl for streaming pipelines and agent frameworks that consume line‑by‑line events.*Built with [Bun](https://bun.sh) and [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);
+}

package/package.json

@@ -1,80 +1,46 @@
 {
   "name": "pplx-zero",
-  "version": "1.1.7",
-  "description": "Fast Perplexity AI search CLI with multimodal support - minimal setup, maximal results",
+  "version": "2.0.0",
+  "description": "Minimal Perplexity AI CLI - search from terminal",
+  "author": "kenzo",
+  "license": "MIT",
   "type": "module",
-  "main": "dist/index.js",
+  "module": "src/index.ts",
   "bin": {
-    "pplx": "dist/index.js"
+    "pplx": "bin/pplx.js"
   },
   "scripts": {
-    "dev": "bun run src/cli/index.ts",
-    "dev:legacy": "bun run src/cli.ts",
-    "build": "rm -rf dist && bun build src/cli/index.ts --target node --outdir dist",
-    "build:legacy": "rm -rf dist && bun build src/cli.ts --target node --outdir dist",
-    "build:binary": "bun build --compile src/cli/index.ts --outfile=dist/pplx",
-    "build:binary:legacy": "bun build --compile src/cli.ts --outfile=dist/pplx-legacy",
-    "test": "bun test",
-    "test:watch": "bun test --watch",
-    "typecheck": "bun tsc --noEmit",
-    "lint": "bun run --bun eslint src/**/*.ts",
-    "lint:fix": "bun run --bun eslint src/**/*.ts --fix",
-    "clean": "rm -rf dist",
-    "dev:debug": "bun --inspect src/cli/index.ts",
-    "dev:debug:legacy": "bun --inspect src/cli.ts"
+    "build": "bun build src/index.ts --compile --outfile=pplx",
+    "dev": "bun run src/index.ts",
+    "test": "bun test"
   },
   "dependencies": {
-    "@perplexity-ai/perplexity_ai": "^0.11.0",
-    "abort-controller": "^3.0.0",
-    "commander": "^12.0.0",
-    "dotenv": "^16.3.1",
-    "zod": "^3.22.4"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "bun-types": "latest",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "eslint": "^8.0.0"
+    "@types/bun": "latest"
   },
-  "engines": {
-    "bun": ">=1.0.0"
+  "peerDependencies": {
+    "typescript": "^5"
   },
-  "keywords": [
-    "pplx-zero",
-    "perplexity",
-    "search",
-    "ai",
-    "cli",
-    "command-line",
-    "tool",
-    "typescript",
-    "bun",
-    "api",
-    "minimal",
-    "fast",
-    "productivity",
-    "zero-config",
-    "multimodal",
-    "attachments",
-    "images",
-    "documents",
-    "sonar",
-    "reasoning",
-    "research",
-    "async"
+  "files": [
+    "src",
+    "bin"
   ],
-  "author": "Kenzo",
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/codewithkenzo/pplx-zero.git"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "package.json"
+  "bugs": {
+    "url": "https://github.com/codewithkenzo/pplx-zero/issues"
+  },
+  "homepage": "https://github.com/codewithkenzo/pplx-zero#readme",
+  "keywords": [
+    "perplexity",
+    "ai",
+    "search",
+    "cli",
+    "terminal",
+    "bun"
   ]
-}
+}

package/src/api.test.ts

@@ -0,0 +1,21 @@
+import { test, expect, describe } from 'bun:test';
+import { MODELS, type Model } from './api';
+
+describe('MODELS', () => {
+  test('includes all expected models', () => {
+    expect(MODELS).toContain('sonar');
+    expect(MODELS).toContain('sonar-pro');
+    expect(MODELS).toContain('sonar-reasoning');
+    expect(MODELS).toContain('sonar-reasoning-pro');
+    expect(MODELS).toContain('sonar-deep-research');
+  });
+
+  test('has exactly 5 models', () => {
+    expect(MODELS).toHaveLength(5);
+  });
+
+  test('Model type matches MODELS array', () => {
+    const model: Model = MODELS[0]!;
+    expect(MODELS.includes(model)).toBe(true);
+  });
+});

package/src/api.ts

@@ -0,0 +1,116 @@
+import { getEnv } from './env';
+import type { FileAttachment } from './files';
+
+const API_URL = 'https://api.perplexity.ai/chat/completions';
+
+export const MODELS = ['sonar', 'sonar-pro', 'sonar-reasoning', 'sonar-reasoning-pro', 'sonar-deep-research'] as const;
+export type Model = (typeof MODELS)[number];
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  date?: string;
+}
+
+export interface StreamCallbacks {
+  onContent: (text: string) => void;
+  onDone: (citations: SearchResult[], usage: { prompt_tokens: number; completion_tokens: number }) => void;
+  onError: (error: Error) => void;
+}
+
+interface MessageContent {
+  type: 'text' | 'file_url';
+  text?: string;
+  file_url?: { url: string };
+  file_name?: string;
+}
+
+function buildMessages(query: string, file?: FileAttachment): { role: string; content: string | MessageContent[] }[] {
+  if (!file) {
+    return [{ role: 'user', content: query }];
+  }
+
+  const content: MessageContent[] = [
+    { type: 'text', text: query },
+    {
+      type: 'file_url',
+      file_url: { url: file.data },
+      file_name: file.filename,
+    },
+  ];
+
+  return [{ role: 'user', content }];
+}
+
+export async function search(
+  query: string,
+  model: Model,
+  callbacks: StreamCallbacks,
+  file?: FileAttachment
+): Promise<void> {
+  const body = JSON.stringify({
+    model,
+    messages: buildMessages(query, file),
+    stream: true,
+  });
+
+  const response = await fetch(API_URL, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${getEnv().PERPLEXITY_API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body,
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    callbacks.onError(new Error(`API error ${response.status}: ${text}`));
+    return;
+  }
+
+  if (!response.body) {
+    callbacks.onError(new Error('No response body'));
+    return;
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let citations: SearchResult[] = [];
+  let usage = { prompt_tokens: 0, completion_tokens: 0 };
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      if (!line.startsWith('data: ')) continue;
+      const data = line.slice(6).trim();
+      if (data === '[DONE]') continue;
+
+      try {
+        const parsed = JSON.parse(data);
+        const delta = parsed.choices?.[0]?.delta?.content;
+        if (delta) {
+          callbacks.onContent(delta);
+        }
+
+        if (parsed.search_results) {
+          citations = parsed.search_results;
+        }
+        if (parsed.usage) {
+          usage = parsed.usage;
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  callbacks.onDone(citations, usage);
+}

package/src/env.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+
+const c = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+} as const;
+
+const envSchema = z.object({
+  PERPLEXITY_API_KEY: z.string().min(1),
+});
+
+let _env: z.infer<typeof envSchema> | null = null;
+
+export function getEnv() {
+  if (_env) return _env;
+
+  const key = process.env.PERPLEXITY_API_KEY || process.env.PERPLEXITY_AI_API_KEY;
+  
+  if (!key) {
+    console.error(`
+${c.red}✗ Missing API Key${c.reset}
+
+Set your Perplexity API key:
+
+  ${c.cyan}export PERPLEXITY_API_KEY="pplx-..."${c.reset}
+
+${c.dim}Get one at: https://perplexity.ai/settings/api${c.reset}
+`);
+    process.exit(2);
+  }
+
+  _env = { PERPLEXITY_API_KEY: key };
+  return _env;
+}

package/src/files.test.ts

@@ -0,0 +1,71 @@
+import { test, expect, describe } from 'bun:test';
+import { encodeFile, toDataUrl, type FileAttachment } from './files';
+import { writeFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const TMP_DIR = '/tmp';
+
+describe('encodeFile', () => {
+  test('encodes text file correctly', async () => {
+    const testPath = join(TMP_DIR, 'test.txt');
+    await writeFile(testPath, 'hello world');
+    
+    const result = await encodeFile(testPath);
+    
+    expect(result.type).toBe('file');
+    expect(result.mimeType).toBe('text/plain');
+    expect(result.filename).toBe('test.txt');
+    expect(result.data).toBe(Buffer.from('hello world').toString('base64'));
+    
+    await unlink(testPath);
+  });
+
+  test('encodes PDF as file type', async () => {
+    const testPath = join(TMP_DIR, 'test.pdf');
+    await writeFile(testPath, '%PDF-1.4 test');
+    
+    const result = await encodeFile(testPath);
+    
+    expect(result.type).toBe('file');
+    expect(result.mimeType).toBe('application/pdf');
+    
+    await unlink(testPath);
+  });
+
+  test('encodes PNG as image type', async () => {
+    const testPath = join(TMP_DIR, 'test.png');
+    const pngHeader = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+    await writeFile(testPath, pngHeader);
+    
+    const result = await encodeFile(testPath);
+    
+    expect(result.type).toBe('image');
+    expect(result.mimeType).toBe('image/png');
+    
+    await unlink(testPath);
+  });
+
+  test('throws on unsupported file type', async () => {
+    const testPath = join(TMP_DIR, 'test.xyz');
+    await writeFile(testPath, 'test');
+    
+    await expect(encodeFile(testPath)).rejects.toThrow('Unsupported file type: .xyz');
+    
+    await unlink(testPath);
+  });
+});
+
+describe('toDataUrl', () => {
+  test('creates valid data URL', () => {
+    const attachment: FileAttachment = {
+      type: 'image',
+      data: 'aGVsbG8gd29ybGQ=',
+      mimeType: 'image/png',
+      filename: 'test.png',
+    };
+    
+    const result = toDataUrl(attachment);
+    
+    expect(result).toBe('data:image/png;base64,aGVsbG8gd29ybGQ=');
+  });
+});

package/src/files.ts

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+
+const MIME_TYPES: Record<string, string> = {
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+};
+
+export interface FileAttachment {
+  type: 'file' | 'image';
+  data: string;
+  mimeType: string;
+  filename: string;
+}
+
+export async function encodeFile(path: string): Promise<FileAttachment> {
+  const ext = extname(path).toLowerCase();
+  const mimeType = MIME_TYPES[ext];
+  
+  if (!mimeType) {
+    throw new Error(`Unsupported file type: ${ext}`);
+  }
+
+  const buffer = await readFile(path);
+  const data = buffer.toString('base64');
+  const isImage = mimeType.startsWith('image/');
+
+  return {
+    type: isImage ? 'image' : 'file',
+    data,
+    mimeType,
+    filename: path.split('/').pop() || 'file',
+  };
+}
+
+export function toDataUrl(attachment: FileAttachment): string {
+  return `data:${attachment.mimeType};base64,${attachment.data}`;
+}