ubersearch 0.0.0-development

package/src/providers/linkup.ts

@@ -0,0 +1,114 @@
+/**
+ * Linkup Search Provider Implementation
+ * https://www.linkup.ai/
+ */
+
+import type { LinkupConfig } from "../config/types";
+import { DockerLifecycleManager } from "../core/docker/dockerLifecycleManager";
+import type { ILifecycleProvider } from "../core/provider";
+import type { SearchQuery, SearchResponse } from "../core/types";
+import { BaseProvider } from "./BaseProvider";
+import { PROVIDER_DEFAULTS } from "./constants";
+import type { LinkupApiResponse, LinkupSearchResult } from "./types";
+import { fetchWithErrorHandling } from "./utils";
+
+export class LinkupProvider extends BaseProvider<LinkupConfig> implements ILifecycleProvider {
+  private lifecycleManager: DockerLifecycleManager;
+
+  constructor(config: LinkupConfig) {
+    super(config);
+
+    const autoStart = config.autoStart ?? false;
+    const autoStop = config.autoStop ?? false;
+    const initTimeoutMs = config.initTimeoutMs ?? 30000;
+
+    this.lifecycleManager = new DockerLifecycleManager({
+      containerName: config.containerName,
+      composeFile: config.composeFile,
+      healthEndpoint: config.healthEndpoint,
+      autoStart,
+      autoStop,
+      initTimeoutMs,
+    });
+  }
+
+  protected getDocsUrl(): string {
+    return "https://docs.linkup.ai/";
+  }
+
+  protected getApiKeyEnv(): string {
+    return this.config.apiKeyEnv;
+  }
+
+  async search(query: SearchQuery): Promise<SearchResponse> {
+    const apiKey = this.getApiKey();
+
+    const requestBody = {
+      q: query.query,
+      depth: "standard",
+      outputType: "searchResults",
+      maxResults: query.limit ?? 5,
+    };
+
+    const { data: json, tookMs } = await fetchWithErrorHandling<LinkupApiResponse>(
+      this.id,
+      this.config.endpoint,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(requestBody),
+        timeoutMs: PROVIDER_DEFAULTS.DEFAULT_TIMEOUT_MS,
+      },
+      "Linkup",
+    );
+
+    const results: LinkupSearchResult[] = json.results ?? [];
+
+    this.validateResults(results, "Linkup");
+
+    // Map to normalized format
+    // Linkup results have url, name/title, content/snippet
+    const items = results.map((r: LinkupSearchResult) => ({
+      title: r.name ?? r.title ?? r.url,
+      url: r.url,
+      snippet: r.content ?? r.snippet ?? r.description ?? "",
+      score: r.score ?? r.relevance,
+      sourceEngine: this.id,
+    }));
+
+    return {
+      engineId: this.id,
+      items,
+      raw: query.includeRaw ? json : undefined,
+      tookMs,
+    };
+  }
+
+  // ILifecycleProvider implementation
+  async init(): Promise<void> {
+    await this.lifecycleManager.init();
+  }
+
+  async healthcheck(): Promise<boolean> {
+    return await this.lifecycleManager.healthcheck();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.lifecycleManager.shutdown();
+  }
+
+  async validateConfig(): Promise<{
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+  }> {
+    return await this.lifecycleManager.validateDockerConfig();
+  }
+
+  isLifecycleManaged(): boolean {
+    return true; // This provider manages lifecycle
+  }
+}

package/src/providers/retry.ts

@@ -0,0 +1,95 @@
+/**
+ * Retry Logic for Provider Operations
+ *
+ * Provides exponential backoff retry functionality for resilient
+ * provider operations
+ */
+
+import type { EngineId } from "../core/types";
+import { SearchError } from "../core/types";
+
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+  /** Maximum number of retry attempts */
+  maxAttempts?: number;
+
+  /** Initial delay between retries in milliseconds */
+  initialDelayMs?: number;
+
+  /** Multiplier for exponential backoff */
+  backoffMultiplier?: number;
+
+  /** Maximum delay between retries in milliseconds */
+  maxDelayMs?: number;
+
+  /** Whether to retry on specific error types */
+  retryableErrors?: Array<"network_error" | "api_error" | "timeout">;
+}
+
+/**
+ * Default retry configuration
+ */
+export const DEFAULT_RETRY_CONFIG: Required<RetryConfig> = {
+  maxAttempts: 3,
+  initialDelayMs: 1000,
+  backoffMultiplier: 2,
+  maxDelayMs: 10000,
+  retryableErrors: ["network_error", "api_error"],
+};
+
+/**
+ * Execute a function with retry logic and exponential backoff
+ *
+ * @param engineId - Engine ID for error messages
+ * @param fn - Function to execute with retry logic
+ * @param config - Retry configuration
+ * @returns Result of the function
+ * @throws SearchError if all retry attempts fail
+ */
+export async function withRetry<T>(
+  engineId: EngineId,
+  fn: () => Promise<T>,
+  config: RetryConfig = {},
+): Promise<T> {
+  const {
+    maxAttempts = DEFAULT_RETRY_CONFIG.maxAttempts,
+    initialDelayMs = DEFAULT_RETRY_CONFIG.initialDelayMs,
+    backoffMultiplier = DEFAULT_RETRY_CONFIG.backoffMultiplier,
+    maxDelayMs = DEFAULT_RETRY_CONFIG.maxDelayMs,
+    retryableErrors = DEFAULT_RETRY_CONFIG.retryableErrors,
+  } = config;
+
+  let lastError: unknown;
+  let delay = initialDelayMs;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (!(error instanceof SearchError)) {
+        throw error;
+      }
+
+      const shouldRetry = retryableErrors.includes(error.reason as "network_error" | "api_error");
+
+      if (!shouldRetry || attempt >= maxAttempts) {
+        throw error;
+      }
+
+      const nextDelay = Math.min(delay * backoffMultiplier, maxDelayMs);
+
+      console.warn(
+        `[${engineId}] Attempt ${attempt}/${maxAttempts} failed: ${error.message}. Retrying in ${nextDelay}ms...`,
+      );
+
+      await new Promise((resolve) => setTimeout(resolve, nextDelay));
+      delay = nextDelay;
+    }
+  }
+
+  throw lastError;
+}

package/src/providers/searchxng.ts

@@ -0,0 +1,163 @@
+/**
+ * SearXNG Search Provider Implementation
+ *
+ * Integrates SearXNG with auto-start Docker container management
+ */
+
+import { dirname } from "node:path";
+import type { SearchxngConfig as BaseSearchxngConfig } from "../config/types";
+import { DockerLifecycleManager } from "../core/docker/dockerLifecycleManager";
+import type { ILifecycleProvider, ProviderMetadata } from "../core/provider";
+import type { SearchQuery, SearchResponse, SearchResultItem } from "../core/types";
+import { SearchError } from "../core/types";
+import { BaseProvider } from "./BaseProvider";
+import { PROVIDER_DEFAULTS } from "./constants";
+import type { SearxngApiResponse, SearxngSearchResult } from "./types";
+import { buildUrl, fetchWithErrorHandling } from "./utils";
+
+export class SearchxngProvider
+  extends BaseProvider<BaseSearchxngConfig>
+  implements ILifecycleProvider
+{
+  private lifecycleManager: DockerLifecycleManager;
+  private defaultLimit: number;
+
+  constructor(config: BaseSearchxngConfig) {
+    super(config);
+    this.defaultLimit = config.defaultLimit;
+
+    const autoStart = config.autoStart ?? true;
+    const autoStop = config.autoStop ?? true;
+    const initTimeoutMs = config.initTimeoutMs ?? PROVIDER_DEFAULTS.SEARXNG_INIT_TIMEOUT_MS;
+
+    const projectRoot = config.composeFile ? dirname(config.composeFile) : process.cwd();
+
+    this.lifecycleManager = new DockerLifecycleManager({
+      containerName: config.containerName,
+      composeFile: config.composeFile,
+      healthEndpoint: config.healthEndpoint,
+      autoStart,
+      autoStop,
+      initTimeoutMs,
+      projectRoot,
+    });
+  }
+
+  protected getDocsUrl(): string {
+    return "https://docs.searxng.org/";
+  }
+
+  protected getApiKeyEnv(): string {
+    return this.config.apiKeyEnv ?? "";
+  }
+
+  override getMetadata(): ProviderMetadata {
+    return {
+      id: this.id,
+      displayName: "SearXNG (Local)",
+      docsUrl: this.getDocsUrl(),
+    };
+  }
+
+  protected override getApiKey(): string {
+    const apiKeyEnv = this.getApiKeyEnv();
+    if (apiKeyEnv) {
+      return process.env[apiKeyEnv] ?? "";
+    }
+    return "";
+  }
+
+  async search(query: SearchQuery): Promise<SearchResponse> {
+    const isHealthy = await this.healthcheck();
+
+    if (!isHealthy) {
+      const isInitializing = !!(await (this.lifecycleManager as any).initPromise);
+      if (!isInitializing) {
+        try {
+          console.log(`[SearXNG] Container not healthy, attempting auto-start...`);
+          await this.init();
+        } catch (initError) {
+          console.error(`[SearXNG] Failed to auto-start container:`, initError);
+        }
+      }
+    }
+
+    if (!isHealthy) {
+      throw new SearchError(
+        this.id,
+        "provider_unavailable",
+        "SearXNG container is not healthy. Check logs with: docker compose logs -f searxng",
+      );
+    }
+
+    const limit = query.limit ?? this.defaultLimit;
+    const url = buildUrl(this.config.endpoint, {
+      q: query.query,
+      format: "json",
+      language: "all",
+      pageno: 1,
+      safesearch: 0,
+    });
+
+    const { data: json, tookMs } = await fetchWithErrorHandling<SearxngApiResponse>(
+      this.id,
+      url,
+      {
+        method: "GET",
+        headers: {
+          Accept: "application/json",
+          "X-Forwarded-For": "127.0.0.1",
+          "X-Real-IP": "127.0.0.1",
+        },
+        timeoutMs: PROVIDER_DEFAULTS.DEFAULT_TIMEOUT_MS,
+      },
+      "SearXNG",
+    );
+
+    const results: SearxngSearchResult[] = json.results ?? [];
+
+    this.validateResults(results, "SearXNG");
+
+    const items: SearchResultItem[] = results.map((r: SearxngSearchResult) => ({
+      title: r.title ?? r.url ?? "#",
+      url: r.url ?? "#",
+      snippet: r.content ?? r.description ?? "",
+      score: r.score ?? r.rank,
+      sourceEngine: r.engine ?? this.id,
+    }));
+
+    const limitedItems = items.slice(0, limit);
+
+    return {
+      engineId: this.id,
+      items: limitedItems,
+      raw: query.includeRaw ? json : undefined,
+      tookMs,
+    };
+  }
+
+  // ILifecycleProvider implementation
+  async init(): Promise<void> {
+    await this.lifecycleManager.init();
+  }
+
+  async healthcheck(): Promise<boolean> {
+    return await this.lifecycleManager.healthcheck();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.lifecycleManager.shutdown();
+  }
+
+  async validateConfig(): Promise<{
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+  }> {
+    return await this.lifecycleManager.validateDockerConfig();
+  }
+
+  isLifecycleManaged(): boolean {
+    return true;
+  }
+}

package/src/providers/tavily.ts

@@ -0,0 +1,73 @@
+/**
+ * Tavily Search Provider Implementation
+ */
+
+import type { TavilyConfig } from "../config/types";
+import type { SearchQuery, SearchResponse } from "../core/types";
+import { BaseProvider } from "./BaseProvider";
+import { PROVIDER_DEFAULTS } from "./constants";
+import type { TavilyApiResponse, TavilySearchResult } from "./types";
+import { fetchWithErrorHandling } from "./utils";
+
+export class TavilyProvider extends BaseProvider<TavilyConfig> {
+  protected getDocsUrl(): string {
+    return "https://docs.tavily.com/";
+  }
+
+  protected getApiKeyEnv(): string {
+    return this.config.apiKeyEnv;
+  }
+
+  async search(query: SearchQuery): Promise<SearchResponse> {
+    const apiKey = this.getApiKey();
+
+    const requestBody = {
+      api_key: apiKey,
+      query: query.query,
+      search_depth: this.config.searchDepth,
+      max_results: query.limit ?? 5,
+      include_answer: false,
+      include_raw_content: false,
+      include_images: false,
+    };
+
+    // Make request with error handling
+    const { data: json, tookMs } = await fetchWithErrorHandling<TavilyApiResponse>(
+      this.id,
+      this.config.endpoint,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(requestBody),
+        timeoutMs: PROVIDER_DEFAULTS.DEFAULT_TIMEOUT_MS,
+      },
+      "Tavily",
+    );
+
+    this.validateResults(json.results, "Tavily");
+
+    // Map to normalized format and filter out invalid results
+    const items = json.results
+      .filter(
+        (r: TavilySearchResult): boolean =>
+          r != null &&
+          typeof r === "object" &&
+          (r.title != null || r.url != null) &&
+          (r.title != null || r.content != null || r.snippet != null),
+      )
+      .map((r: TavilySearchResult) => ({
+        title: r.title ?? r.url ?? "Untitled",
+        url: r.url ?? "",
+        snippet: r.content ?? r.snippet ?? "",
+        score: r.score,
+        sourceEngine: this.id,
+      }));
+
+    return {
+      engineId: this.id,
+      items,
+      raw: query.includeRaw ? json : undefined,
+      tookMs,
+    };
+  }
+}

package/src/providers/types/index.ts

@@ -0,0 +1,185 @@
+/**
+ * Provider API Response Types
+ *
+ * Type definitions for external search provider API responses.
+ * These types ensure type safety when parsing provider responses.
+ */
+
+// ============ Tavily API Types ============
+
+/**
+ * Single result from Tavily search API
+ */
+export interface TavilySearchResult {
+  title?: string;
+  url: string;
+  content?: string;
+  snippet?: string;
+  score?: number;
+  published_date?: string;
+}
+
+/**
+ * Tavily search API response
+ */
+export interface TavilyApiResponse {
+  query?: string;
+  results: TavilySearchResult[];
+  answer?: string;
+  response_time?: number;
+  images?: string[];
+}
+
+// ============ Brave API Types ============
+
+/**
+ * Single web result from Brave search API
+ */
+export interface BraveWebResult {
+  title: string;
+  url: string;
+  description?: string;
+  snippet?: string;
+  abstract?: string;
+  rank?: number;
+  score?: number;
+  age?: string;
+  language?: string;
+  family_friendly?: boolean;
+}
+
+/**
+ * Brave search API response
+ */
+export interface BraveApiResponse {
+  type?: string;
+  query?: {
+    original: string;
+    altered?: string;
+  };
+  web?: {
+    type?: string;
+    results: BraveWebResult[];
+    family_friendly?: boolean;
+  };
+  /** Fallback for alternative response format */
+  results?: BraveWebResult[];
+}
+
+// ============ Linkup API Types ============
+
+/**
+ * Single result from Linkup search API
+ */
+export interface LinkupSearchResult {
+  url: string;
+  name?: string;
+  title?: string;
+  content?: string;
+  snippet?: string;
+  description?: string;
+  score?: number;
+  relevance?: number;
+}
+
+/**
+ * Linkup search API response
+ */
+export interface LinkupApiResponse {
+  results: LinkupSearchResult[];
+  answer?: string;
+  sources?: LinkupSearchResult[];
+}
+
+// ============ SearXNG API Types ============
+
+/**
+ * Single result from SearXNG search API
+ */
+export interface SearxngSearchResult {
+  title?: string;
+  url: string;
+  content?: string;
+  description?: string;
+  score?: number;
+  rank?: number;
+  engine?: string;
+  parsed_url?: string[];
+  engines?: string[];
+  positions?: number[];
+  category?: string;
+}
+
+/**
+ * SearXNG search API response
+ */
+export interface SearxngApiResponse {
+  query?: string;
+  results: SearxngSearchResult[];
+  number_of_results?: number;
+  infoboxes?: unknown[];
+  suggestions?: string[];
+  answers?: string[];
+  corrections?: string[];
+  unresponsive_engines?: string[];
+}
+
+// ============ Type Guards ============
+
+/**
+ * Type guard to check if a value is a valid Tavily result
+ */
+export function isTavilyResult(value: unknown): value is TavilySearchResult {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return typeof obj.url === "string" || typeof obj.title === "string";
+}
+
+/**
+ * Type guard to check if a value is a valid Tavily response
+ */
+export function isTavilyResponse(value: unknown): value is TavilyApiResponse {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return "results" in obj && Array.isArray(obj.results);
+}
+
+/**
+ * Type guard to check if a value is a valid Brave response
+ */
+export function isBraveResponse(value: unknown): value is BraveApiResponse {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    ("web" in obj && typeof obj.web === "object") ||
+    ("results" in obj && Array.isArray(obj.results))
+  );
+}
+
+/**
+ * Type guard to check if a value is a valid Linkup response
+ */
+export function isLinkupResponse(value: unknown): value is LinkupApiResponse {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return "results" in obj && Array.isArray(obj.results);
+}
+
+/**
+ * Type guard to check if a value is a valid SearXNG response
+ */
+export function isSearxngResponse(value: unknown): value is SearxngApiResponse {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return "results" in obj && Array.isArray(obj.results);
+}