@pellux/goodvibes-tui 0.18.4

package/src/web-search/providers/searxng.ts

@@ -0,0 +1,88 @@
+import type { WebSearchProvider, WebSearchProviderResponse, WebSearchRequest } from '@pellux/goodvibes-sdk/platform/web-search/types';
+import {
+  buildDescriptor,
+  executeJsonRequest,
+  firstString,
+  resultFromRecord,
+  type SearchProviderContext,
+} from './shared.ts';
+
+const SEARXNG_ENV_KEYS = ['SEARXNG_BASE_URL'] as const;
+const SEARXNG_SERVICE_NAME = 'searxng';
+
+function mapTimeRange(value: WebSearchRequest['timeRange']): string | undefined {
+  switch (value) {
+    case 'day':
+      return 'day';
+    case 'month':
+      return 'month';
+    case 'year':
+      return 'year';
+    default:
+      return undefined;
+  }
+}
+
+export function createSearxngSearchProvider(context: SearchProviderContext): WebSearchProvider {
+  const env = context.env;
+  const serviceRegistry = context.serviceRegistry;
+  return {
+    id: 'searxng',
+    label: 'SearXNG',
+    capabilities: ['search', 'evidence'],
+    descriptor() {
+      return buildDescriptor({
+        id: 'searxng',
+        label: 'SearXNG',
+        note: 'Uses a SearXNG instance via its JSON search API. Configure SEARXNG_BASE_URL or a searxng service entry.',
+        requiresAuth: false,
+        serviceName: SEARXNG_SERVICE_NAME,
+        baseUrlEnvCandidates: SEARXNG_ENV_KEYS,
+      }, { env, serviceRegistry });
+    },
+    async search(request: WebSearchRequest): Promise<WebSearchProviderResponse> {
+      const maxResults = Math.max(1, Math.min(25, request.maxResults ?? 10));
+      const baseUrl = (env.SEARXNG_BASE_URL ?? serviceRegistry.get(SEARXNG_SERVICE_NAME)?.baseUrl ?? '').trim().replace(/\/+$/, '');
+      if (!baseUrl) {
+        throw new Error('SearXNG requires SEARXNG_BASE_URL or a searxng service entry with baseUrl.');
+      }
+      const { payload } = await executeJsonRequest<Record<string, unknown>>({
+        url: `${baseUrl}/search`,
+        params: {
+          q: request.query,
+          format: 'json',
+          pageno: '1',
+          ...(request.region ? { language: request.region } : {}),
+          ...(mapTimeRange(request.timeRange) ? { time_range: mapTimeRange(request.timeRange)! } : {}),
+        },
+        headers: { Accept: 'application/json' },
+        service: serviceRegistry.get(SEARXNG_SERVICE_NAME) ? SEARXNG_SERVICE_NAME : undefined,
+        fetcher: context.fetcher,
+      });
+      const results = Array.isArray(payload.results)
+        ? payload.results
+            .slice(0, maxResults)
+            .map((entry, index) => {
+              if (!entry || typeof entry !== 'object') return null;
+              const record = entry as Record<string, unknown>;
+              return resultFromRecord('searxng', index + 1, record, {
+                urlKeys: ['url'],
+                titleKeys: ['title'],
+                snippetKeys: ['content'],
+                metadata: {
+                  engine: firstString(record, ['engine']),
+                  publishedDate: firstString(record, ['publishedDate', 'published_date']),
+                },
+              });
+            })
+            .filter((entry): entry is NonNullable<typeof entry> => entry !== null)
+        : [];
+      return {
+        results,
+        metadata: {
+          numberOfResults: typeof payload.number_of_results === 'number' ? payload.number_of_results : undefined,
+        },
+      };
+    },
+  };
+}

package/src/web-search/providers/shared.ts

@@ -0,0 +1,249 @@
+import type { ServiceRegistry } from '../../config/service-registry.ts';
+import { executeFetchInput, type FetchOutput, type FetchUrlResult } from '../../tools/fetch/index.ts';
+import type { FetchAuthInput, FetchInput, FetchUrlInput } from '@pellux/goodvibes-sdk/platform/tools/fetch/schema';
+import type { WebSearchEvidence, WebSearchProviderDescriptor, WebSearchResult } from '@pellux/goodvibes-sdk/platform/web-search/types';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+
+type EnvMap = Record<string, string | undefined>;
+type FetchExecutor = (input: FetchInput) => Promise<FetchOutput>;
+
+export interface SearchProviderContext {
+  readonly fetcher?: FetchExecutor;
+  readonly env: EnvMap;
+  readonly serviceRegistry: Pick<ServiceRegistry, 'get'>;
+}
+
+export interface SearchProviderConfig {
+  readonly id: string;
+  readonly label: string;
+  readonly note: string;
+  readonly envKeyCandidates?: readonly string[];
+  readonly serviceName?: string;
+  readonly baseUrlEnvCandidates?: readonly string[];
+  readonly defaultBaseUrl?: string;
+  readonly requiresAuth?: boolean;
+}
+
+export interface JsonRequestConfig {
+  readonly url: string;
+  readonly method?: 'GET' | 'POST';
+  readonly params?: Record<string, string>;
+  readonly body?: Record<string, unknown>;
+  readonly headers?: Record<string, string>;
+  readonly service?: string;
+  readonly auth?: FetchAuthInput;
+  readonly fetcher?: FetchExecutor;
+  readonly maxContentLength?: number;
+}
+
+export interface JsonRequestResult<T = unknown> {
+  readonly payload: T;
+  readonly response: FetchUrlResult;
+}
+
+export function resolveDomain(url: string): string | undefined {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return undefined;
+  }
+}
+
+export function trimSnippet(value: unknown, limit = 320): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  if (!normalized) return undefined;
+  if (normalized.length <= limit) return normalized;
+  return `${normalized.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
+}
+
+export function makeEvidence(
+  url: string,
+  content: unknown,
+  metadata: Record<string, unknown> = {},
+  extract: 'raw' | 'text' | 'json' | 'markdown' | 'readable' | 'code_blocks' | 'links' | 'metadata' | 'structured' | 'tables' | 'pdf' | 'summary' = 'summary',
+): WebSearchEvidence[] | undefined {
+  if (typeof content !== 'string') return undefined;
+  const normalized = content.trim();
+  if (!normalized) return undefined;
+  return [{
+    url,
+    extract,
+    content: normalized,
+    tokensUsed: Math.ceil(normalized.length / 4),
+    metadata,
+  }];
+}
+
+export function withInlineApiKey(
+  env: EnvMap,
+  envKeys: readonly string[] | undefined,
+  headerName: string,
+): FetchAuthInput | undefined {
+  if (!envKeys || envKeys.length === 0) return undefined;
+  for (const key of envKeys) {
+    const value = env[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return {
+        type: 'api-key',
+        header: headerName,
+        key: value.trim(),
+      };
+    }
+  }
+  return undefined;
+}
+
+export function withInlineBearer(
+  env: EnvMap,
+  envKeys: readonly string[] | undefined,
+): FetchAuthInput | undefined {
+  if (!envKeys || envKeys.length === 0) return undefined;
+  for (const key of envKeys) {
+    const value = env[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return {
+        type: 'bearer',
+        token: value.trim(),
+      };
+    }
+  }
+  return undefined;
+}
+
+export function hasConfiguredCredential(
+  serviceRegistry: Pick<ServiceRegistry, 'get'>,
+  env: EnvMap,
+  envKeys: readonly string[] | undefined,
+  serviceName?: string,
+): boolean {
+  const envConfigured = (envKeys ?? []).some((key) => typeof env[key] === 'string' && env[key]!.trim().length > 0);
+  if (envConfigured) return true;
+  return Boolean(serviceName && serviceRegistry.get(serviceName));
+}
+
+export function resolveBaseUrl(
+  serviceRegistry: Pick<ServiceRegistry, 'get'>,
+  env: EnvMap,
+  envKeys: readonly string[] | undefined,
+  serviceName: string | undefined,
+  defaultBaseUrl?: string,
+): string | null {
+  for (const key of envKeys ?? []) {
+    const value = env[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.trim().replace(/\/+$/, '');
+    }
+  }
+  const configuredService = serviceName ? serviceRegistry.get(serviceName) : null;
+  const serviceUrl = configuredService?.baseUrl?.trim();
+  if (serviceUrl) return serviceUrl.replace(/\/+$/, '');
+  return defaultBaseUrl ? defaultBaseUrl.replace(/\/+$/, '') : null;
+}
+
+export function buildDescriptor(
+  config: SearchProviderConfig,
+  context: SearchProviderContext,
+): WebSearchProviderDescriptor {
+  const configured = config.requiresAuth === false
+    ? resolveBaseUrl(context.serviceRegistry, context.env, config.baseUrlEnvCandidates, config.serviceName, config.defaultBaseUrl) != null
+    : hasConfiguredCredential(context.serviceRegistry, context.env, config.envKeyCandidates, config.serviceName);
+  return {
+    id: config.id,
+    label: config.label,
+    capabilities: ['search', 'evidence'],
+    requiresAuth: config.requiresAuth ?? true,
+    configured,
+    note: config.note,
+  };
+}
+
+export async function executeJsonRequest<T = unknown>(config: JsonRequestConfig): Promise<JsonRequestResult<T>> {
+  const fetcher = config.fetcher ?? executeFetchInput;
+  const urlInput: FetchUrlInput = {
+    url: config.url,
+    method: config.method ?? 'GET',
+    extract: 'json',
+    ...(config.params ? { params: config.params } : {}),
+    ...(config.headers ? { headers: config.headers } : {}),
+    ...(config.body ? { body_type: 'json', body: JSON.stringify(config.body) } : {}),
+    ...(config.service ? { service: config.service } : {}),
+    ...(config.auth ? { auth: config.auth } : {}),
+    ...(config.maxContentLength ? { max_content_length: config.maxContentLength } : {}),
+  };
+  const output = await fetcher({
+    urls: [urlInput],
+    parallel: false,
+    verbosity: 'standard',
+    sanitize_mode: 'safe-text',
+    max_content_length: config.maxContentLength ?? 512_000,
+  });
+  const response = output.results?.[0];
+  if (!response || response.error || typeof response.content !== 'string') {
+    throw new Error(response?.error ?? `Search provider request failed for ${config.url}`);
+  }
+  let payload: T;
+  try {
+    payload = JSON.parse(response.content) as T;
+  } catch (error) {
+    throw new Error(`Search provider returned invalid JSON for ${config.url}: ${summarizeError(error)}`);
+  }
+  return { payload, response };
+}
+
+export function resultFromRecord(
+  providerId: string,
+  rank: number,
+  record: Record<string, unknown>,
+  options: {
+    readonly urlKeys?: readonly string[];
+    readonly titleKeys?: readonly string[];
+    readonly snippetKeys?: readonly string[];
+    readonly displayUrlKeys?: readonly string[];
+    readonly evidenceKeys?: readonly string[];
+    readonly metadata?: Record<string, unknown>;
+  } = {},
+): WebSearchResult | null {
+  const url = firstString(record, options.urlKeys ?? ['url', 'link', 'id']);
+  if (!url) return null;
+  return {
+    rank,
+    url,
+    ...(firstString(record, options.titleKeys ?? ['title', 'name', 'heading']) ? { title: firstString(record, options.titleKeys ?? ['title', 'name', 'heading']) } : {}),
+    ...(trimSnippet(firstString(record, options.snippetKeys ?? ['snippet', 'description', 'content', 'text'])) ? { snippet: trimSnippet(firstString(record, options.snippetKeys ?? ['snippet', 'description', 'content', 'text'])) } : {}),
+    ...(firstString(record, options.displayUrlKeys ?? ['displayUrl', 'display_url']) ? { displayUrl: firstString(record, options.displayUrlKeys ?? ['displayUrl', 'display_url']) } : {}),
+    ...(resolveDomain(url) ? { domain: resolveDomain(url) } : {}),
+    type: 'organic',
+    providerId,
+    metadata: {
+      ...(options.metadata ?? {}),
+      ...(options.evidenceKeys
+        ? {
+            hasProviderEvidence: options.evidenceKeys.some((key) => typeof record[key] === 'string' && String(record[key]).trim().length > 0),
+          }
+        : {}),
+    },
+    ...(providerEvidence(url, record, options.evidenceKeys) ? { evidence: providerEvidence(url, record, options.evidenceKeys) } : {}),
+  };
+}
+
+export function firstString(record: Record<string, unknown>, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim();
+  }
+  return undefined;
+}
+
+function providerEvidence(
+  url: string,
+  record: Record<string, unknown>,
+  keys: readonly string[] | undefined,
+): WebSearchEvidence[] | undefined {
+  for (const key of keys ?? []) {
+    const value = record[key];
+    if (typeof value !== 'string' || value.trim().length === 0) continue;
+    return makeEvidence(url, value, { providerField: key });
+  }
+  return undefined;
+}

package/src/web-search/providers/tavily.ts

@@ -0,0 +1,90 @@
+import type { WebSearchInstantAnswer, WebSearchProvider, WebSearchProviderResponse, WebSearchRequest } from '@pellux/goodvibes-sdk/platform/web-search/types';
+import {
+  buildDescriptor,
+  executeJsonRequest,
+  firstString,
+  resultFromRecord,
+  withInlineBearer,
+  type SearchProviderContext,
+} from './shared.ts';
+
+const TAVILY_DEFAULT_BASE_URL = 'https://api.tavily.com';
+const TAVILY_ENV_KEYS = ['TAVILY_API_KEY'] as const;
+const TAVILY_SERVICE_NAME = 'tavily';
+
+function buildInstantAnswer(payload: Record<string, unknown>): WebSearchInstantAnswer | undefined {
+  const answer = firstString(payload, ['answer']);
+  if (!answer) return undefined;
+  return {
+    heading: 'Tavily Answer',
+    answer,
+    type: 'answer',
+    related: [],
+    metadata: {},
+  };
+}
+
+export function createTavilySearchProvider(context: SearchProviderContext): WebSearchProvider {
+  const env = context.env;
+  const serviceRegistry = context.serviceRegistry;
+  return {
+    id: 'tavily',
+    label: 'Tavily',
+    capabilities: ['search', 'instant_answer', 'evidence'],
+    descriptor() {
+      return buildDescriptor({
+        id: 'tavily',
+        label: 'Tavily',
+        note: 'Uses Tavily Search JSON results. Configure via TAVILY_API_KEY or a tavily service entry.',
+        envKeyCandidates: TAVILY_ENV_KEYS,
+        serviceName: TAVILY_SERVICE_NAME,
+        defaultBaseUrl: TAVILY_DEFAULT_BASE_URL,
+      }, { env, serviceRegistry });
+    },
+    async search(request: WebSearchRequest): Promise<WebSearchProviderResponse> {
+      const maxResults = Math.max(1, Math.min(20, request.maxResults ?? 10));
+      const baseUrl = (serviceRegistry.get(TAVILY_SERVICE_NAME)?.baseUrl ?? TAVILY_DEFAULT_BASE_URL).replace(/\/+$/, '');
+      const { payload } = await executeJsonRequest<Record<string, unknown>>({
+        url: `${baseUrl}/search`,
+        method: 'POST',
+        headers: { Accept: 'application/json' },
+        body: {
+          query: request.query,
+          max_results: maxResults,
+          include_answer: request.includeInstantAnswer !== false,
+          search_depth: request.includeEvidence || request.verbosity === 'evidence' || request.verbosity === 'full'
+            ? 'advanced'
+            : 'basic',
+        },
+        service: serviceRegistry.get(TAVILY_SERVICE_NAME) ? TAVILY_SERVICE_NAME : undefined,
+        auth: serviceRegistry.get(TAVILY_SERVICE_NAME) ? undefined : withInlineBearer(env, TAVILY_ENV_KEYS),
+        fetcher: context.fetcher,
+      });
+      const results = Array.isArray(payload.results)
+        ? payload.results
+            .map((entry, index) => {
+              if (!entry || typeof entry !== 'object') return null;
+              const record = entry as Record<string, unknown>;
+              return resultFromRecord('tavily', index + 1, record, {
+                urlKeys: ['url'],
+                titleKeys: ['title'],
+                snippetKeys: ['content'],
+                evidenceKeys: ['raw_content'],
+                metadata: {
+                  score: typeof record.score === 'number' ? record.score : undefined,
+                },
+              });
+            })
+            .filter((entry): entry is NonNullable<typeof entry> => entry !== null)
+        : [];
+      return {
+        results,
+        ...(buildInstantAnswer(payload) ? { instantAnswer: buildInstantAnswer(payload) } : {}),
+        metadata: {
+          requestId: firstString(payload, ['request_id']),
+          responseTime: firstString(payload, ['response_time']),
+        },
+      };
+    },
+  };
+}

package/src/web-search/service.ts

@@ -0,0 +1,142 @@
+import { FetchRuntimeService, type FetchRuntimeDeps } from '../tools/fetch/index.ts';
+import type { FetchExtractMode } from '@pellux/goodvibes-sdk/platform/tools/fetch/schema';
+import { WebSearchProviderRegistry } from './provider-registry.ts';
+import type {
+  WebSearchEvidence,
+  WebSearchProvider,
+  WebSearchRequest,
+  WebSearchResponse,
+  WebSearchResult,
+  WebSearchVerbosity,
+} from '@pellux/goodvibes-sdk/platform/web-search/types';
+
+export interface WebSearchServiceStatus {
+  readonly enabled: boolean;
+  readonly providerCount: number;
+  readonly providers: ReturnType<WebSearchProviderRegistry['list']>;
+  readonly note: string;
+}
+
+function selectEvidenceExtract(request: WebSearchRequest, verbosity: WebSearchVerbosity): FetchExtractMode {
+  if (request.evidenceExtract) return request.evidenceExtract;
+  return verbosity === 'full' ? 'readable' : 'summary';
+}
+
+function shapeResultForVerbosity(result: WebSearchResult, verbosity: WebSearchVerbosity): WebSearchResult {
+  switch (verbosity) {
+    case 'urls_only':
+      return {
+        rank: result.rank,
+        url: result.url,
+        ...(result.domain ? { domain: result.domain } : {}),
+        type: result.type,
+        providerId: result.providerId,
+        metadata: result.metadata,
+      };
+    case 'titles':
+      return {
+        ...shapeResultForVerbosity(result, 'urls_only'),
+        ...(result.title ? { title: result.title } : {}),
+        ...(result.displayUrl ? { displayUrl: result.displayUrl } : {}),
+      };
+    case 'snippets':
+      return {
+        ...shapeResultForVerbosity(result, 'titles'),
+        ...(result.snippet ? { snippet: result.snippet } : {}),
+      };
+    default:
+      return result;
+  }
+}
+
+export class WebSearchService {
+  private readonly fetchRuntime = new FetchRuntimeService();
+
+  constructor(
+    private readonly registry: WebSearchProviderRegistry,
+    private readonly fetchDeps: FetchRuntimeDeps = {},
+  ) {}
+
+  async getStatus(): Promise<WebSearchServiceStatus> {
+    const providers = this.registry.list();
+    return {
+      enabled: providers.length > 0,
+      providerCount: providers.length,
+      providers,
+      note: 'Web search uses provider-backed discovery and normalizes results before they reach the model.',
+    };
+  }
+
+  async search(request: WebSearchRequest): Promise<WebSearchResponse> {
+    const provider = this.registry.find(request.providerId);
+    if (!provider) {
+      throw new Error(request.providerId ? `Web search provider unavailable: ${request.providerId}` : 'No web search provider is registered');
+    }
+
+    const verbosity = request.verbosity ?? 'snippets';
+    const baseResponse = await provider.search(request);
+    const evidenceEnabled = request.includeEvidence || verbosity === 'evidence' || verbosity === 'full';
+    const resultsWithEvidence = evidenceEnabled
+      ? await this.attachEvidence(baseResponse.results, request)
+      : baseResponse.results;
+    const shapedResults = resultsWithEvidence.map((result) => shapeResultForVerbosity(result, verbosity));
+
+    return {
+      providerId: provider.id,
+      providerLabel: provider.label,
+      query: request.query,
+      verbosity,
+      results: shapedResults,
+      ...(baseResponse.instantAnswer ? { instantAnswer: baseResponse.instantAnswer } : {}),
+      metadata: baseResponse.metadata,
+    };
+  }
+
+  private async attachEvidence(results: readonly WebSearchResult[], request: WebSearchRequest): Promise<readonly WebSearchResult[]> {
+    const evidenceTopN = Math.max(1, Math.min(10, request.evidenceTopN ?? 3));
+    const extract = selectEvidenceExtract(request, request.verbosity ?? 'snippets');
+    const selectedIndexes = results
+      .map((result, index) => ({ result, index }))
+      .filter(({ result, index }) => index < evidenceTopN && (!result.evidence || result.evidence.length === 0));
+    if (selectedIndexes.length === 0) return results;
+
+    const fetched = await this.fetchRuntime.execute({
+      urls: selectedIndexes.map(({ result }) => ({
+        url: result.url,
+        extract,
+        max_content_length: extract === 'readable' ? 20_000 : 10_000,
+      })),
+      parallel: true,
+      verbosity: 'standard',
+      sanitize_mode: 'safe-text',
+      ...(request.trustedHosts ? { trusted_hosts: [...request.trustedHosts] } : {}),
+      ...(request.blockedHosts ? { blocked_hosts: [...request.blockedHosts] } : {}),
+    }, this.fetchDeps);
+
+    const evidenceByUrl = new Map<string, WebSearchEvidence>();
+    for (const result of fetched.results ?? []) {
+      if (!result.content || result.error) continue;
+      evidenceByUrl.set(result.url, {
+        url: result.final_url ?? result.url,
+        extract,
+        content: result.content,
+        tokensUsed: result.tokens_used ?? Math.ceil(result.content.length / 4),
+        ...(result.status ? { status: result.status } : {}),
+        ...(result.contentType ? { contentType: result.contentType } : {}),
+        ...(result.truncated ? { truncated: true } : {}),
+        metadata: {
+          redirected: result.redirected ?? false,
+        },
+      });
+    }
+
+    return results.map((result) => {
+      const evidence = evidenceByUrl.get(result.url);
+      if (!evidence) return result;
+      return {
+        ...result,
+        evidence: [...(result.evidence ?? []), evidence],
+      };
+    });
+  }
+}

package/src/widget/index.ts

@@ -0,0 +1,2 @@
+export * from './widget.ts';
+export * from './types.ts';

package/src/widget/types.ts

@@ -0,0 +1,9 @@
+export interface Widget {
+  id: string;
+  name: string;
+}
+
+export interface WidgetInput {
+  name: string;
+  // add more fields as needed
+}

package/src/widget/widget.ts

@@ -0,0 +1,8 @@
+import type { Widget, WidgetInput } from './types.ts';
+
+export function createWidget(input: WidgetInput): Widget {
+    // Simple implementation: generate a random id and spread input
+  return { id: crypto.randomUUID(), ...input };
+
+  throw new Error('Not implemented');
+}