@effect-uai/core 0.6.0 → 0.8.0

package/src/transcriber/Transcriber.ts

@@ -15,12 +15,13 @@ export type CommonTranscribeRequest = {
   readonly model: string
   /** ISO-639-1 / BCP-47. Omit for autodetection (where supported). */
   readonly language?: string
-  /**
-   * Vocab biasing. Single-string covers OpenAI/Whisper-style prompts;
-   * `terms[]` covers Deepgram `keyterm`, Google adaptation phrases, AWS
-   * `vocabularyName`. Providers ignore what they don't support.
-   */
-  readonly prompt?: string | { readonly terms: ReadonlyArray<string> }
+  /** Free-form context / style hint (Whisper-style prose). OpenAI honors
+   *  it; providers without a prompt field `warnDropped`. */
+  readonly prompt?: string
+  /** Vocabulary biasing — discrete terms to boost (names, jargon). Maps to
+   *  Deepgram `keyterm`, ElevenLabs `keyterms`, Google `adaptation`,
+   *  Inworld `prompts`; others `warnDropped`. */
+  readonly biasingTerms?: ReadonlyArray<string>
   readonly diarization?: boolean
   readonly wordTimestamps?: boolean
 }
@@ -28,7 +29,9 @@ export type CommonTranscribeRequest = {
 /**
  * Streaming-transcription request. `inputFormat` declares what the
  * bytes in the input stream will look like — providers reject
- * mismatches at stream startup with `AiError.InvalidRequest`.
+ * formats they can't ingest at stream startup with
+ * `AiError.Unsupported` (a per-Layer capability gap, not a wire-shape
+ * mismatch).
  */
 export type CommonStreamTranscribeRequest = Omit<CommonTranscribeRequest, "audio"> & {
   readonly inputFormat: AudioFormat

package/src/web-search/WebSearch.ts

@@ -0,0 +1,150 @@
+import { Context, type DateTime, Effect, Schema } from "effect"
+import type * as AiError from "../domain/AiError.js"
+
+// ---------------------------------------------------------------------------
+// Recency
+// ---------------------------------------------------------------------------
+
+/**
+ * Convenience freshness enum shared by every provider. A coarse "published
+ * within the last …" filter that maps onto each provider's native recency
+ * knob (Perplexity `search_recency_filter`, Brave `freshness`, Tavily
+ * `time_range`, You.com `freshness`), or onto a computed published-date
+ * range where a provider has no enum (Exa).
+ *
+ * For a precise window use {@link CommonSearchRequest.startDate} /
+ * {@link CommonSearchRequest.endDate} instead; `recency` is the sugar for
+ * the common "past week / past month" case.
+ *
+ * Exposed as a `Schema` so {@link "../web-search/WebSearchTool".webSearchTool}
+ * can hand it straight to a model as a tool parameter; the
+ * {@link SearchRecency} type is derived from it.
+ */
+export const SearchRecency = Schema.Literals(["hour", "day", "week", "month", "year"])
+
+export type SearchRecency = typeof SearchRecency.Type
+
+// ---------------------------------------------------------------------------
+// Request
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-provider web-search request. A field earns a place here only if
+ * most of the supported providers honor it and a developer would expect it
+ * from a generic search interface; everything provider-specific (Exa
+ * `type`, Tavily `searchDepth`, Brave `goggles`, pagination `offset`,
+ * `safeSearch`, `topic`, …) lives on that provider's typed request.
+ *
+ * Note the one structural difference from `EmbeddingModel` /
+ * `Transcriber`: there is no `model`. None of the pure-`/search` endpoints
+ * take one - what looks model-shaped on a provider (Exa `type`, Tavily
+ * `searchDepth`) is a mode knob, so it stays on the provider-typed request.
+ */
+export type CommonSearchRequest = {
+  /** The search query. The one field every provider requires. */
+  readonly query: string
+  /**
+   * Upper bound on the number of results to return in this one call.
+   * Providers cap differently (Perplexity / Tavily / Brave at ~20, Exa /
+   * You.com at ~100); a value above a provider's cap is clamped by that
+   * provider. There is no common pagination - only two providers paginate
+   * and only shallowly, so `offset` is provider-typed.
+   */
+  readonly maxResults?: number
+  /** Restrict results to these domains (e.g. `["docs.foo.com"]`). */
+  readonly includeDomains?: ReadonlyArray<string>
+  /** Drop results from these domains. */
+  readonly excludeDomains?: ReadonlyArray<string>
+  /**
+   * Coarse freshness filter - see {@link SearchRecency}. Sugar over an
+   * explicit `startDate`; ignored where {@link startDate} is also set and
+   * the provider takes only one.
+   */
+  readonly recency?: SearchRecency
+  /** Published-after bound. The precise alternative to {@link recency}. */
+  readonly startDate?: DateTime.DateTime
+  /** Published-before bound. */
+  readonly endDate?: DateTime.DateTime
+  /** ISO 3166-1 alpha-2 country code to localize results (e.g. `"us"`). */
+  readonly country?: string
+  /** ISO 639-1 language code to bias results toward (e.g. `"en"`). */
+  readonly language?: string
+}
+
+// ---------------------------------------------------------------------------
+// Response
+// ---------------------------------------------------------------------------
+
+/**
+ * One normalized web-search hit. A flat record with optionals rather than a
+ * tagged union: the providers differ by *which fields are present*, not by
+ * *kind*. The provider's untouched result object is always on `raw`, so a
+ * caller holding a typed provider tag can recover anything not promoted
+ * here (`author`, `favicon`, multi-chunk `snippets[]`, …).
+ */
+export type SearchResult = {
+  /** Canonical result URL. Always present. */
+  readonly url: string
+  /** Result title / headline, when the provider returns one. */
+  readonly title?: string
+  /**
+   * Primary short excerpt - the one text field all providers return (under
+   * various wire names: `snippet`, `content`, `description`). The richer
+   * extract fields (`text`, `highlights`, `summary`) belong to the
+   * out-of-scope extract feature and stay on the provider-typed result.
+   */
+  readonly snippet?: string
+  /** Publication date, when the provider reports one. */
+  readonly publishedDate?: DateTime.DateTime
+  /**
+   * Relevance score, only from providers that rank (Exa, Tavily);
+   * `undefined` for providers that return an unscored list. Kept despite
+   * being non-universal because ranking is core to what a "search result"
+   * means - and `undefined` cleanly says "this backend doesn't score."
+   */
+  readonly score?: number
+  /** The provider-native result object, never lossy. */
+  readonly raw: unknown
+}
+
+export type SearchResponse = {
+  readonly results: ReadonlyArray<SearchResult>
+  /**
+   * The provider-native top-level response object. Cost / usage reporting
+   * is deliberately not modeled on this surface yet: providers disagree on
+   * both what (Exa returns USD, Tavily credits, Brave nothing in-body) and
+   * where (Brave reports cost in response headers), so it is deferred to the
+   * unified usage design (see plans/usage-tracking.md). Anything a provider
+   * reports survives here on `raw`.
+   */
+  readonly raw: unknown
+}
+
+// ---------------------------------------------------------------------------
+// Service + helper
+// ---------------------------------------------------------------------------
+
+/**
+ * The portable web-search surface: one operation, `search`. Pure search is
+ * the one thing every provider does, so - unlike `SpeechSynthesizer` /
+ * `Transcriber` - this capability needs no marker tags; every provider
+ * Layer can answer.
+ */
+export type WebSearchService = {
+  readonly search: (request: CommonSearchRequest) => Effect.Effect<SearchResponse, AiError.AiError>
+}
+
+/**
+ * Generic web-search service tag. Yield this for provider-portable code;
+ * yield a provider tag (`PerplexitySearch`, `ExaSearch`, …) when you need
+ * that provider's own knobs. A provider's `layer` registers both.
+ */
+export class WebSearch extends Context.Service<WebSearch, WebSearchService>()(
+  "@betalyra/effect-uai/WebSearch",
+) {}
+
+/** Run one web search against whichever provider Layer is in scope. */
+export const search = (
+  request: CommonSearchRequest,
+): Effect.Effect<SearchResponse, AiError.AiError, WebSearch> =>
+  Effect.flatMap(WebSearch.asEffect(), (s) => s.search(request))

package/src/web-search/WebSearchTool.ts

@@ -0,0 +1,106 @@
+import { Effect, Schema } from "effect"
+import * as Tool from "../tool/Tool.js"
+import { search, SearchRecency, type SearchResult, WebSearch } from "./WebSearch.js"
+
+/**
+ * Model-facing argument schema. Deliberately narrow: `query` plus the one
+ * filter that is genuinely the model's call - `recency` (it knows whether a
+ * question is about current events or evergreen). App-policy scoping
+ * (`includeDomains` / `excludeDomains`) and the `maxResults` cost ceiling
+ * are pinned on the constructor instead, so they are guaranteed rather than
+ * left to the model to remember each call.
+ */
+const WebSearchToolArgs = Schema.Struct({
+  query: Schema.String,
+  recency: Schema.optional(SearchRecency),
+})
+
+export type WebSearchToolArgs = typeof WebSearchToolArgs.Type
+
+/** Numbered `title / url / snippet` list - what a model reads best. */
+const defaultRender = (results: ReadonlyArray<SearchResult>): string =>
+  results.length === 0
+    ? "No results found."
+    : results
+        .map((r, i) => {
+          const head = `${i + 1}. ${r.title ?? r.url}\n   ${r.url}`
+          return r.snippet === undefined ? head : `${head}\n   ${r.snippet}`
+        })
+        .join("\n\n")
+
+export type WebSearchToolOptions = {
+  /** Tool name the model sees. Default `"web_search"`. */
+  readonly name?: string
+  /**
+   * App-fixed ceiling on results per call - a cost guard, not exposed to
+   * the model. Default `5`.
+   */
+  readonly maxResults?: number
+  /**
+   * App-fixed allowlist applied to every search. A policy scope ("only
+   * search our docs"), not a model knob - so it is enforced, not requested.
+   */
+  readonly includeDomains?: ReadonlyArray<string>
+  /** App-fixed denylist applied to every search ("never return X"). */
+  readonly excludeDomains?: ReadonlyArray<string>
+  /**
+   * Override how results are rendered into the model-facing string.
+   * Default: a numbered `title / url / snippet` list.
+   */
+  readonly render?: (results: ReadonlyArray<SearchResult>) => string
+}
+
+/**
+ * The canonical web-search tool. Its `R` is just `WebSearch`, so providing
+ * any search-provider Layer satisfies it and the model-facing contract
+ * (name, description, schema) is identical no matter which backend answers
+ * - swap `PerplexitySearch.layer` for `ExaSearch.layer` and the tool the
+ * model sees does not change. Drops straight into a `Toolkit` and the
+ * `LanguageModel` tool-calling loop.
+ *
+ * The model controls only `query` and `recency`; domain scoping and the
+ * result cap are app policy, fixed here on the constructor. `Output` is
+ * rendered text, not raw `SearchResult[]`: the model reads the list, while
+ * the app still gets the structured results through the normal tool-result
+ * channel. Pass `render` to change the format.
+ */
+export const webSearchTool = (
+  options?: WebSearchToolOptions,
+): Tool.Tool<string, WebSearchToolArgs, string, WebSearch> => {
+  const name = options?.name ?? "web_search"
+  const render = options?.render ?? defaultRender
+  const maxResults = options?.maxResults ?? 5
+  const includeDomains = options?.includeDomains
+  const excludeDomains = options?.excludeDomains
+  return Tool.make({
+    name,
+    description:
+      "Search the web for current information. Returns ranked results with titles, URLs, and snippets.",
+    inputSchema: Tool.fromEffectSchema(WebSearchToolArgs),
+    // The call is wrapped in a tracing span so agent traces show the tool
+    // invocation (query, filters, result count) nested under the model turn.
+    // `withSpan` is a no-op until a Tracer is installed, so this is free by
+    // default and adds nothing to the requirements.
+    run: (args) =>
+      search({
+        query: args.query,
+        maxResults,
+        ...(args.recency !== undefined && { recency: args.recency }),
+        ...(includeDomains !== undefined && { includeDomains }),
+        ...(excludeDomains !== undefined && { excludeDomains }),
+      }).pipe(
+        Effect.tap((r) => Effect.annotateCurrentSpan("web_search.result_count", r.results.length)),
+        Effect.map((r) => render(r.results)),
+        Effect.withSpan(name, {
+          kind: "client",
+          attributes: {
+            "web_search.query": args.query,
+            "web_search.max_results": maxResults,
+            ...(args.recency !== undefined && { "web_search.recency": args.recency }),
+            ...(includeDomains !== undefined && { "web_search.include_domains": includeDomains }),
+            ...(excludeDomains !== undefined && { "web_search.exclude_domains": excludeDomains }),
+          },
+        }),
+      ),
+  })
+}

package/dist/Audio-BfCTGnH3.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Audio-BfCTGnH3.d.mts","names":[],"sources":["../src/domain/Audio.ts"],"mappings":";;;;;;;;;;;;;;KAUY,aAAA;;;;;AAAZ;;;;;KA0BY,WAAA,GACR,QAAA,CAAS,aAAA,IACT,WAAA,CAAY,aAAA,IACZ,UAAA,CAAW,aAAA;AAAA,cAEF,UAAA,GAAc,CAAA,EAAG,WAAA,KAAc,CAAA,IAAK,QAAA,CAAS,aAAA;AAAA,cAC7C,aAAA,GAAiB,CAAA,EAAG,WAAA,KAAc,CAAA,IAAK,WAAA,CAAY,aAAA;AAAA,cAEnD,YAAA,GAAgB,CAAA,EAAG,WAAA,KAAc,CAAA,IAAK,UAAA,CAAW,aAAA;;;;;;;KAQlD,WAAA;EAAA,SACD,SAAA;EAAA,SACA,QAAA;EAAA,SAUA,UAAA,wDA1BK;EAAA,SA4BL,OAAA;EAAA,SACA,QAAA;AAAA;;AA1BX;;;;KAkCY,UAAA;EAAA,SACD,KAAA,EAAO,UAAA;AAAA;;;;;KAON,SAAA;EAAA,SACD,MAAA,EAAQ,WAAA;EAAA,SACR,KAAA,EAAO,UAAA;EAAA,SACP,eAAA;AAAA"}