@effect-uai/exa 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Betalyra Sociedade Unipessoal Lda.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/ExaSearch.d.mts

@@ -0,0 +1,49 @@
+import { ExaCategory, ExaSearchType } from "./models.mjs";
+import { Context, Effect, Layer, Redacted } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import * as AiError from "@effect-uai/core/AiError";
+import { CommonSearchRequest, SearchResponse, WebSearch } from "@effect-uai/core/WebSearch";
+
+//#region src/ExaSearch.d.ts
+declare namespace ExaSearch_d_exports {
+  export { Config, ExaSearch, ExaSearchRequest, ExaSearchService, layer, make };
+}
+/**
+ * Exa-typed search request. Widens {@link CommonSearchRequest} with Exa's
+ * own knobs; the common fields map onto Exa's wire filters (see the codec
+ * below). There is no `model` - `/search` ranks the web directly, with
+ * `type` choosing the retrieval strategy.
+ */
+type ExaSearchRequest = CommonSearchRequest & {
+  /** Retrieval strategy - see {@link ExaSearchType}. Defaults to `auto`. */readonly type?: ExaSearchType; /** Content-vertical filter - see {@link ExaCategory}. */
+  readonly category?: ExaCategory;
+};
+type ExaSearchService = {
+  readonly search: (request: ExaSearchRequest) => Effect.Effect<SearchResponse, AiError.AiError>;
+};
+declare const ExaSearch_base: Context.ServiceClass<ExaSearch, "@betalyra/effect-uai/providers/exa/ExaSearch", ExaSearchService>;
+/**
+ * Provider-typed service tag. Yield this for Exa-typed search (`type`,
+ * `category`, the per-result `score`); yield the generic `WebSearch` tag
+ * for provider-portable code. Both are registered by {@link layer}.
+ */
+declare class ExaSearch extends ExaSearch_base {}
+type Config = {
+  readonly apiKey: Redacted.Redacted;
+  readonly baseUrl?: string;
+};
+/**
+ * Build an `ExaSearchService` value. For Layer-based setup, prefer
+ * {@link layer}.
+ */
+declare const make: (cfg: Config) => Effect.Effect<ExaSearchService, never, HttpClient.HttpClient>;
+/**
+ * Layer registering both the provider-typed `ExaSearch` tag and the
+ * generic `WebSearch` tag over one implementation. A `CommonSearchRequest`
+ * is structurally an `ExaSearchRequest` with `type` / `category` unset, so
+ * the generic registration forwards directly.
+ */
+declare const layer: (cfg: Config) => Layer.Layer<ExaSearch | WebSearch, never, HttpClient.HttpClient>;
+//#endregion
+export { Config, ExaSearch, ExaSearchRequest, ExaSearchService, layer, make, ExaSearch_d_exports as t };
+//# sourceMappingURL=ExaSearch.d.mts.map

package/dist/ExaSearch.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExaSearch.d.mts","names":[],"sources":["../src/ExaSearch.ts"],"mappings":";;;;;;;;;;;;;;;;KAwBY,gBAAA,GAAmB,mBAAA;qFAEpB,IAAA,GAAO,aAAA;WAEP,QAAA,GAAW,WAAA;AAAA;AAAA,KAGV,gBAAA;EAAA,SACD,MAAA,GAAS,OAAA,EAAS,gBAAA,KAAqB,MAAA,CAAO,MAAA,CAAO,cAAA,EAAgB,OAAA,CAAQ,OAAA;AAAA;AAAA,cACvF,cAAA;;;;;;cAOY,SAAA,SAAkB,cAAA;AAAA,KAInB,MAAA;EAAA,SACD,MAAA,EAAQ,QAAA,CAAS,QAAA;EAAA,SACjB,OAAA;AAAA;;;;;cA4KE,IAAA,GAAQ,GAAA,EAAK,MAAA,KAAS,MAAA,CAAO,MAAA,CAAO,gBAAA,SAAyB,UAAA,CAAW,UAAA;;;;;;;cAYxE,KAAA,GACX,GAAA,EAAK,MAAA,KACJ,KAAA,CAAM,KAAA,CAAM,SAAA,GAAY,SAAA,SAAkB,UAAA,CAAW,UAAA"}

package/dist/ExaSearch.mjs

@@ -0,0 +1,150 @@
+import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
+import { Context, DateTime, Effect, Layer, Option, Redacted, Schema } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import * as AiError from "@effect-uai/core/AiError";
+import * as Capabilities from "@effect-uai/core/Capabilities";
+import { WebSearch } from "@effect-uai/core/WebSearch";
+//#region src/ExaSearch.ts
+var ExaSearch_exports = /* @__PURE__ */ __exportAll({
+	ExaSearch: () => ExaSearch,
+	layer: () => layer,
+	make: () => make
+});
+/**
+* Provider-typed service tag. Yield this for Exa-typed search (`type`,
+* `category`, the per-result `score`); yield the generic `WebSearch` tag
+* for provider-portable code. Both are registered by {@link layer}.
+*/
+var ExaSearch = class extends Context.Service()("@betalyra/effect-uai/providers/exa/ExaSearch") {};
+const recencyDuration = {
+	hour: "1 hour",
+	day: "1 day",
+	week: "7 days",
+	month: "30 days",
+	year: "365 days"
+};
+const buildBody = (request, now) => {
+	const startPublishedDate = request.startDate !== void 0 ? DateTime.formatIso(request.startDate) : request.recency !== void 0 ? DateTime.formatIso(DateTime.subtractDuration(now, recencyDuration[request.recency])) : void 0;
+	return {
+		query: request.query,
+		...request.maxResults !== void 0 && { numResults: request.maxResults },
+		...request.type !== void 0 && { type: request.type },
+		...request.category !== void 0 && { category: request.category },
+		...request.includeDomains !== void 0 && { includeDomains: request.includeDomains },
+		...request.excludeDomains !== void 0 && { excludeDomains: request.excludeDomains },
+		...startPublishedDate !== void 0 && { startPublishedDate },
+		...request.endDate !== void 0 && { endPublishedDate: DateTime.formatIso(request.endDate) },
+		...request.country !== void 0 && { userLocation: request.country }
+	};
+};
+const WireResult = Schema.Struct({
+	id: Schema.optional(Schema.String),
+	url: Schema.String,
+	title: Schema.optional(Schema.NullOr(Schema.String)),
+	score: Schema.optional(Schema.Number),
+	publishedDate: Schema.optional(Schema.NullOr(Schema.String)),
+	author: Schema.optional(Schema.NullOr(Schema.String))
+});
+const WireCost = Schema.Struct({ total: Schema.optional(Schema.Number) });
+const WireResponse = Schema.Struct({
+	requestId: Schema.optional(Schema.String),
+	results: Schema.Array(WireResult),
+	costDollars: Schema.optional(WireCost)
+});
+/** Lenient parse of Exa's ISO date strings; unparseable -> omitted. */
+const parseDate = (s) => s == null ? void 0 : Option.getOrUndefined(DateTime.make(s));
+const toResult = (r) => {
+	const publishedDate = parseDate(r.publishedDate);
+	return {
+		url: r.url,
+		...r.title != null && { title: r.title },
+		...r.score !== void 0 && { score: r.score },
+		...publishedDate !== void 0 && { publishedDate },
+		raw: r
+	};
+};
+const toResponse = (wire) => ({
+	results: wire.results.map(toResult),
+	raw: wire
+});
+const transportFailure = (cause) => new AiError.Unavailable({
+	provider: "exa",
+	raw: cause
+});
+const httpStatusError = (status, body) => {
+	const provider = "exa";
+	const raw = body;
+	if (status === 429) return new AiError.RateLimited({
+		provider,
+		raw
+	});
+	if (status === 408 || status === 504) return new AiError.Timeout({
+		provider,
+		raw
+	});
+	if (status === 401) return new AiError.AuthFailed({
+		provider,
+		subtype: "auth",
+		raw
+	});
+	if (status === 403) return new AiError.AuthFailed({
+		provider,
+		subtype: "permission",
+		raw
+	});
+	if (status === 402) return new AiError.AuthFailed({
+		provider,
+		subtype: "billing",
+		raw
+	});
+	if (status >= 500) return new AiError.Unavailable({
+		provider,
+		status,
+		raw
+	});
+	return new AiError.InvalidRequest({
+		provider,
+		raw
+	});
+};
+const baseUrl = (cfg) => cfg.baseUrl ?? "https://api.exa.ai";
+const postSearch = (cfg, body) => Effect.gen(function* () {
+	const client = yield* HttpClient.HttpClient;
+	const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/search`).pipe(HttpClientRequest.setHeader("x-api-key", Redacted.value(cfg.apiKey)), HttpClientRequest.bodyJsonUnsafe(body));
+	const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure));
+	if (response.status >= 400) {
+		const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""));
+		return yield* httpStatusError(response.status, text);
+	}
+	const json = yield* response.json.pipe(Effect.mapError(transportFailure));
+	return yield* Schema.decodeUnknownEffect(WireResponse)(json).pipe(Effect.mapError(transportFailure));
+});
+const searchImpl = (cfg) => (request) => Effect.gen(function* () {
+	yield* Capabilities.warnDroppedWhen(request.language, {
+		provider: "exa",
+		capability: "language",
+		field: "language",
+		reason: "Exa /search has no language filter; the hint is ignored."
+	});
+	return toResponse(yield* postSearch(cfg, buildBody(request, yield* DateTime.now)));
+});
+/**
+* Build an `ExaSearchService` value. For Layer-based setup, prefer
+* {@link layer}.
+*/
+const make = (cfg) => Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({ search: (request) => searchImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)) }));
+/**
+* Layer registering both the provider-typed `ExaSearch` tag and the
+* generic `WebSearch` tag over one implementation. A `CommonSearchRequest`
+* is structurally an `ExaSearchRequest` with `type` / `category` unset, so
+* the generic registration forwards directly.
+*/
+const layer = (cfg) => {
+	const typed = Layer.effect(ExaSearch, make(cfg));
+	const generic = Layer.effect(WebSearch, Effect.map(make(cfg), (s) => ({ search: (request) => s.search(request) })));
+	return Layer.merge(typed, generic);
+};
+//#endregion
+export { ExaSearch, layer, make, ExaSearch_exports as t };
+
+//# sourceMappingURL=ExaSearch.mjs.map

package/dist/ExaSearch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExaSearch.mjs","names":[],"sources":["../src/ExaSearch.ts"],"sourcesContent":["import { Context, DateTime, type Duration, Effect, Layer, Option, Redacted, Schema } from \"effect\"\nimport { HttpClient, HttpClientRequest } from \"effect/unstable/http\"\nimport * as AiError from \"@effect-uai/core/AiError\"\nimport * as Capabilities from \"@effect-uai/core/Capabilities\"\nimport {\n  type CommonSearchRequest,\n  type SearchRecency,\n  type SearchResponse,\n  type SearchResult,\n  WebSearch,\n  type WebSearchService,\n} from \"@effect-uai/core/WebSearch\"\nimport type { ExaCategory, ExaSearchType } from \"./models.js\"\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Exa-typed search request. Widens {@link CommonSearchRequest} with Exa's\n * own knobs; the common fields map onto Exa's wire filters (see the codec\n * below). There is no `model` - `/search` ranks the web directly, with\n * `type` choosing the retrieval strategy.\n */\nexport type ExaSearchRequest = CommonSearchRequest & {\n  /** Retrieval strategy - see {@link ExaSearchType}. Defaults to `auto`. */\n  readonly type?: ExaSearchType\n  /** Content-vertical filter - see {@link ExaCategory}. */\n  readonly category?: ExaCategory\n}\n\nexport type ExaSearchService = {\n  readonly search: (request: ExaSearchRequest) => Effect.Effect<SearchResponse, AiError.AiError>\n}\n\n/**\n * Provider-typed service tag. Yield this for Exa-typed search (`type`,\n * `category`, the per-result `score`); yield the generic `WebSearch` tag\n * for provider-portable code. Both are registered by {@link layer}.\n */\nexport class ExaSearch extends Context.Service<ExaSearch, ExaSearchService>()(\n  \"@betalyra/effect-uai/providers/exa/ExaSearch\",\n) {}\n\nexport type Config = {\n  readonly apiKey: Redacted.Redacted\n  readonly baseUrl?: string\n}\n\n// ---------------------------------------------------------------------------\n// Codec - request body\n// ---------------------------------------------------------------------------\n\ntype WireBody = {\n  readonly query: string\n  readonly numResults?: number\n  readonly type?: string\n  readonly category?: string\n  readonly includeDomains?: ReadonlyArray<string>\n  readonly excludeDomains?: ReadonlyArray<string>\n  readonly startPublishedDate?: string\n  readonly endPublishedDate?: string\n  readonly userLocation?: string\n}\n\n// Exa has no recency enum; map the coarse enum onto a published-after date\n// computed from \"now\" (per the capabilities policy: lossless translation).\nconst recencyDuration: Record<SearchRecency, Duration.Input> = {\n  hour: \"1 hour\",\n  day: \"1 day\",\n  week: \"7 days\",\n  month: \"30 days\",\n  year: \"365 days\",\n}\n\nconst buildBody = (request: ExaSearchRequest, now: DateTime.DateTime): WireBody => {\n  // Explicit `startDate` wins over the `recency` sugar; otherwise derive the\n  // published-after bound from the recency window.\n  const startPublishedDate =\n    request.startDate !== undefined\n      ? DateTime.formatIso(request.startDate)\n      : request.recency !== undefined\n        ? DateTime.formatIso(DateTime.subtractDuration(now, recencyDuration[request.recency]))\n        : undefined\n\n  return {\n    query: request.query,\n    ...(request.maxResults !== undefined && { numResults: request.maxResults }),\n    ...(request.type !== undefined && { type: request.type }),\n    ...(request.category !== undefined && { category: request.category }),\n    ...(request.includeDomains !== undefined && { includeDomains: request.includeDomains }),\n    ...(request.excludeDomains !== undefined && { excludeDomains: request.excludeDomains }),\n    ...(startPublishedDate !== undefined && { startPublishedDate }),\n    ...(request.endDate !== undefined && { endPublishedDate: DateTime.formatIso(request.endDate) }),\n    ...(request.country !== undefined && { userLocation: request.country }),\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Codec - response\n// ---------------------------------------------------------------------------\n\nconst WireResult = Schema.Struct({\n  id: Schema.optional(Schema.String),\n  url: Schema.String,\n  title: Schema.optional(Schema.NullOr(Schema.String)),\n  score: Schema.optional(Schema.Number),\n  publishedDate: Schema.optional(Schema.NullOr(Schema.String)),\n  author: Schema.optional(Schema.NullOr(Schema.String)),\n})\ntype WireResult = typeof WireResult.Type\n\nconst WireCost = Schema.Struct({\n  total: Schema.optional(Schema.Number),\n})\n\nconst WireResponse = Schema.Struct({\n  requestId: Schema.optional(Schema.String),\n  results: Schema.Array(WireResult),\n  costDollars: Schema.optional(WireCost),\n})\ntype WireResponse = typeof WireResponse.Type\n\n/** Lenient parse of Exa's ISO date strings; unparseable -> omitted. */\nconst parseDate = (s: string | null | undefined): DateTime.DateTime | undefined =>\n  s == null ? undefined : Option.getOrUndefined(DateTime.make(s))\n\n// Exa's pure `/search` returns no text excerpt unless you request `contents`\n// (the out-of-scope extract feature), so `snippet` stays undefined here -\n// the honest result is url + title + score + publishedDate. `author` and\n// the full `raw` object remain on `raw` for typed-tag callers.\nconst toResult = (r: WireResult): SearchResult => {\n  const publishedDate = parseDate(r.publishedDate)\n  return {\n    url: r.url,\n    ...(r.title != null && { title: r.title }),\n    ...(r.score !== undefined && { score: r.score }),\n    ...(publishedDate !== undefined && { publishedDate }),\n    raw: r,\n  }\n}\n\n// `costDollars` is still decoded (so it survives on `raw`) but not promoted\n// to a typed cost field: search cost/usage is deferred to the unified usage\n// design (see plans/usage-tracking.md).\nconst toResponse = (wire: WireResponse): SearchResponse => ({\n  results: wire.results.map(toResult),\n  raw: wire,\n})\n\n// ---------------------------------------------------------------------------\n// HTTP\n// ---------------------------------------------------------------------------\n\nconst transportFailure = (cause: unknown): AiError.AiError =>\n  new AiError.Unavailable({ provider: \"exa\", raw: cause })\n\nconst httpStatusError = (status: number, body: string): AiError.AiError => {\n  const provider = \"exa\"\n  const raw = body\n  if (status === 429) return new AiError.RateLimited({ provider, raw })\n  if (status === 408 || status === 504) return new AiError.Timeout({ provider, raw })\n  if (status === 401) return new AiError.AuthFailed({ provider, subtype: \"auth\", raw })\n  if (status === 403) return new AiError.AuthFailed({ provider, subtype: \"permission\", raw })\n  if (status === 402) return new AiError.AuthFailed({ provider, subtype: \"billing\", raw })\n  if (status >= 500) return new AiError.Unavailable({ provider, status, raw })\n  return new AiError.InvalidRequest({ provider, raw })\n}\n\nconst baseUrl = (cfg: Config): string => cfg.baseUrl ?? \"https://api.exa.ai\"\n\nconst postSearch = (\n  cfg: Config,\n  body: WireBody,\n): Effect.Effect<WireResponse, AiError.AiError, HttpClient.HttpClient> =>\n  Effect.gen(function* () {\n    const client = yield* HttpClient.HttpClient\n    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/search`).pipe(\n      HttpClientRequest.setHeader(\"x-api-key\", Redacted.value(cfg.apiKey)),\n      HttpClientRequest.bodyJsonUnsafe(body),\n    )\n    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))\n    if (response.status >= 400) {\n      const text = yield* response.text.pipe(Effect.orElseSucceed(() => \"\"))\n      return yield* httpStatusError(response.status, text)\n    }\n    const json = yield* response.json.pipe(Effect.mapError(transportFailure))\n    return yield* Schema.decodeUnknownEffect(WireResponse)(json).pipe(\n      Effect.mapError(transportFailure),\n    )\n  })\n\nconst searchImpl =\n  (cfg: Config) =>\n  (\n    request: ExaSearchRequest,\n  ): Effect.Effect<SearchResponse, AiError.AiError, HttpClient.HttpClient> =>\n    Effect.gen(function* () {\n      // Exa has no language filter (bucket 2: warn, don't fail).\n      yield* Capabilities.warnDroppedWhen(request.language, {\n        provider: \"exa\",\n        capability: \"language\",\n        field: \"language\",\n        reason: \"Exa /search has no language filter; the hint is ignored.\",\n      })\n      const now = yield* DateTime.now\n      const wire = yield* postSearch(cfg, buildBody(request, now))\n      return toResponse(wire)\n    })\n\n// ---------------------------------------------------------------------------\n// Constructors\n// ---------------------------------------------------------------------------\n\n/**\n * Build an `ExaSearchService` value. For Layer-based setup, prefer\n * {@link layer}.\n */\nexport const make = (cfg: Config): Effect.Effect<ExaSearchService, never, HttpClient.HttpClient> =>\n  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({\n    search: (request) =>\n      searchImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),\n  }))\n\n/**\n * Layer registering both the provider-typed `ExaSearch` tag and the\n * generic `WebSearch` tag over one implementation. A `CommonSearchRequest`\n * is structurally an `ExaSearchRequest` with `type` / `category` unset, so\n * the generic registration forwards directly.\n */\nexport const layer = (\n  cfg: Config,\n): Layer.Layer<ExaSearch | WebSearch, never, HttpClient.HttpClient> => {\n  const typed = Layer.effect(ExaSearch, make(cfg))\n  const generic = Layer.effect(\n    WebSearch,\n    Effect.map(make(cfg), (s): WebSearchService => ({ search: (request) => s.search(request) })),\n  )\n  return Layer.merge(typed, generic)\n}\n"],"mappings":"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"}

package/dist/chunk-CfYAbeIz.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { ExaCategory, ExaSearchType } from "./models.mjs";
+import { t as ExaSearch_d_exports } from "./ExaSearch.mjs";
+export { ExaCategory, ExaSearch_d_exports as ExaSearch, ExaSearchType };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { t as ExaSearch_exports } from "./ExaSearch.mjs";
+import "./models.mjs";
+export { ExaSearch_exports as ExaSearch };

package/dist/models.d.mts

@@ -0,0 +1,24 @@
+//#region src/models.d.ts
+/**
+ * Exa's search mode. The `/search` endpoint has no `model`; `type` selects
+ * the retrieval strategy instead, and is the one knob that makes Exa
+ * distinctive (semantic / embeddings-backed search vs. keyword).
+ *
+ * Current documented values: `auto` (default; picks per query), `fast`,
+ * `instant`, and the deep-research variants (`deep-lite`, `deep`,
+ * `deep-reasoning`). The legacy `neural` / `keyword` values still work on
+ * the wire; the `(string & {})` tail keeps any of them assignable without
+ * an SDK bump.
+ *
+ * Provider-specific, so it lives on `ExaSearchRequest`, not the
+ * cross-provider `CommonSearchRequest`.
+ */
+type ExaSearchType = "auto" | "fast" | "instant" | "deep-lite" | "deep" | "deep-reasoning" | "neural" | "keyword" | (string & {});
+/**
+ * Exa's result category filter. Narrows the index to a content vertical.
+ * Provider-specific, so it lives on `ExaSearchRequest`.
+ */
+type ExaCategory = "company" | "research paper" | "news" | "personal site" | "financial report" | "people" | (string & {});
+//#endregion
+export { ExaCategory, ExaSearchType };
+//# sourceMappingURL=models.d.mts.map

package/dist/models.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.mts","names":[],"sources":["../src/models.ts"],"mappings":";;AAcA;;;;;AAgBA;;;;;;;;KAhBY,aAAA;;;;;KAgBA,WAAA"}

package/dist/models.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@effect-uai/exa",
+  "version": "0.7.0",
+  "description": "Exa provider for @effect-uai/core (web search).",
+  "keywords": [
+    "ai",
+    "effect",
+    "exa",
+    "search",
+    "web-search"
+  ],
+  "homepage": "https://github.com/betalyra/effect-uai/tree/main/packages/providers/exa",
+  "bugs": {
+    "url": "https://github.com/betalyra/effect-uai/issues"
+  },
+  "license": "MIT",
+  "author": "Betalyra",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/betalyra/effect-uai",
+    "directory": "packages/providers/exa"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./ExaSearch": {
+      "types": "./dist/ExaSearch.d.mts",
+      "import": "./dist/ExaSearch.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "effect": "4.0.0-beta.57",
+    "typescript": "^6.0.3",
+    "@effect-uai/core": "0.7.0"
+  },
+  "peerDependencies": {
+    "@effect-uai/core": ">=0.2.0 <1",
+    "effect": "4.0.0-beta.57"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/ExaSearch.ts

@@ -0,0 +1,240 @@
+import { Context, DateTime, type Duration, Effect, Layer, Option, Redacted, Schema } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import * as Capabilities from "@effect-uai/core/Capabilities"
+import {
+  type CommonSearchRequest,
+  type SearchRecency,
+  type SearchResponse,
+  type SearchResult,
+  WebSearch,
+  type WebSearchService,
+} from "@effect-uai/core/WebSearch"
+import type { ExaCategory, ExaSearchType } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Exa-typed search request. Widens {@link CommonSearchRequest} with Exa's
+ * own knobs; the common fields map onto Exa's wire filters (see the codec
+ * below). There is no `model` - `/search` ranks the web directly, with
+ * `type` choosing the retrieval strategy.
+ */
+export type ExaSearchRequest = CommonSearchRequest & {
+  /** Retrieval strategy - see {@link ExaSearchType}. Defaults to `auto`. */
+  readonly type?: ExaSearchType
+  /** Content-vertical filter - see {@link ExaCategory}. */
+  readonly category?: ExaCategory
+}
+
+export type ExaSearchService = {
+  readonly search: (request: ExaSearchRequest) => Effect.Effect<SearchResponse, AiError.AiError>
+}
+
+/**
+ * Provider-typed service tag. Yield this for Exa-typed search (`type`,
+ * `category`, the per-result `score`); yield the generic `WebSearch` tag
+ * for provider-portable code. Both are registered by {@link layer}.
+ */
+export class ExaSearch extends Context.Service<ExaSearch, ExaSearchService>()(
+  "@betalyra/effect-uai/providers/exa/ExaSearch",
+) {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+}
+
+// ---------------------------------------------------------------------------
+// Codec - request body
+// ---------------------------------------------------------------------------
+
+type WireBody = {
+  readonly query: string
+  readonly numResults?: number
+  readonly type?: string
+  readonly category?: string
+  readonly includeDomains?: ReadonlyArray<string>
+  readonly excludeDomains?: ReadonlyArray<string>
+  readonly startPublishedDate?: string
+  readonly endPublishedDate?: string
+  readonly userLocation?: string
+}
+
+// Exa has no recency enum; map the coarse enum onto a published-after date
+// computed from "now" (per the capabilities policy: lossless translation).
+const recencyDuration: Record<SearchRecency, Duration.Input> = {
+  hour: "1 hour",
+  day: "1 day",
+  week: "7 days",
+  month: "30 days",
+  year: "365 days",
+}
+
+const buildBody = (request: ExaSearchRequest, now: DateTime.DateTime): WireBody => {
+  // Explicit `startDate` wins over the `recency` sugar; otherwise derive the
+  // published-after bound from the recency window.
+  const startPublishedDate =
+    request.startDate !== undefined
+      ? DateTime.formatIso(request.startDate)
+      : request.recency !== undefined
+        ? DateTime.formatIso(DateTime.subtractDuration(now, recencyDuration[request.recency]))
+        : undefined
+
+  return {
+    query: request.query,
+    ...(request.maxResults !== undefined && { numResults: request.maxResults }),
+    ...(request.type !== undefined && { type: request.type }),
+    ...(request.category !== undefined && { category: request.category }),
+    ...(request.includeDomains !== undefined && { includeDomains: request.includeDomains }),
+    ...(request.excludeDomains !== undefined && { excludeDomains: request.excludeDomains }),
+    ...(startPublishedDate !== undefined && { startPublishedDate }),
+    ...(request.endDate !== undefined && { endPublishedDate: DateTime.formatIso(request.endDate) }),
+    ...(request.country !== undefined && { userLocation: request.country }),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Codec - response
+// ---------------------------------------------------------------------------
+
+const WireResult = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  url: Schema.String,
+  title: Schema.optional(Schema.NullOr(Schema.String)),
+  score: Schema.optional(Schema.Number),
+  publishedDate: Schema.optional(Schema.NullOr(Schema.String)),
+  author: Schema.optional(Schema.NullOr(Schema.String)),
+})
+type WireResult = typeof WireResult.Type
+
+const WireCost = Schema.Struct({
+  total: Schema.optional(Schema.Number),
+})
+
+const WireResponse = Schema.Struct({
+  requestId: Schema.optional(Schema.String),
+  results: Schema.Array(WireResult),
+  costDollars: Schema.optional(WireCost),
+})
+type WireResponse = typeof WireResponse.Type
+
+/** Lenient parse of Exa's ISO date strings; unparseable -> omitted. */
+const parseDate = (s: string | null | undefined): DateTime.DateTime | undefined =>
+  s == null ? undefined : Option.getOrUndefined(DateTime.make(s))
+
+// Exa's pure `/search` returns no text excerpt unless you request `contents`
+// (the out-of-scope extract feature), so `snippet` stays undefined here -
+// the honest result is url + title + score + publishedDate. `author` and
+// the full `raw` object remain on `raw` for typed-tag callers.
+const toResult = (r: WireResult): SearchResult => {
+  const publishedDate = parseDate(r.publishedDate)
+  return {
+    url: r.url,
+    ...(r.title != null && { title: r.title }),
+    ...(r.score !== undefined && { score: r.score }),
+    ...(publishedDate !== undefined && { publishedDate }),
+    raw: r,
+  }
+}
+
+// `costDollars` is still decoded (so it survives on `raw`) but not promoted
+// to a typed cost field: search cost/usage is deferred to the unified usage
+// design (see plans/usage-tracking.md).
+const toResponse = (wire: WireResponse): SearchResponse => ({
+  results: wire.results.map(toResult),
+  raw: wire,
+})
+
+// ---------------------------------------------------------------------------
+// HTTP
+// ---------------------------------------------------------------------------
+
+const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "exa", raw: cause })
+
+const httpStatusError = (status: number, body: string): AiError.AiError => {
+  const provider = "exa"
+  const raw = body
+  if (status === 429) return new AiError.RateLimited({ provider, raw })
+  if (status === 408 || status === 504) return new AiError.Timeout({ provider, raw })
+  if (status === 401) return new AiError.AuthFailed({ provider, subtype: "auth", raw })
+  if (status === 403) return new AiError.AuthFailed({ provider, subtype: "permission", raw })
+  if (status === 402) return new AiError.AuthFailed({ provider, subtype: "billing", raw })
+  if (status >= 500) return new AiError.Unavailable({ provider, status, raw })
+  return new AiError.InvalidRequest({ provider, raw })
+}
+
+const baseUrl = (cfg: Config): string => cfg.baseUrl ?? "https://api.exa.ai"
+
+const postSearch = (
+  cfg: Config,
+  body: WireBody,
+): Effect.Effect<WireResponse, AiError.AiError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/search`).pipe(
+      HttpClientRequest.setHeader("x-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(body),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* httpStatusError(response.status, text)
+    }
+    const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    return yield* Schema.decodeUnknownEffect(WireResponse)(json).pipe(
+      Effect.mapError(transportFailure),
+    )
+  })
+
+const searchImpl =
+  (cfg: Config) =>
+  (
+    request: ExaSearchRequest,
+  ): Effect.Effect<SearchResponse, AiError.AiError, HttpClient.HttpClient> =>
+    Effect.gen(function* () {
+      // Exa has no language filter (bucket 2: warn, don't fail).
+      yield* Capabilities.warnDroppedWhen(request.language, {
+        provider: "exa",
+        capability: "language",
+        field: "language",
+        reason: "Exa /search has no language filter; the hint is ignored.",
+      })
+      const now = yield* DateTime.now
+      const wire = yield* postSearch(cfg, buildBody(request, now))
+      return toResponse(wire)
+    })
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an `ExaSearchService` value. For Layer-based setup, prefer
+ * {@link layer}.
+ */
+export const make = (cfg: Config): Effect.Effect<ExaSearchService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+    search: (request) =>
+      searchImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+  }))
+
+/**
+ * Layer registering both the provider-typed `ExaSearch` tag and the
+ * generic `WebSearch` tag over one implementation. A `CommonSearchRequest`
+ * is structurally an `ExaSearchRequest` with `type` / `category` unset, so
+ * the generic registration forwards directly.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<ExaSearch | WebSearch, never, HttpClient.HttpClient> => {
+  const typed = Layer.effect(ExaSearch, make(cfg))
+  const generic = Layer.effect(
+    WebSearch,
+    Effect.map(make(cfg), (s): WebSearchService => ({ search: (request) => s.search(request) })),
+  )
+  return Layer.merge(typed, generic)
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * as ExaSearch from "./ExaSearch.js"
+export * from "./models.js"

package/src/models.ts

@@ -0,0 +1,39 @@
+/**
+ * Exa's search mode. The `/search` endpoint has no `model`; `type` selects
+ * the retrieval strategy instead, and is the one knob that makes Exa
+ * distinctive (semantic / embeddings-backed search vs. keyword).
+ *
+ * Current documented values: `auto` (default; picks per query), `fast`,
+ * `instant`, and the deep-research variants (`deep-lite`, `deep`,
+ * `deep-reasoning`). The legacy `neural` / `keyword` values still work on
+ * the wire; the `(string & {})` tail keeps any of them assignable without
+ * an SDK bump.
+ *
+ * Provider-specific, so it lives on `ExaSearchRequest`, not the
+ * cross-provider `CommonSearchRequest`.
+ */
+export type ExaSearchType =
+  | "auto"
+  | "fast"
+  | "instant"
+  | "deep-lite"
+  | "deep"
+  | "deep-reasoning"
+  | "neural"
+  | "keyword"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+/**
+ * Exa's result category filter. Narrows the index to a content vertical.
+ * Provider-specific, so it lives on `ExaSearchRequest`.
+ */
+export type ExaCategory =
+  | "company"
+  | "research paper"
+  | "news"
+  | "personal site"
+  | "financial report"
+  | "people"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})