@hasna/connectors 0.4.2 → 0.5.1

package/connectors/connect-perplexity/CLAUDE.md

@@ -0,0 +1,156 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+connect-perplexity is a TypeScript CLI and library for Perplexity AI's API. It provides chat completions with web search grounding, supporting multiple Sonar models with citation tracking.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+
+# Example commands
+bun run dev ask "What is AI?"
+bun run dev chat search "latest news"
+bun run dev models
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Use async/await for all async operations
+- Minimal dependencies: commander, chalk only
+- Type annotations required everywhere
+- Use interfaces for all API types
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # HTTP client for Perplexity API
+│   ├── example.ts    # ChatApi - chat completions
+│   └── index.ts      # Main Perplexity class
+├── cli/
+│   └── index.ts      # CLI commands (ask, search, chat, config, profile)
+├── types/
+│   └── index.ts      # Perplexity API types
+├── utils/
+│   ├── config.ts     # Multi-profile configuration
+│   └── output.ts     # CLI output formatting
+└── index.ts          # Library exports
+```
+
+## Key Types
+
+```typescript
+// Models available
+type PerplexityModel =
+  | 'sonar'
+  | 'sonar-pro'
+  | 'sonar-reasoning'
+  | 'sonar-reasoning-pro'
+  | 'sonar-deep-research';
+
+// Chat message structure
+interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+// Response includes citations
+interface ChatCompletionResponse {
+  choices: ChatCompletionChoice[];
+  usage: ChatCompletionUsage;
+  citations?: string[];      // Source URLs
+  search_results?: SearchResult[];
+}
+```
+
+## API Patterns
+
+### ChatApi Methods
+
+- `create(messages, options)` - Full chat completion with message history
+- `ask(question, options)` - Simple question/answer
+- `search(query, options)` - Web search with answer
+- `research(topic, options)` - Deep research (uses sonar-deep-research)
+- `reason(prompt, options)` - Reasoning task (uses sonar-reasoning-pro)
+
+### Options
+
+```typescript
+interface ChatOptions {
+  model?: PerplexityModel;
+  maxTokens?: number;
+  temperature?: number;
+  searchRecencyFilter?: 'month' | 'week' | 'day' | 'hour';
+  systemPrompt?: string;
+  // ...more
+}
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PERPLEXITY_API_KEY` | API key (overrides profile) |
+
+## Data Storage
+
+```
+~/.connect/connect-perplexity/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+Profile JSON:
+```json
+{
+  "apiKey": "pplx-xxx",
+  "defaultModel": "sonar-pro"
+}
+```
+
+## CLI Commands
+
+```bash
+# Quick commands
+connect-perplexity ask <question>
+connect-perplexity search <query>
+connect-perplexity models
+
+# Chat commands
+connect-perplexity chat ask <question> [-m model] [-t temp] [--recency hour|day|week|month]
+connect-perplexity chat search <query> [--recency]
+connect-perplexity chat research <topic>
+connect-perplexity chat reason <prompt>
+
+# Config
+connect-perplexity config set-key <key>
+connect-perplexity config set-model <model>
+connect-perplexity config show
+
+# Profiles
+connect-perplexity profile list|use|create|delete|show
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-perplexity/README.md

@@ -0,0 +1,184 @@
+# connect-perplexity
+
+A TypeScript CLI and library for interacting with Perplexity AI's API. Chat completions with web search grounding.
+
+## Features
+
+- Chat completions with web search grounding
+- Multiple Sonar models (sonar, sonar-pro, sonar-reasoning, sonar-deep-research)
+- Citations and source tracking
+- Multi-profile configuration (switch between different API keys)
+- Pretty and JSON output formats
+
+## Installation
+
+```bash
+# Install globally
+bun add -g @hasna/connect-perplexity
+
+# Or install locally
+bun add @hasna/connect-perplexity
+```
+
+## Setup
+
+### Get API Key
+
+1. Go to [Perplexity AI Settings](https://www.perplexity.ai/settings/api)
+2. Create an API key
+3. Set it in the CLI:
+
+```bash
+connect-perplexity config set-key pplx-xxxxx
+
+# Or use environment variable
+export PERPLEXITY_API_KEY=pplx-xxxxx
+```
+
+## CLI Usage
+
+### Quick Commands
+
+```bash
+# Ask a question
+connect-perplexity ask "What is quantum computing?"
+
+# Search the web
+connect-perplexity search "latest AI news 2026"
+
+# List available models
+connect-perplexity models
+```
+
+### Chat Commands
+
+```bash
+# Ask with specific model
+connect-perplexity chat ask "Explain neural networks" -m sonar-pro
+
+# Search with recency filter
+connect-perplexity chat search "Bitcoin price" --recency day
+
+# Deep research on a topic
+connect-perplexity chat research "Climate change solutions"
+
+# Reasoning task
+connect-perplexity chat reason "If all A are B, and all B are C, what can we conclude?"
+```
+
+### Profile Management
+
+```bash
+# Create profiles for different API keys
+connect-perplexity profile create work --api-key pplx-xxx --use
+connect-perplexity profile create personal --api-key pplx-yyy
+
+# Switch profiles
+connect-perplexity profile use work
+
+# Use profile for single command
+connect-perplexity -p personal ask "Hello"
+
+# List profiles
+connect-perplexity profile list
+```
+
+### Configuration
+
+```bash
+# Set API key
+connect-perplexity config set-key <key>
+
+# Set default model
+connect-perplexity config set-model sonar-pro
+
+# Show configuration
+connect-perplexity config show
+```
+
+## Library Usage
+
+```typescript
+import { Perplexity } from '@hasna/connect-perplexity';
+
+// Create client
+const perplexity = new Perplexity({ apiKey: 'pplx-xxx' });
+
+// Or from environment
+const perplexity = Perplexity.fromEnv(); // Uses PERPLEXITY_API_KEY
+
+// Ask a question
+const response = await perplexity.chat.ask('What is quantum computing?');
+console.log(response.choices[0].message.content);
+
+// With options
+const response = await perplexity.chat.ask('Explain AI', {
+  model: 'sonar-pro',
+  temperature: 0.7,
+  maxTokens: 1000,
+});
+
+// Search the web
+const search = await perplexity.chat.search('latest AI news');
+console.log(search.citations); // Array of source URLs
+
+// Deep research
+const research = await perplexity.chat.research('Climate change impacts');
+
+// Reasoning
+const reason = await perplexity.chat.reason('Solve this logic puzzle...');
+
+// Full chat with messages
+const chat = await perplexity.chat.create([
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'Hello!' },
+], { model: 'sonar' });
+```
+
+## Models
+
+| Model | Description |
+|-------|-------------|
+| `sonar` | Standard model for general queries |
+| `sonar-pro` | Enhanced model with better accuracy |
+| `sonar-reasoning` | Optimized for reasoning tasks |
+| `sonar-reasoning-pro` | Enhanced reasoning model |
+| `sonar-deep-research` | Comprehensive research model |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PERPLEXITY_API_KEY` | API key (overrides profile config) |
+
+## Data Storage
+
+Configuration stored in `~/.connect/connect-perplexity/`:
+
+```
+~/.connect/connect-perplexity/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## License
+
+MIT

package/connectors/connect-perplexity/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@hasna/connect-perplexity",
+  "version": "0.0.2",
+  "description": "Perplexity AI API connector CLI - Chat completions with web search grounding",
+  "type": "module",
+  "bin": {
+    "connect-perplexity": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "release": "bun run ./scripts/publish.ts",
+    "release:patch": "bun run ./scripts/publish.ts patch",
+    "release:minor": "bun run ./scripts/publish.ts minor",
+    "release:major": "bun run ./scripts/publish.ts major",
+    "release:dry": "bun run ./scripts/publish.ts --dry-run"
+  },
+  "keywords": [
+    "perplexity",
+    "ai",
+    "llm",
+    "chat",
+    "search",
+    "sonar",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/open-connectors.git"
+  }
+}

package/connectors/connect-perplexity/scripts/publish.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+/**
+ * Auto-versioning publish script
+ * - Fetches current npm version
+ * - Auto-bumps patch version if local version <= npm version
+ * - Creates git tag
+ * - Publishes to npm
+ */
+
+import { $ } from 'bun';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+interface PackageJson {
+  name: string;
+  version: string;
+  [key: string]: unknown;
+}
+
+type BumpType = 'patch' | 'minor' | 'major';
+
+function parseVersion(version: string): { major: number; minor: number; patch: number } {
+  const [major, minor, patch] = version.split('.').map(Number);
+  return { major, minor, patch };
+}
+
+function bumpVersion(version: string, type: BumpType = 'patch'): string {
+  const { major, minor, patch } = parseVersion(version);
+
+  switch (type) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+    default:
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+
+function compareVersions(a: string, b: string): number {
+  const vA = parseVersion(a);
+  const vB = parseVersion(b);
+
+  if (vA.major !== vB.major) return vA.major - vB.major;
+  if (vA.minor !== vB.minor) return vA.minor - vB.minor;
+  return vA.patch - vB.patch;
+}
+
+async function getNpmVersion(packageName: string): Promise<string | null> {
+  try {
+    const result = await $`npm view ${packageName} version 2>/dev/null`.text();
+    return result.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function hasUncommittedChanges(): Promise<boolean> {
+  try {
+    const result = await $`git status --porcelain`.text();
+    return result.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function isGitRepo(): Promise<boolean> {
+  try {
+    await $`git rev-parse --git-dir 2>/dev/null`.text();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createGitTag(version: string, packageName: string): Promise<boolean> {
+  const tagName = `${packageName}@${version}`;
+
+  try {
+    // Check if tag already exists
+    const existingTags = await $`git tag -l ${tagName}`.text();
+    if (existingTags.trim()) {
+      console.log(`⚠️  Tag ${tagName} already exists, skipping tag creation`);
+      return true;
+    }
+
+    await $`git tag -a ${tagName} -m "Release ${tagName}"`;
+    console.log(`✅ Created git tag: ${tagName}`);
+    return true;
+  } catch (error) {
+    console.error(`❌ Failed to create git tag: ${error}`);
+    return false;
+  }
+}
+
+async function commitVersionBump(version: string, packageName: string): Promise<boolean> {
+  try {
+    await $`git add package.json`;
+    await $`git commit -m "chore(${packageName}): bump version to ${version}"`;
+    console.log(`✅ Committed version bump`);
+    return true;
+  } catch (error) {
+    console.error(`❌ Failed to commit: ${error}`);
+    return false;
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const bumpType = (args.find(a => ['patch', 'minor', 'major'].includes(a)) || 'patch') as BumpType;
+  const skipGit = args.includes('--skip-git');
+  const dryRun = args.includes('--dry-run');
+  const force = args.includes('--force');
+
+  // Read package.json
+  const pkgPath = join(process.cwd(), 'package.json');
+  const pkg: PackageJson = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+  console.log(`\n📦 Publishing ${pkg.name}\n`);
+
+  // Get current npm version
+  const npmVersion = await getNpmVersion(pkg.name);
+  let newVersion = pkg.version;
+
+  if (npmVersion) {
+    console.log(`📌 Current npm version: ${npmVersion}`);
+    console.log(`📌 Local version: ${pkg.version}`);
+
+    // Check if we need to bump
+    if (compareVersions(pkg.version, npmVersion) <= 0) {
+      newVersion = bumpVersion(npmVersion, bumpType);
+      console.log(`🔄 Auto-bumping to: ${newVersion}`);
+    } else {
+      console.log(`✅ Local version is ahead, using: ${pkg.version}`);
+    }
+  } else {
+    console.log(`📌 Package not yet published to npm`);
+    console.log(`📌 Using local version: ${pkg.version}`);
+  }
+
+  // Update package.json if version changed
+  if (newVersion !== pkg.version) {
+    if (dryRun) {
+      console.log(`\n🧪 DRY RUN: Would update version to ${newVersion}`);
+    } else {
+      pkg.version = newVersion;
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      console.log(`✅ Updated package.json to version ${newVersion}`);
+    }
+  }
+
+  // Git operations
+  const isGit = await isGitRepo();
+
+  if (isGit && !skipGit) {
+    const hasChanges = await hasUncommittedChanges();
+
+    if (hasChanges && newVersion !== pkg.version) {
+      if (dryRun) {
+        console.log(`🧪 DRY RUN: Would commit version bump`);
+      } else {
+        await commitVersionBump(newVersion, pkg.name.replace('@hasna/', ''));
+      }
+    }
+
+    if (dryRun) {
+      console.log(`🧪 DRY RUN: Would create tag ${pkg.name}@${newVersion}`);
+    } else {
+      await createGitTag(newVersion, pkg.name.replace('@hasna/', ''));
+    }
+  }
+
+  // Build
+  console.log(`\n🔨 Building...`);
+  if (!dryRun) {
+    await $`bun run build`;
+  } else {
+    console.log(`🧪 DRY RUN: Would run build`);
+  }
+
+  // Publish
+  console.log(`\n🚀 Publishing to npm...`);
+  if (dryRun) {
+    console.log(`🧪 DRY RUN: Would publish ${pkg.name}@${newVersion}`);
+  } else {
+    try {
+      await $`npm publish`;
+      console.log(`\n✅ Successfully published ${pkg.name}@${newVersion}`);
+    } catch (error) {
+      console.error(`\n❌ Publish failed: ${error}`);
+      process.exit(1);
+    }
+  }
+
+  // Push tags
+  if (isGit && !skipGit && !dryRun) {
+    console.log(`\n📤 Pushing tags to remote...`);
+    try {
+      await $`git push --tags`;
+      console.log(`✅ Pushed tags to remote`);
+    } catch {
+      console.log(`⚠️  Could not push tags (no remote or not configured)`);
+    }
+  }
+
+  console.log(`\n✨ Done!\n`);
+}
+
+main().catch(console.error);