@effect-x/ultimate-search 0.1.2 → 0.1.4

package/src/config/settings.ts

@@ -0,0 +1,261 @@
+import { Config, Effect, Layer, Option, ServiceMap } from "effect";
+import { ConfigValidationError, type UltimateSearchError } from "../shared/errors";
+import type { ServicesReturns } from "../shared/effect";
+import {
+  optionalAbsoluteUrlStringFromStringSchema,
+  optionalTrimmedNonEmptyStringFromStringSchema,
+} from "../shared/schema";
+
+export interface ProviderEnvironment {
+  readonly apiUrl: Option.Option<string>;
+  readonly apiKey: Option.Option<string>;
+}
+
+export interface GrokEnvironment extends ProviderEnvironment {
+  readonly model: string;
+}
+
+export interface FirecrawlEnvironment {
+  readonly apiUrl: string;
+  readonly apiKey: Option.Option<string>;
+}
+
+export interface UltimateSearchSettings {
+  readonly grok: GrokEnvironment;
+  readonly tavily: ProviderEnvironment;
+  readonly firecrawl: FirecrawlEnvironment;
+}
+
+export interface GrokProviderConfig {
+  readonly apiUrl: string;
+  readonly apiKey: string;
+  readonly model: string;
+}
+
+export interface TavilyProviderConfig {
+  readonly apiUrl: string;
+  readonly apiKey: string;
+}
+
+export interface FirecrawlProviderConfig {
+  readonly apiUrl: string;
+  readonly apiKey: string;
+}
+
+export class UltimateSearchConfig extends ServiceMap.Service<
+  UltimateSearchConfig,
+  {
+    readonly settings: UltimateSearchSettings;
+    readonly getGrokConfig: () => Effect.Effect<GrokProviderConfig, UltimateSearchError>;
+    readonly getTavilyConfig: () => Effect.Effect<TavilyProviderConfig, UltimateSearchError>;
+    readonly getFirecrawlConfig: () => Effect.Effect<FirecrawlProviderConfig, UltimateSearchError>;
+  }
+>()("UltimateSearchConfig") {
+  static readonly layer = Layer.effect(
+    UltimateSearchConfig,
+    Effect.gen(function* () {
+      const settings: UltimateSearchConfig.Methods["settings"] = yield* loadSettings.pipe(
+        Effect.withSpan("UltimateSearchConfig.settings"),
+      );
+
+      const getGrokConfig: UltimateSearchConfig.Methods["getGrokConfig"] = Effect.fn(
+        "UltimateSearchConfig.getGrokConfig",
+      )(function* (): Effect.fn.Return<GrokProviderConfig, ConfigValidationError, never> {
+        const grok = yield* strictConfigEffect(grokEnvironmentConfig);
+        const details: Array<string> = [];
+
+        if (Option.isNone(grok.apiUrl)) {
+          details.push("Set GROK_API_URL to the grok base URL.");
+        }
+
+        if (Option.isNone(grok.apiKey)) {
+          details.push("Set GROK_API_KEY to the grok bearer token.");
+        }
+
+        if (details.length > 0) {
+          return yield* new ConfigValidationError({
+            provider: "grok",
+            message: "Missing required Grok configuration.",
+            details,
+          });
+        }
+
+        return {
+          apiUrl: Option.getOrElse(grok.apiUrl, () => ""),
+          apiKey: Option.getOrElse(grok.apiKey, () => ""),
+          model: grok.model,
+        } satisfies GrokProviderConfig;
+      });
+
+      const getTavilyConfig: UltimateSearchConfig.Methods["getTavilyConfig"] = Effect.fn(
+        "UltimateSearchConfig.getTavilyConfig",
+      )(function* (): Effect.fn.Return<TavilyProviderConfig, ConfigValidationError, never> {
+        const tavily = yield* strictConfigEffect(tavilyEnvironmentConfig);
+        const details: Array<string> = [];
+
+        if (Option.isNone(tavily.apiUrl)) {
+          details.push("Set TAVILY_API_URL to the Tavily or Tavily proxy base URL.");
+        }
+
+        if (Option.isNone(tavily.apiKey)) {
+          details.push("Set TAVILY_API_KEY to the Tavily or Tavily proxy bearer token.");
+        }
+
+        if (details.length > 0) {
+          return yield* new ConfigValidationError({
+            provider: "tavily",
+            message: "Missing required Tavily configuration.",
+            details,
+          });
+        }
+
+        return {
+          apiUrl: Option.getOrElse(tavily.apiUrl, () => ""),
+          apiKey: Option.getOrElse(tavily.apiKey, () => ""),
+        } satisfies TavilyProviderConfig;
+      });
+
+      const getFirecrawlConfig: UltimateSearchConfig.Methods["getFirecrawlConfig"] = Effect.fn(
+        "UltimateSearchConfig.getFirecrawlConfig",
+      )(function* (): Effect.fn.Return<FirecrawlProviderConfig, ConfigValidationError, never> {
+        const firecrawl = yield* strictConfigEffect(firecrawlEnvironmentConfig);
+
+        if (Option.isNone(firecrawl.apiKey)) {
+          return yield* new ConfigValidationError({
+            provider: "firecrawl",
+            message: "Missing required FireCrawl configuration.",
+            details: ["Set FIRECRAWL_API_KEY to the FireCrawl bearer token."],
+          });
+        }
+
+        return {
+          apiUrl: firecrawl.apiUrl,
+          apiKey: Option.getOrElse(firecrawl.apiKey, () => ""),
+        } satisfies FirecrawlProviderConfig;
+      });
+
+      return UltimateSearchConfig.of({
+        settings,
+        getGrokConfig,
+        getTavilyConfig,
+        getFirecrawlConfig,
+      });
+    }),
+  );
+}
+
+export declare namespace UltimateSearchConfig {
+  export type Methods = ServiceMap.Service.Shape<typeof UltimateSearchConfig>;
+  export type Returns<key extends keyof Methods, R = never> = ServicesReturns<Methods[key], R>;
+}
+
+const optionalUrlConfig = (name: string) =>
+  Config.schema(
+    optionalAbsoluteUrlStringFromStringSchema(`${name} must be an absolute URL.`),
+    name,
+  ).pipe(Config.withDefault(Option.none<string>()));
+
+const optionalSecretConfig = (name: string) =>
+  Config.schema(optionalTrimmedNonEmptyStringFromStringSchema, name).pipe(
+    Config.withDefault(Option.none<string>()),
+  );
+
+const requiredTextConfig = (name: string, fallback: string) =>
+  Config.schema(optionalTrimmedNonEmptyStringFromStringSchema, name).pipe(
+    Config.withDefault(Option.none<string>()),
+    Config.map(Option.getOrElse(() => fallback)),
+  );
+
+const requiredUrlConfig = (name: string, fallback: string) =>
+  Config.schema(
+    optionalAbsoluteUrlStringFromStringSchema(`${name} must be an absolute URL.`),
+    name,
+  ).pipe(Config.withDefault(Option.none<string>()), Config.map(Option.getOrElse(() => fallback)));
+
+const grokEnvironmentConfig = Config.all({
+  apiUrl: optionalUrlConfig("GROK_API_URL"),
+  apiKey: optionalSecretConfig("GROK_API_KEY"),
+  model: requiredTextConfig("GROK_MODEL", "grok-4.1-fast"),
+}) satisfies Config.Config<GrokEnvironment>;
+
+const tavilyEnvironmentConfig = Config.all({
+  apiUrl: optionalUrlConfig("TAVILY_API_URL"),
+  apiKey: optionalSecretConfig("TAVILY_API_KEY"),
+}) satisfies Config.Config<ProviderEnvironment>;
+
+const firecrawlEnvironmentConfig = Config.all({
+  apiUrl: requiredUrlConfig("FIRECRAWL_API_URL", "https://api.firecrawl.dev/v2"),
+  apiKey: optionalSecretConfig("FIRECRAWL_API_KEY"),
+}) satisfies Config.Config<FirecrawlEnvironment>;
+
+const defaultGrokEnvironment: GrokEnvironment = {
+  apiUrl: Option.none(),
+  apiKey: Option.none(),
+  model: "grok-4.1-fast",
+};
+
+const defaultTavilyEnvironment: ProviderEnvironment = {
+  apiUrl: Option.none(),
+  apiKey: Option.none(),
+};
+
+const defaultFirecrawlEnvironment: FirecrawlEnvironment = {
+  apiUrl: "https://api.firecrawl.dev/v2",
+  apiKey: Option.none(),
+};
+
+const mapConfigLoadError = (error: unknown) =>
+  new ConfigValidationError({
+    provider: "shared",
+    message: "Failed to load CLI configuration.",
+    details: configErrorDetails(error),
+    cause: error,
+  });
+
+const strictConfigEffect = <A>(config: Config.Config<A>) =>
+  config
+    .asEffect()
+    .pipe(Effect.mapError(mapConfigLoadError), Effect.withSpan("UltimateSearchConfig.settings"));
+
+const bestEffortConfigEffect = <A>(config: Config.Config<A>, fallback: A) =>
+  strictConfigEffect(config).pipe(Effect.catch(() => Effect.succeed(fallback)));
+
+const loadSettings = Effect.all({
+  grok: bestEffortConfigEffect(grokEnvironmentConfig, defaultGrokEnvironment),
+  tavily: bestEffortConfigEffect(tavilyEnvironmentConfig, defaultTavilyEnvironment),
+  firecrawl: bestEffortConfigEffect(firecrawlEnvironmentConfig, defaultFirecrawlEnvironment),
+}) satisfies Effect.Effect<UltimateSearchSettings, never, never>;
+
+const configErrorDetails = (error: unknown): Array<string> => {
+  if (error instanceof Config.ConfigError && error.message.length > 0) {
+    return [error.message];
+  }
+
+  if (error instanceof Error && error.message.length > 0) {
+    return [error.message];
+  }
+
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof error.message === "string" &&
+    error.message.length > 0
+  ) {
+    return [error.message];
+  }
+
+  if (typeof error === "string" && error.length > 0) {
+    return [error];
+  }
+
+  if (error != null) {
+    const text = String(error);
+
+    if (text.length > 0 && text !== "[object Object]") {
+      return [text];
+    }
+  }
+
+  return [];
+};

package/src/providers/firecrawl/client.ts

@@ -0,0 +1,75 @@
+import { Effect, Layer, Schema, ServiceMap } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { UltimateSearchConfig } from "../../config/settings";
+import type { ServicesReturns } from "../../shared/effect";
+import { ProviderDecodeError, type UltimateSearchError } from "../../shared/errors";
+import {
+  catchProviderHttpError,
+  decodeJsonResponse,
+  makeProviderHttpClient,
+} from "../../shared/provider-http-client";
+import {
+  type FirecrawlScrapeRequest,
+  FirecrawlScrapeResponseSchema,
+  type FirecrawlScrapeResponse,
+} from "./schema";
+
+const decodeFirecrawlScrapeResponse = Schema.decodeUnknownEffect(FirecrawlScrapeResponseSchema);
+
+const mapDecodeError = (error: unknown, fallback: string) =>
+  new ProviderDecodeError({
+    provider: "firecrawl",
+    message: error instanceof Error ? error.message : fallback,
+    cause: error,
+  });
+
+export class FirecrawlProviderClient extends ServiceMap.Service<
+  FirecrawlProviderClient,
+  {
+    readonly scrape: (
+      request: FirecrawlScrapeRequest,
+    ) => Effect.Effect<FirecrawlScrapeResponse, UltimateSearchError, never>;
+  }
+>()("FirecrawlProviderClient") {
+  static readonly layer = Layer.effect(
+    FirecrawlProviderClient,
+    Effect.gen(function* () {
+      const config = yield* UltimateSearchConfig;
+      const http = makeProviderHttpClient(yield* HttpClient.HttpClient);
+
+      const scrape: FirecrawlProviderClient.Methods["scrape"] = Effect.fn(
+        "FirecrawlProviderClient.scrape",
+      )(function* (payload): FirecrawlProviderClient.Returns<"scrape"> {
+        const firecrawl = yield* config.getFirecrawlConfig();
+        const request = HttpClientRequest.post(`${firecrawl.apiUrl}/scrape`).pipe(
+          HttpClientRequest.acceptJson,
+          HttpClientRequest.bearerToken(firecrawl.apiKey),
+          HttpClientRequest.bodyJsonUnsafe(payload),
+        );
+
+        const response = yield* http
+          .execute(request)
+          .pipe(
+            catchProviderHttpError(
+              "firecrawl",
+              "Failed to send the FireCrawl request.",
+              (status: number) => `FireCrawl returned HTTP ${status}.`,
+            ),
+          );
+
+        return yield* decodeJsonResponse(response, decodeFirecrawlScrapeResponse, (error) =>
+          mapDecodeError(error, "Failed to decode the FireCrawl response payload."),
+        );
+      });
+
+      return FirecrawlProviderClient.of({
+        scrape,
+      });
+    }),
+  );
+}
+
+export declare namespace FirecrawlProviderClient {
+  export type Methods = ServiceMap.Service.Shape<typeof FirecrawlProviderClient>;
+  export type Returns<key extends keyof Methods, R = never> = ServicesReturns<Methods[key], R>;
+}

package/src/providers/firecrawl/schema.ts

@@ -0,0 +1,31 @@
+import { Schema } from "effect";
+
+export const FirecrawlFormatSchema = Schema.Literals(["markdown"] as const);
+
+export type FirecrawlFormat = typeof FirecrawlFormatSchema.Type;
+
+export const FirecrawlScrapeRequestSchema = Schema.Struct({
+  url: Schema.String,
+  formats: Schema.NonEmptyArray(FirecrawlFormatSchema),
+});
+
+export type FirecrawlScrapeRequest = typeof FirecrawlScrapeRequestSchema.Type;
+
+export const FirecrawlScrapeResponseSchema = Schema.Struct({
+  success: Schema.optional(Schema.Boolean),
+  data: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        markdown: Schema.optional(Schema.NullOr(Schema.String)),
+        content: Schema.optional(Schema.NullOr(Schema.String)),
+        metadata: Schema.optional(
+          Schema.Struct({
+            title: Schema.optional(Schema.NullOr(Schema.String)),
+          }),
+        ),
+      }),
+    ),
+  ),
+});
+
+export type FirecrawlScrapeResponse = typeof FirecrawlScrapeResponseSchema.Type;

package/src/providers/grok/client.ts

@@ -0,0 +1,77 @@
+import { Effect, Layer, Schema, ServiceMap } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { UltimateSearchConfig } from "../../config/settings";
+import type { ServicesReturns } from "../../shared/effect";
+import { ProviderDecodeError, type UltimateSearchError } from "../../shared/errors";
+import {
+  catchProviderHttpError,
+  decodeJsonResponse,
+  makeProviderHttpClient,
+} from "../../shared/provider-http-client";
+import {
+  type GrokChatCompletionRequest,
+  GrokChatCompletionResponseSchema,
+  type GrokChatCompletionResponse,
+} from "./schema";
+
+const decodeGrokChatCompletionResponse = Schema.decodeUnknownEffect(
+  GrokChatCompletionResponseSchema,
+);
+
+const mapDecodeError = (error: unknown, fallback: string) =>
+  new ProviderDecodeError({
+    provider: "grok",
+    message: error instanceof Error ? error.message : fallback,
+    cause: error,
+  });
+
+export class GrokProviderClient extends ServiceMap.Service<
+  GrokProviderClient,
+  {
+    readonly createChatCompletion: (
+      request: GrokChatCompletionRequest,
+    ) => Effect.Effect<GrokChatCompletionResponse, UltimateSearchError, never>;
+  }
+>()("GrokProviderClient") {
+  static readonly layer = Layer.effect(
+    GrokProviderClient,
+    Effect.gen(function* () {
+      const config = yield* UltimateSearchConfig;
+      const http = makeProviderHttpClient(yield* HttpClient.HttpClient);
+
+      const createChatCompletion: GrokProviderClient.Methods["createChatCompletion"] = Effect.fn(
+        "GrokProviderClient.createChatCompletion",
+      )(function* (payload): GrokProviderClient.Returns<"createChatCompletion"> {
+        const grok = yield* config.getGrokConfig();
+        const request = HttpClientRequest.post(`${grok.apiUrl}/v1/chat/completions`).pipe(
+          HttpClientRequest.acceptJson,
+          HttpClientRequest.bearerToken(grok.apiKey),
+          HttpClientRequest.bodyJsonUnsafe(payload),
+        );
+
+        const response = yield* http
+          .execute(request)
+          .pipe(
+            catchProviderHttpError(
+              "grok",
+              "Failed to send the Grok request.",
+              (status: number) => `Grok returned HTTP ${status}.`,
+            ),
+          );
+
+        return yield* decodeJsonResponse(response, decodeGrokChatCompletionResponse, (error) =>
+          mapDecodeError(error, "Failed to decode the Grok response payload."),
+        );
+      });
+
+      return GrokProviderClient.of({
+        createChatCompletion,
+      });
+    }),
+  );
+}
+
+export declare namespace GrokProviderClient {
+  export type Methods = ServiceMap.Service.Shape<typeof GrokProviderClient>;
+  export type Returns<key extends keyof Methods, R = never> = ServicesReturns<Methods[key], R>;
+}

package/src/providers/grok/schema.ts

@@ -0,0 +1,107 @@
+import { Option, Schema } from "effect";
+import { trimmedNonEmptyStringSchema } from "../../shared/schema";
+
+export const GrokUsageSchema = Schema.Struct({
+  prompt_tokens: Schema.Number,
+  completion_tokens: Schema.Number,
+  total_tokens: Schema.Number,
+});
+
+export type GrokUsage = typeof GrokUsageSchema.Type;
+
+export const GrokMessageSchema = Schema.Struct({
+  role: Schema.Literals(["system", "user", "assistant"] as const),
+  content: Schema.String,
+});
+
+export type GrokMessage = typeof GrokMessageSchema.Type;
+
+export const GrokChatCompletionRequestSchema = Schema.Struct({
+  model: Schema.NonEmptyString,
+  stream: Schema.Boolean,
+  messages: Schema.NonEmptyArray(GrokMessageSchema),
+});
+
+export type GrokChatCompletionRequest = typeof GrokChatCompletionRequestSchema.Type;
+
+export const GrokChatCompletionResponseSchema = Schema.Struct({
+  model: Schema.String,
+  choices: Schema.NonEmptyArray(
+    Schema.Struct({
+      message: GrokMessageSchema,
+    }),
+  ),
+  usage: GrokUsageSchema,
+});
+
+export type GrokChatCompletionResponse = typeof GrokChatCompletionResponseSchema.Type;
+
+export class GrokSearchInput extends Schema.Class<GrokSearchInput>("GrokSearchInput")({
+  query: trimmedNonEmptyStringSchema("query must be a non-empty string"),
+  platform: Schema.Option(Schema.NonEmptyString),
+  model: Schema.Option(Schema.NonEmptyString),
+}) {
+  static decodeEffect = Schema.decodeUnknownEffect(GrokSearchInput);
+}
+
+export interface GrokSearchResult {
+  readonly content: string;
+  readonly model: string;
+  readonly usage: GrokUsage;
+}
+
+export const GrokSearchResultSchema = Schema.Struct({
+  content: Schema.String,
+  model: Schema.String,
+  usage: GrokUsageSchema,
+});
+
+const timeSensitivePattern =
+  /今天|最新|当前|latest|recent|today|current|now|这几天|本周|本月|近期|最近/iu;
+
+export const grokSystemPrompt = `# Core Instruction
+
+1. User needs may be vague. Think divergently, infer intent from multiple angles, and leverage full conversation context to progressively clarify their true needs.
+2. **Breadth-First Search**—Approach problems from multiple dimensions. Brainstorm 5+ perspectives and execute parallel searches for each. Consult as many high-quality sources as possible before responding.
+3. **Depth-First Search**—After broad exploration, select ≥2 most relevant perspectives for deep investigation into specialized knowledge.
+4. **Evidence-Based Reasoning & Traceable Sources**—Every claim must be followed by a citation. More credible sources strengthen arguments. If no references exist, remain silent.
+5. Before responding, ensure full execution of Steps 1–4.
+
+# Search Instruction
+
+1. Think carefully before responding—anticipate the user's true intent to ensure precision.
+2. Verify every claim rigorously to avoid misinformation.
+3. Follow problem logic—dig deeper until clues are exhaustively clear. Use multiple parallel tool calls per query and ensure answers are well-sourced.
+4. Search in English first (prioritizing English resources for volume/quality), but switch to Chinese if context demands.
+5. Prioritize authoritative sources: Wikipedia, academic databases, books, reputable media/journalism.
+6. Favor sharing in-depth, specialized knowledge over generic or common-sense content.
+
+# Output Style
+
+1. Lead with the **most probable solution** before detailed analysis.
+2. **Define every technical term** in plain language.
+3. **Respect facts and search results—use statistical rigor to discern truth**.
+4. **Every sentence must cite sources**. More references = stronger credibility.
+5. **Strictly format outputs in polished Markdown**.`;
+
+const withCurrentTimeContext = (query: string) => {
+  if (!timeSensitivePattern.test(query)) {
+    return query;
+  }
+
+  return `[Current date and time: ${new Date().toISOString()}]
+
+${query}`;
+};
+
+export const buildGrokUserMessage = (input: GrokSearchInput) => {
+  const baseMessage = withCurrentTimeContext(input.query);
+
+  return Option.match(input.platform, {
+    onNone: () => baseMessage,
+    onSome: (platform) =>
+      `${baseMessage}
+
+You should focus on these platform: ${platform}`,
+  });
+};

package/src/providers/tavily/client.ts

@@ -0,0 +1,143 @@
+import { Effect, Layer, Schema, ServiceMap } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { UltimateSearchConfig } from "../../config/settings";
+import type { ServicesReturns } from "../../shared/effect";
+import { ProviderDecodeError, type UltimateSearchError } from "../../shared/errors";
+import {
+  catchProviderHttpError,
+  decodeJsonResponse,
+  makeProviderHttpClient,
+} from "../../shared/provider-http-client";
+import {
+  type TavilyMapRequest,
+  TavilyMapResponseSchema,
+  type TavilyMapResponse,
+  type TavilyExtractRequest,
+  TavilyExtractResponseSchema,
+  type TavilyExtractResponse,
+  type TavilySearchRequest,
+  TavilySearchResponseSchema,
+  type TavilySearchResponse,
+} from "./schema";
+
+const decodeTavilySearchResponse = Schema.decodeUnknownEffect(TavilySearchResponseSchema);
+
+const decodeTavilyMapResponse = Schema.decodeUnknownEffect(TavilyMapResponseSchema);
+
+const decodeTavilyExtractResponse = Schema.decodeUnknownEffect(TavilyExtractResponseSchema);
+
+const mapDecodeError = (error: unknown, fallback: string) =>
+  new ProviderDecodeError({
+    provider: "tavily",
+    message: error instanceof Error ? error.message : fallback,
+    cause: error,
+  });
+
+export class TavilyProviderClient extends ServiceMap.Service<
+  TavilyProviderClient,
+  {
+    readonly search: (
+      request: TavilySearchRequest,
+    ) => Effect.Effect<TavilySearchResponse, UltimateSearchError, never>;
+    readonly map: (
+      request: TavilyMapRequest,
+    ) => Effect.Effect<TavilyMapResponse, UltimateSearchError, never>;
+    readonly extract: (
+      request: TavilyExtractRequest,
+    ) => Effect.Effect<TavilyExtractResponse, UltimateSearchError, never>;
+  }
+>()("TavilyProviderClient") {
+  static readonly layer = Layer.effect(
+    TavilyProviderClient,
+    Effect.gen(function* () {
+      const config = yield* UltimateSearchConfig;
+      const http = makeProviderHttpClient(yield* HttpClient.HttpClient);
+
+      const search: TavilyProviderClient.Methods["search"] = Effect.fn(
+        "TavilyProviderClient.search",
+      )(function* (payload): TavilyProviderClient.Returns<"search"> {
+        const tavily = yield* config.getTavilyConfig();
+        const request = HttpClientRequest.post(`${tavily.apiUrl}/search`).pipe(
+          HttpClientRequest.acceptJson,
+          HttpClientRequest.bearerToken(tavily.apiKey),
+          HttpClientRequest.bodyJsonUnsafe(payload),
+        );
+
+        const response = yield* http
+          .execute(request)
+          .pipe(
+            catchProviderHttpError(
+              "tavily",
+              "Failed to send the Tavily request.",
+              (status: number) => `Tavily returned HTTP ${status}.`,
+            ),
+          );
+
+        return yield* decodeJsonResponse(response, decodeTavilySearchResponse, (error) =>
+          mapDecodeError(error, "Failed to decode the Tavily response payload."),
+        );
+      });
+
+      const map: TavilyProviderClient.Methods["map"] = Effect.fn("TavilyProviderClient.map")(
+        function* (payload): TavilyProviderClient.Returns<"map"> {
+          const tavily = yield* config.getTavilyConfig();
+          const request = HttpClientRequest.post(`${tavily.apiUrl}/map`).pipe(
+            HttpClientRequest.acceptJson,
+            HttpClientRequest.bearerToken(tavily.apiKey),
+            HttpClientRequest.bodyJsonUnsafe(payload),
+          );
+
+          const response = yield* http
+            .execute(request)
+            .pipe(
+              catchProviderHttpError(
+                "tavily",
+                "Failed to send the Tavily map request.",
+                (status: number) => `Tavily map returned HTTP ${status}.`,
+              ),
+            );
+
+          return yield* decodeJsonResponse(response, decodeTavilyMapResponse, (error) =>
+            mapDecodeError(error, "Failed to decode the Tavily map response payload."),
+          );
+        },
+      );
+
+      const extract: TavilyProviderClient.Methods["extract"] = Effect.fn(
+        "TavilyProviderClient.extract",
+      )(function* (payload): TavilyProviderClient.Returns<"extract"> {
+        const tavily = yield* config.getTavilyConfig();
+        const request = HttpClientRequest.post(`${tavily.apiUrl}/extract`).pipe(
+          HttpClientRequest.acceptJson,
+          HttpClientRequest.bearerToken(tavily.apiKey),
+          HttpClientRequest.bodyJsonUnsafe(payload),
+        );
+
+        const response = yield* http
+          .execute(request)
+          .pipe(
+            catchProviderHttpError(
+              "tavily",
+              "Failed to send the Tavily extract request.",
+              (status: number) => `Tavily returned HTTP ${status}.`,
+            ),
+          );
+
+        return yield* decodeJsonResponse(response, decodeTavilyExtractResponse, (error) =>
+          mapDecodeError(error, "Failed to decode the Tavily extract payload."),
+        );
+      });
+
+      return TavilyProviderClient.of({
+        map,
+        search,
+        extract,
+      });
+    }),
+  );
+}
+
+export declare namespace TavilyProviderClient {
+  export type Methods = ServiceMap.Service.Shape<typeof TavilyProviderClient>;
+  export type Returns<key extends keyof Methods, R = never> = ServicesReturns<Methods[key], R>;
+}