@pi-unipi/web-api 0.1.0

package/src/settings.ts

@@ -0,0 +1,263 @@
+/**
+ * @unipi/web-api — Settings storage
+ *
+ * Manages API keys and provider configuration.
+ * Persists to ~/.unipi/config/web-api/auth.json and config.json
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+/** Auth storage structure (API keys) */
+export interface WebApiAuth {
+  [providerId: string]: string;
+}
+
+/** Provider configuration */
+export interface ProviderSettings {
+  enabled: boolean;
+  apiKey?: string;
+  [key: string]: unknown;
+}
+
+/** Cache configuration */
+export interface CacheSettings {
+  enabled: boolean;
+  ttlMs: number;
+}
+
+/** Config storage structure */
+export interface WebApiConfig {
+  providers: Record<string, ProviderSettings>;
+  cache: CacheSettings;
+}
+
+/** Default configuration */
+const DEFAULT_CONFIG: WebApiConfig = {
+  providers: {
+    duckduckgo: { enabled: true },
+    "jina-search": { enabled: true },
+    "jina-reader": { enabled: true },
+    serpapi: { enabled: false },
+    tavily: { enabled: false },
+    firecrawl: { enabled: false },
+    perplexity: { enabled: false },
+    "llm-summarize": { enabled: true },
+  },
+  cache: {
+    enabled: true,
+    ttlMs: 3600000, // 1 hour
+  },
+};
+
+/**
+ * Get the config directory path.
+ */
+function getConfigDir(): string {
+  const homeDir = os.homedir();
+  return path.join(homeDir, ".unipi", "config", "web-api");
+}
+
+/**
+ * Get the auth file path.
+ */
+function getAuthPath(): string {
+  return path.join(getConfigDir(), "auth.json");
+}
+
+/**
+ * Get the config file path.
+ */
+function getConfigPath(): string {
+  return path.join(getConfigDir(), "config.json");
+}
+
+/**
+ * Ensure config directory exists.
+ */
+function ensureConfigDir(): void {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Load API keys from auth.json.
+ * @returns API keys object
+ */
+export function loadAuth(): WebApiAuth {
+  try {
+    const authPath = getAuthPath();
+    if (fs.existsSync(authPath)) {
+      const content = fs.readFileSync(authPath, "utf-8");
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    console.error("[web-api] Failed to load auth:", error);
+  }
+  return {};
+}
+
+/**
+ * Save API keys to auth.json.
+ * @param auth - API keys object
+ */
+export function saveAuth(auth: WebApiAuth): void {
+  ensureConfigDir();
+  const authPath = getAuthPath();
+  fs.writeFileSync(authPath, JSON.stringify(auth, null, 2), "utf-8");
+}
+
+/**
+ * Load configuration from config.json.
+ * @returns Configuration object
+ */
+export function loadConfig(): WebApiConfig {
+  try {
+    const configPath = getConfigPath();
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, "utf-8");
+      const config = JSON.parse(content) as Partial<WebApiConfig>;
+      return {
+        ...DEFAULT_CONFIG,
+        ...config,
+        providers: {
+          ...DEFAULT_CONFIG.providers,
+          ...config.providers,
+        },
+        cache: {
+          ...DEFAULT_CONFIG.cache,
+          ...config.cache,
+        },
+      };
+    }
+  } catch (error) {
+    console.error("[web-api] Failed to load config:", error);
+  }
+  return DEFAULT_CONFIG;
+}
+
+/**
+ * Save configuration to config.json.
+ * @param config - Configuration object
+ */
+export function saveConfig(config: WebApiConfig): void {
+  ensureConfigDir();
+  const configPath = getConfigPath();
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+
+/**
+ * Get API key for a provider.
+ * @param providerId - Provider ID
+ * @returns API key or undefined
+ */
+export function getApiKey(providerId: string): string | undefined {
+  const auth = loadAuth();
+  return auth[providerId];
+}
+
+/**
+ * Set API key for a provider.
+ * @param providerId - Provider ID
+ * @param apiKey - API key
+ */
+export function setApiKey(providerId: string, apiKey: string): void {
+  const auth = loadAuth();
+  auth[providerId] = apiKey;
+  saveAuth(auth);
+}
+
+/**
+ * Remove API key for a provider.
+ * @param providerId - Provider ID
+ */
+export function removeApiKey(providerId: string): void {
+  const auth = loadAuth();
+  delete auth[providerId];
+  saveAuth(auth);
+}
+
+/**
+ * Check if a provider is enabled.
+ * @param providerId - Provider ID
+ * @returns true if enabled
+ */
+export function isProviderEnabled(providerId: string): boolean {
+  const config = loadConfig();
+  return config.providers[providerId]?.enabled !== false;
+}
+
+/**
+ * Enable or disable a provider.
+ * @param providerId - Provider ID
+ * @param enabled - Whether to enable
+ */
+export function setProviderEnabled(providerId: string, enabled: boolean): void {
+  const config = loadConfig();
+  if (!config.providers[providerId]) {
+    config.providers[providerId] = { enabled };
+  } else {
+    config.providers[providerId].enabled = enabled;
+  }
+  saveConfig(config);
+}
+
+/**
+ * Get cache settings.
+ * @returns Cache configuration
+ */
+export function getCacheSettings(): CacheSettings {
+  const config = loadConfig();
+  return config.cache;
+}
+
+/**
+ * Update cache settings.
+ * @param cache - New cache settings
+ */
+export function updateCacheSettings(cache: Partial<CacheSettings>): void {
+  const config = loadConfig();
+  config.cache = {
+    ...config.cache,
+    ...cache,
+  };
+  saveConfig(config);
+}
+
+/**
+ * Validate API key format (basic validation).
+ * @param providerId - Provider ID
+ * @param apiKey - API key to validate
+ * @returns true if format looks valid
+ */
+export function validateApiKeyFormat(providerId: string, apiKey: string): boolean {
+  if (!apiKey || apiKey.trim().length === 0) {
+    return false;
+  }
+
+  // Provider-specific format checks
+  switch (providerId) {
+    case "serpapi":
+      // SerpAPI keys are typically 64 characters
+      return apiKey.length >= 32;
+    case "tavily":
+      // Tavily keys start with "tvly-"
+      return apiKey.startsWith("tvly-") && apiKey.length >= 10;
+    case "firecrawl":
+      // Firecrawl keys are typically longer
+      return apiKey.length >= 20;
+    case "perplexity":
+      // Perplexity keys are typically longer
+      return apiKey.length >= 20;
+    case "jina-search":
+    case "jina-reader":
+      // Jina keys are typically longer
+      return apiKey.length >= 10;
+    default:
+      // Generic validation
+      return apiKey.length >= 8;
+  }
+}

package/src/tools.ts

@@ -0,0 +1,329 @@
+/**
+ * @unipi/web-api — Agent tools registration
+ *
+ * Registers web-search, web-read, and web-llm-summarize tools.
+ * Implements smart provider selection based on ranking.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registry } from "./providers/registry.js";
+import type {
+  WebProvider,
+  WebCapability,
+  SearchResult,
+  ReadResult,
+  SummarizeResult,
+} from "./providers/base.js";
+import {
+  getApiKey,
+  isProviderEnabled,
+  loadConfig,
+} from "./settings.js";
+
+/** Tool names */
+export const WEB_TOOLS = {
+  SEARCH: "web_search",
+  READ: "web_read",
+  SUMMARIZE: "web_llm_summarize",
+} as const;
+
+/**
+ * Get available providers for a capability.
+ * Filters by enabled status and API key availability.
+ */
+function getAvailableProviders(capability: WebCapability): WebProvider[] {
+  const config = loadConfig();
+  const ranked = registry.getRankedProviders(capability);
+
+  return ranked.filter((provider) => {
+    // Check if provider is enabled
+    if (!isProviderEnabled(provider.id)) {
+      return false;
+    }
+
+    // Check if provider requires API key
+    if (provider.requiresApiKey) {
+      const apiKey = getApiKey(provider.id);
+      if (!apiKey) {
+        return false;
+      }
+    }
+
+    return true;
+  });
+}
+
+/**
+ * Select provider for a capability.
+ * If sourceRank is specified, use that rank.
+ * Otherwise, use the lowest-ranked available provider.
+ */
+function selectProvider(
+  capability: WebCapability,
+  sourceRank?: number
+): WebProvider {
+  const available = getAvailableProviders(capability);
+
+  if (available.length === 0) {
+    const allProviders = registry.getProvidersForCapability(capability);
+    const providerNames = allProviders.map((p) => p.name).join(", ");
+    throw new Error(
+      `No ${capability} provider available.\n` +
+      `Configure providers via /unipi:web-settings\n` +
+      `Available providers: ${providerNames}`
+    );
+  }
+
+  if (sourceRank !== undefined) {
+    // Find provider with matching rank
+    const provider = available.find((p) => p.ranking[capability] === sourceRank);
+    if (!provider) {
+      const availableRanks = available.map((p) => p.ranking[capability]).join(", ");
+      throw new Error(
+        `No provider at rank ${sourceRank} for ${capability}.\n` +
+        `Available ranks: ${availableRanks}`
+      );
+    }
+    return provider;
+  }
+
+  // Return lowest-ranked (cheapest/simplest) available provider
+  return available[0];
+}
+
+/**
+ * Execute web search.
+ */
+async function executeSearch(
+  query: string,
+  sourceRank?: number
+): Promise<SearchResult[]> {
+  const provider = selectProvider("search", sourceRank);
+
+  if (!provider.search) {
+    throw new Error(`Provider "${provider.name}" does not support search`);
+  }
+
+  const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
+  const config = { enabled: true, apiKey };
+
+  return provider.search(query, config);
+}
+
+/**
+ * Execute web read.
+ */
+async function executeRead(
+  url: string,
+  sourceRank?: number
+): Promise<ReadResult> {
+  const provider = selectProvider("read", sourceRank);
+
+  if (!provider.read) {
+    throw new Error(`Provider "${provider.name}" does not support read`);
+  }
+
+  const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
+  const config = { enabled: true, apiKey };
+
+  return provider.read(url, config);
+}
+
+/**
+ * Execute web summarize.
+ */
+async function executeSummarize(
+  url: string,
+  prompt?: string,
+  sourceRank?: number
+): Promise<SummarizeResult> {
+  const provider = selectProvider("summarize", sourceRank);
+
+  if (!provider.summarize) {
+    throw new Error(`Provider "${provider.name}" does not support summarize`);
+  }
+
+  const apiKey = provider.requiresApiKey ? getApiKey(provider.id) : undefined;
+  const config = { enabled: true, apiKey };
+
+  return provider.summarize(url, prompt, config);
+}
+
+/**
+ * Register web tools with pi.
+ */
+export function registerWebTools(pi: ExtensionAPI): void {
+  // --- web_search tool ---
+  pi.registerTool({
+    name: WEB_TOOLS.SEARCH,
+    label: "Web Search",
+    description:
+      "Search the web for information using various providers. " +
+      "Lower source = simpler/cheaper providers (DuckDuckGo, Jina Search). " +
+      "Higher source = more capable providers (SerpAPI, Tavily, Perplexity).",
+    promptSnippet: "Search the web for information.",
+    promptGuidelines: [
+      "Use web_search to find information on the web.",
+      "Omit source for auto-selection (cheapest available).",
+      "Specify source number for specific provider (1=DuckDuckGo, 2=Jina, 3=SerpAPI, 4=Tavily, 5=Perplexity).",
+      "Quick facts: source 1-2. Research: source 3-5.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query string" }),
+      source: Type.Optional(
+        Type.Number({
+          description:
+            "Provider selection (1=DuckDuckGo, 2=Jina Search, 3=SerpAPI, 4=Tavily, 5=Perplexity). " +
+            "Omit for auto-selection.",
+          minimum: 1,
+          maximum: 5,
+        })
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      try {
+        const results = await executeSearch(params.query, params.source);
+
+        if (results.length === 0) {
+          return {
+            content: [{ type: "text", text: "No results found." }],
+          };
+        }
+
+        const formatted = results
+          .map(
+            (r, i) =>
+              `${i + 1}. **${r.title}**\n   ${r.url}\n   ${r.snippet}`
+          )
+          .join("\n\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${results.length} results:\n\n${formatted}`,
+            },
+          ],
+        };
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Search failed: ${message}` }],
+          isError: true,
+        };
+      }
+    },
+  });
+
+  // --- web_read tool ---
+  pi.registerTool({
+    name: WEB_TOOLS.READ,
+    label: "Web Read",
+    description:
+      "Read and extract content from a URL. " +
+      "Extracts main content, strips navigation/ads. Returns markdown.",
+    promptSnippet: "Read content from a URL.",
+    promptGuidelines: [
+      "Use web_read to extract content from a web page.",
+      "Returns main content as markdown.",
+      "Lower source = simpler providers (Jina Reader).",
+      "Higher source = more capable providers (Firecrawl, Perplexity).",
+    ],
+    parameters: Type.Object({
+      url: Type.String({ description: "URL to read" }),
+      source: Type.Optional(
+        Type.Number({
+          description:
+            "Provider selection (1=Jina Reader, 2=Firecrawl, 3=Perplexity). " +
+            "Omit for auto-selection.",
+          minimum: 1,
+          maximum: 3,
+        })
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      try {
+        const result = await executeRead(params.url, params.source);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Content from ${result.url}:\n\n${result.content}`,
+            },
+          ],
+        };
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Read failed: ${message}` }],
+          isError: true,
+        };
+      }
+    },
+  });
+
+  // --- web_llm_summarize tool ---
+  pi.registerTool({
+    name: WEB_TOOLS.SUMMARIZE,
+    label: "Web LLM Summarize",
+    description:
+      "Summarize web content using LLM. " +
+      "Fetches content from URL, then uses LLM to summarize. " +
+      "Higher cost (LLM tokens + provider cost).",
+    promptSnippet: "Summarize web content using LLM.",
+    promptGuidelines: [
+      "Use web_llm_summarize to get a summary of web content.",
+      "Specify custom prompt for targeted summaries.",
+      "Omit source for auto-selection of content provider.",
+      "Higher cost due to LLM token usage.",
+    ],
+    parameters: Type.Object({
+      url: Type.String({ description: "URL to summarize" }),
+      prompt: Type.Optional(
+        Type.String({
+          description:
+            "Custom summarization prompt. " +
+            "Omit for default comprehensive summary.",
+        })
+      ),
+      source: Type.Optional(
+        Type.Number({
+          description:
+            "Provider selection for content fetch (1=Jina Reader, 2=Firecrawl, 3=Perplexity). " +
+            "Omit for auto-selection.",
+          minimum: 1,
+          maximum: 3,
+        })
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      try {
+        const result = await executeSummarize(
+          params.url,
+          params.prompt,
+          params.source
+        );
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Summary of ${result.url}:\n\n${result.summary}`,
+            },
+          ],
+        };
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Summarize failed: ${message}` }],
+          isError: true,
+        };
+      }
+    },
+  });
+}

package/src/tui/provider-selector.ts

@@ -0,0 +1,71 @@
+/**
+ * @unipi/web-api — Provider selector TUI component
+ *
+ * Displays provider list with status indicators for API key management.
+ */
+
+import type { WebProvider } from "../providers/base.js";
+import { registry } from "../providers/registry.js";
+import { getApiKey, isProviderEnabled } from "../settings.js";
+
+/** Provider status */
+export interface ProviderStatus {
+  provider: WebProvider;
+  configured: boolean;
+  enabled: boolean;
+  hasApiKey: boolean;
+}
+
+/**
+ * Get status of all providers.
+ */
+export function getProviderStatuses(): ProviderStatus[] {
+  const providers = registry.getAllProviders();
+
+  return providers.map((provider) => {
+    const hasApiKey = provider.requiresApiKey
+      ? !!getApiKey(provider.id)
+      : true;
+    const enabled = isProviderEnabled(provider.id);
+
+    return {
+      provider,
+      configured: hasApiKey && enabled,
+      enabled,
+      hasApiKey,
+    };
+  });
+}
+
+/**
+ * Format provider status for display.
+ */
+export function formatProviderStatus(status: ProviderStatus): string {
+  const icon = status.configured ? "✓" : "✗";
+  const name = status.provider.name.padEnd(20);
+  const capabilities = status.provider.capabilities.join(", ");
+  const apiKeyStatus = status.provider.requiresApiKey
+    ? status.hasApiKey
+      ? "API key configured"
+      : "API key required"
+    : "No API key needed";
+
+  return `${icon} ${name} ${capabilities.padEnd(30)} ${apiKeyStatus}`;
+}
+
+/**
+ * Get provider selection options for TUI.
+ */
+export function getProviderOptions(): Array<{
+  label: string;
+  value: string;
+  description: string;
+}> {
+  const statuses = getProviderStatuses();
+
+  return statuses.map((status) => ({
+    label: formatProviderStatus(status),
+    value: status.provider.id,
+    description: `${status.provider.name} - ${status.provider.capabilities.join(", ")}`,
+  }));
+}