@oh-my-pi/perplexity 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @oh-my-pi/perplexity
+
+Perplexity AI search tools for [pi](https://github.com/badlogic/pi-mono).
+
+## Installation
+
+```bash
+omp install @oh-my-pi/perplexity
+```
+
+## Configuration
+
+Set your Perplexity API key:
+
+```bash
+# Option 1: Environment variable
+export PERPLEXITY_API_KEY=pplx-xxx
+
+# Option 2: Add to ~/.env
+echo "PERPLEXITY_API_KEY=pplx-xxx" >> ~/.env
+```
+
+Get your API key from [Perplexity API Settings](https://www.perplexity.ai/settings/api).
+
+## Tools
+
+### `perplexity_search`
+
+Fast web search using Perplexity Sonar. Returns real-time answers with citations.
+
+**Best for:** Quick facts, current events, straightforward questions
+
+**Parameters:**
+
+- `query` (required): The search query or question
+- `search_recency_filter`: Filter by recency (`day`, `week`, `month`, `year`)
+- `search_domain_filter`: Limit to specific domains (e.g., `["nature.com", "arxiv.org"]`)
+- `search_context_size`: Amount of search context (`low`, `medium`, `high`)
+- `return_related_questions`: Include follow-up question suggestions
+
+### `perplexity_search_pro`
+
+Advanced web search using Perplexity Sonar Pro. Returns comprehensive answers with 2x more sources.
+
+**Best for:** Complex research, multi-step analysis, detailed comparisons
+
+**Additional parameters:**
+
+- `system_prompt`: Guide the response style and focus
+
+## Pricing
+
+| Model     | Input       | Output       | Per 1K Requests |
+| --------- | ----------- | ------------ | --------------- |
+| Sonar     | $1/M tokens | $1/M tokens  | $5-12           |
+| Sonar Pro | $3/M tokens | $15/M tokens | $6-14           |
+
+Request cost varies by `search_context_size` (low/medium/high).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@oh-my-pi/perplexity",
+  "version": "0.1.0",
+  "description": "Perplexity AI search tools for pi",
+  "keywords": [
+    "omp-plugin",
+    "perplexity",
+    "web-search",
+    "ai-search",
+    "sonar"
+  ],
+  "author": "Can Bölük <me@can.ac>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/can1357/oh-my-pi.git",
+    "directory": "plugins/perplexity"
+  },
+  "omp": {
+    "install": [
+      {
+        "src": "tools/perplexity/runtime.json",
+        "dest": "agent/tools/perplexity/runtime.json",
+        "copy": true
+      },
+      {
+        "src": "tools/perplexity/index.ts",
+        "dest": "agent/tools/perplexity/index.ts"
+      },
+      {
+        "src": "tools/perplexity/shared.ts",
+        "dest": "agent/tools/perplexity/shared.ts"
+      },
+      {
+        "src": "tools/perplexity/search.ts",
+        "dest": "agent/tools/perplexity/search.ts"
+      }
+    ],
+    "variables": {
+      "apiKey": {
+        "type": "string",
+        "env": "PERPLEXITY_API_KEY",
+        "description": "Perplexity API key for authentication",
+        "required": true
+      }
+    },
+    "features": {
+      "search": {
+        "description": "Web search with Sonar models (fast and pro)",
+        "default": true
+      }
+    }
+  },
+  "files": [
+    "tools"
+  ]
+}

package/tools/perplexity/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Perplexity Tools - Dynamic loader for feature modules
+ *
+ * Reads runtime.json to determine which features are enabled,
+ * then loads and initializes those feature modules.
+ *
+ * Available features:
+ *   - search: Web search with Sonar models (fast and pro)
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import type {
+  CustomAgentTool,
+  CustomToolFactory,
+  ToolAPI,
+} from "@mariozechner/pi-coding-agent";
+import runtime from "./runtime.json";
+
+// Map feature names to their module imports
+const FEATURE_LOADERS: Record<
+  string,
+  () => Promise<{ default: CustomToolFactory }>
+> = {
+  search: () => import("./search"),
+};
+
+/**
+ * Factory function that loads enabled features from runtime.json
+ */
+const factory: CustomToolFactory = async (
+  toolApi: ToolAPI,
+): Promise<CustomAgentTool<TSchema, unknown>[] | null> => {
+  const allTools: CustomAgentTool<TSchema, unknown>[] = [];
+  const enabledFeatures = runtime.features ?? [];
+
+  for (const feature of enabledFeatures) {
+    const loader = FEATURE_LOADERS[feature];
+    if (!loader) {
+      console.error(`Unknown perplexity feature: "${feature}"`);
+      continue;
+    }
+
+    try {
+      const module = await loader();
+      const featureFactory = module.default;
+
+      if (typeof featureFactory === "function") {
+        const result = await featureFactory(toolApi);
+        // Handle both single tool and array of tools
+        if (result) {
+          const tools = Array.isArray(result) ? result : [result];
+          for (const tool of tools) {
+            if (tool && typeof tool === "object" && "name" in tool) {
+              allTools.push(tool);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Failed to load perplexity feature "${feature}":`, error);
+    }
+  }
+
+  return allTools.length > 0 ? allTools : null;
+};
+
+export default factory;

package/tools/perplexity/runtime.json

@@ -0,0 +1,4 @@
+{
+  "features": ["search"],
+  "options": {}
+}

package/tools/perplexity/search.ts

@@ -0,0 +1,196 @@
+/**
+ * Perplexity Search Tools - Web search with Sonar models
+ *
+ * Tools:
+ *   - perplexity_search: Fast web search with Sonar (quick answers)
+ *   - perplexity_search_pro: Advanced search with Sonar Pro (deeper research)
+ */
+
+import { Type, type TSchema } from "@sinclair/typebox";
+import type {
+  CustomAgentTool,
+  CustomToolFactory,
+  ToolAPI,
+} from "@mariozechner/pi-coding-agent";
+import {
+  callPerplexity,
+  findApiKey,
+  formatResponse,
+  type PerplexityRequest,
+} from "./shared";
+
+const RecencyFilter = Type.Optional(
+  Type.Union(
+    [
+      Type.Literal("day"),
+      Type.Literal("week"),
+      Type.Literal("month"),
+      Type.Literal("year"),
+    ],
+    { description: "Filter results by recency" },
+  ),
+);
+
+const SearchContextSize = Type.Optional(
+  Type.Union(
+    [
+      Type.Literal("low"),
+      Type.Literal("medium"),
+      Type.Literal("high"),
+    ],
+    { description: "Amount of search context to use (affects cost). Default: low" },
+  ),
+);
+
+// Schema for fast search
+const FastSearchSchema = Type.Object({
+  query: Type.String({
+    description: "The search query or question to answer",
+  }),
+  search_recency_filter: RecencyFilter,
+  search_domain_filter: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Limit search to specific domains (e.g., ['nature.com', 'arxiv.org']). Prefix with '-' to exclude.",
+    }),
+  ),
+  search_context_size: SearchContextSize,
+  return_related_questions: Type.Optional(
+    Type.Boolean({
+      description: "Include related follow-up questions in response",
+    }),
+  ),
+});
+
+// Schema for pro search
+const ProSearchSchema = Type.Object({
+  query: Type.String({
+    description: "The search query or research question",
+  }),
+  system_prompt: Type.Optional(
+    Type.String({
+      description: "System prompt to guide the response style and focus",
+    }),
+  ),
+  search_recency_filter: RecencyFilter,
+  search_domain_filter: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Limit search to specific domains (e.g., ['nature.com', 'arxiv.org']). Prefix with '-' to exclude.",
+    }),
+  ),
+  search_context_size: SearchContextSize,
+  return_related_questions: Type.Optional(
+    Type.Boolean({
+      description: "Include related follow-up questions in response",
+    }),
+  ),
+});
+
+type FastSearchParams = {
+  query: string;
+  search_recency_filter?: "day" | "week" | "month" | "year";
+  search_domain_filter?: string[];
+  search_context_size?: "low" | "medium" | "high";
+  return_related_questions?: boolean;
+};
+
+type ProSearchParams = FastSearchParams & {
+  system_prompt?: string;
+};
+
+function createSearchTool(
+  apiKey: string,
+  name: string,
+  description: string,
+  model: string,
+  schema: TSchema,
+): CustomAgentTool<TSchema, unknown> {
+  return {
+    name,
+    label: name.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+    description,
+    parameters: schema,
+    async execute(_toolCallId, params) {
+      try {
+        const p = (params ?? {}) as ProSearchParams;
+
+        const request: PerplexityRequest = {
+          model,
+          messages: [],
+        };
+
+        // Add system prompt if provided
+        if (p.system_prompt) {
+          request.messages.push({
+            role: "system",
+            content: p.system_prompt,
+          });
+        }
+
+        request.messages.push({
+          role: "user",
+          content: p.query,
+        });
+
+        // Add optional parameters
+        if (p.search_recency_filter) {
+          request.search_recency_filter = p.search_recency_filter;
+        }
+        if (p.search_domain_filter && p.search_domain_filter.length > 0) {
+          request.search_domain_filter = p.search_domain_filter;
+        }
+        if (p.search_context_size) {
+          request.search_context_size = p.search_context_size;
+        }
+        if (p.return_related_questions) {
+          request.return_related_questions = p.return_related_questions;
+        }
+
+        const response = await callPerplexity(apiKey, request);
+        const text = formatResponse(response);
+
+        return {
+          content: [{ type: "text" as const, text }],
+          details: {
+            model: response.model,
+            usage: response.usage,
+            citations: response.citations,
+            search_results: response.search_results,
+            related_questions: response.related_questions,
+          },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text" as const, text: `Error: ${message}` }],
+          details: { error: message },
+        };
+      }
+    },
+  };
+}
+
+const factory: CustomToolFactory = async (
+  _toolApi: ToolAPI,
+): Promise<CustomAgentTool<TSchema, unknown>[] | null> => {
+  const apiKey = findApiKey();
+  if (!apiKey) return null;
+
+  return [
+    createSearchTool(
+      apiKey,
+      "perplexity_search",
+      "Fast web search using Perplexity Sonar. Returns real-time answers with citations. Best for quick facts, current events, and straightforward questions. Cost-effective for high-volume queries.",
+      "sonar",
+      FastSearchSchema,
+    ),
+    createSearchTool(
+      apiKey,
+      "perplexity_search_pro",
+      "Advanced web search using Perplexity Sonar Pro. Returns comprehensive, well-researched answers with 2x more sources. Best for complex research questions, multi-step analysis, and detailed comparisons. Higher cost but deeper results.",
+      "sonar-pro",
+      ProSearchSchema,
+    ),
+  ];
+};
+
+export default factory;

package/tools/perplexity/shared.ts

@@ -0,0 +1,166 @@
+/**
+ * Shared utilities for Perplexity API
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
+
+export interface PerplexityMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface PerplexityRequest {
+  model: string;
+  messages: PerplexityMessage[];
+  temperature?: number;
+  max_tokens?: number;
+  search_domain_filter?: string[];
+  search_recency_filter?: "day" | "week" | "month" | "year";
+  return_images?: boolean;
+  return_related_questions?: boolean;
+  search_context_size?: "low" | "medium" | "high";
+}
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  date?: string;
+  snippet?: string;
+}
+
+export interface PerplexityResponse {
+  id: string;
+  model: string;
+  created: number;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    search_context_size?: string;
+  };
+  citations?: string[];
+  search_results?: SearchResult[];
+  related_questions?: string[];
+  choices: Array<{
+    index: number;
+    finish_reason: string;
+    message: {
+      role: string;
+      content: string;
+    };
+  }>;
+}
+
+/**
+ * Parse a .env file and return key-value pairs
+ */
+function parseEnvFile(filePath: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!fs.existsSync(filePath)) return result;
+
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+
+      const eqIndex = trimmed.indexOf("=");
+      if (eqIndex === -1) continue;
+
+      const key = trimmed.slice(0, eqIndex).trim();
+      let value = trimmed.slice(eqIndex + 1).trim();
+
+      // Remove surrounding quotes
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+
+      result[key] = value;
+    }
+  } catch {
+    // Ignore read errors
+  }
+
+  return result;
+}
+
+/**
+ * Find PERPLEXITY_API_KEY from environment or .env files
+ */
+export function findApiKey(): string | null {
+  // 1. Check environment variable
+  if (process.env.PERPLEXITY_API_KEY) {
+    return process.env.PERPLEXITY_API_KEY;
+  }
+
+  // 2. Check .env in current directory
+  const localEnv = parseEnvFile(path.join(process.cwd(), ".env"));
+  if (localEnv.PERPLEXITY_API_KEY) {
+    return localEnv.PERPLEXITY_API_KEY;
+  }
+
+  // 3. Check ~/.env
+  const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
+  if (homeEnv.PERPLEXITY_API_KEY) {
+    return homeEnv.PERPLEXITY_API_KEY;
+  }
+
+  return null;
+}
+
+/**
+ * Call Perplexity API
+ */
+export async function callPerplexity(
+  apiKey: string,
+  request: PerplexityRequest,
+): Promise<PerplexityResponse> {
+  const response = await fetch(PERPLEXITY_API_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(request),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Perplexity API error (${response.status}): ${errorText}`);
+  }
+
+  return response.json() as Promise<PerplexityResponse>;
+}
+
+/**
+ * Format Perplexity response for display
+ */
+export function formatResponse(response: PerplexityResponse): string {
+  const content = response.choices[0]?.message?.content ?? "";
+  const parts: string[] = [content];
+
+  // Add citations if available
+  if (response.citations && response.citations.length > 0) {
+    parts.push("\n\n## Sources");
+    for (const [i, url] of response.citations.entries()) {
+      parts.push(`[${i + 1}] ${url}`);
+    }
+  }
+
+  // Add related questions if available
+  if (response.related_questions && response.related_questions.length > 0) {
+    parts.push("\n\n## Related Questions");
+    for (const question of response.related_questions) {
+      parts.push(`- ${question}`);
+    }
+  }
+
+  return parts.join("\n");
+}