@effect-uai/core 0.7.0 → 0.9.0

package/dist/transcriber/Transcriber.d.mts

@@ -1,5 +1,5 @@
-import { t as AiError } from "../AiError-CAX_48RU.mjs";
-import { a as AudioSource, r as AudioFormat } from "../Audio-DPlTsNdz.mjs";
+import { t as AiError } from "../AiError-CrdR1EQi.mjs";
+import { a as AudioSource, r as AudioFormat } from "../Audio-DDSKCkSe.mjs";
 import { TranscriptEvent, TranscriptResult } from "../domain/Transcript.mjs";
 import { Context, Effect, Stream } from "effect";
 

package/dist/transcriber/Transcriber.test.mjs

@@ -1,5 +1,5 @@
 import { streamTranscriptionFrom, transcribe } from "./Transcriber.mjs";
-import { i as it, n as globalExpect, r as describe, t as import_dist } from "../dist-DV5ISja1.mjs";
+import { a as describe, n as globalExpect, o as it, t as import_dist } from "../dist-B04dlFHg.mjs";
 import { layer, layerSyncOnly } from "../testing/MockTranscriber.mjs";
 import { Duration, Effect, Stream } from "effect";
 //#region src/transcriber/Transcriber.test.ts

package/dist/web-search/WebSearch.d.mts

@@ -0,0 +1,119 @@
+import { t as AiError } from "../AiError-CrdR1EQi.mjs";
+import { Context, DateTime, Effect, Schema } from "effect";
+
+//#region src/web-search/WebSearch.d.ts
+declare namespace WebSearch_d_exports {
+  export { CommonSearchRequest, SearchRecency, SearchResponse, SearchResult, WebSearch, WebSearchService, search };
+}
+/**
+ * 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.
+ */
+declare const SearchRecency: Schema.Literals<readonly ["hour", "day", "week", "month", "year"]>;
+type SearchRecency = typeof SearchRecency.Type;
+/**
+ * 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.
+ */
+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;
+};
+/**
+ * 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[]`, …).
+ */
+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;
+};
+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;
+};
+/**
+ * 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.
+ */
+type WebSearchService = {
+  readonly search: (request: CommonSearchRequest) => Effect.Effect<SearchResponse, AiError>;
+};
+declare const WebSearch_base: Context.ServiceClass<WebSearch, "@betalyra/effect-uai/WebSearch", WebSearchService>;
+/**
+ * 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.
+ */
+declare class WebSearch extends WebSearch_base {}
+/** Run one web search against whichever provider Layer is in scope. */
+declare const search: (request: CommonSearchRequest) => Effect.Effect<SearchResponse, AiError, WebSearch>;
+//#endregion
+export { CommonSearchRequest, SearchRecency, SearchResponse, SearchResult, WebSearch, WebSearchService, search, WebSearch_d_exports as t };
+//# sourceMappingURL=WebSearch.d.mts.map

package/dist/web-search/WebSearch.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearch.d.mts","names":[],"sources":["../../src/web-search/WebSearch.ts"],"mappings":";;;;;;;;;;;;;;;;;;;AAsBA;;;cAAa,aAAA,EAAa,MAAA,CAAA,QAAA;AAAA,KAEd,aAAA,UAAuB,aAAA,CAAc,IAAA;AAAjD;;;;;AAkBA;;;;;;;AAlBA,KAkBY,mBAAA;EAwB0B,wEAtB3B,KAAA;EAAA;;;;;;;EAAA,SAQA,UAAA,WAYA;EAAA,SAVA,cAAA,GAAiB,aAAA,UAUI;EAAA,SARrB,cAAA,GAAiB,aAAA;EAUP;;;;;EAAA,SAJV,OAAA,GAAU,aAAA,EAsBT;EAAA,SApBD,SAAA,GAAY,QAAA,CAAS,QAAA;WAErB,OAAA,GAAU,QAAA,CAAS,QAAA,EAoBnB;EAAA,SAlBA,OAAA,WA2BA;EAAA,SAzBA,QAAA;AAAA;;;;;;AAuCX;;KAzBY,YAAA;EA0BqB,qDAxBtB,GAAA,UAwBS;EAAA,SAtBT,KAAA;EA+BA;;;AAaX;;;EAbW,SAxBA,OAAA,WAsCwD;EAAA,SApCxD,aAAA,GAAgB,QAAA,CAAS,QAAA;EAoCiB;;;;;;EAAA,SA7B1C,KAAA,WA6BiD;EAAA,SA3BjD,GAAA;AAAA;AAAA,KAGC,cAAA;EAAA,SACD,OAAA,EAAS,aAAA,CAAc,YAAA;EAuBgE;AACjG;;;;;;;EADiG,SAdvF,GAAA;AAAA;;;;;;AAsBX;KATY,gBAAA;EAAA,SACD,MAAA,GAAS,OAAA,EAAS,mBAAA,KAAwB,MAAA,CAAO,MAAA,CAAO,cAAA,EAAgB,OAAA;AAAA;AAAA,cAClF,cAAA;AAYD;;;;;AAAA,cALa,SAAA,SAAkB,cAAA;;cAKlB,MAAA,GACX,OAAA,EAAS,mBAAA,KACR,MAAA,CAAO,MAAA,CAAO,cAAA,EAAgB,OAAA,EAAiB,SAAA"}

package/dist/web-search/WebSearch.mjs

@@ -0,0 +1,42 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { Context, Effect, Schema } from "effect";
+//#region src/web-search/WebSearch.ts
+var WebSearch_exports = /* @__PURE__ */ __exportAll({
+	SearchRecency: () => SearchRecency,
+	WebSearch: () => WebSearch,
+	search: () => search
+});
+/**
+* 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.
+*/
+const SearchRecency = Schema.Literals([
+	"hour",
+	"day",
+	"week",
+	"month",
+	"year"
+]);
+/**
+* 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.
+*/
+var WebSearch = class extends Context.Service()("@betalyra/effect-uai/WebSearch") {};
+/** Run one web search against whichever provider Layer is in scope. */
+const search = (request) => Effect.flatMap(WebSearch.asEffect(), (s) => s.search(request));
+//#endregion
+export { SearchRecency, WebSearch, search, WebSearch_exports as t };
+
+//# sourceMappingURL=WebSearch.mjs.map

package/dist/web-search/WebSearch.mjs.map

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

package/dist/web-search/WebSearchTool.d.mts

@@ -0,0 +1,58 @@
+import { c as Tool } from "../Tool-0XUIT2A2.mjs";
+import { SearchResult, WebSearch } from "./WebSearch.mjs";
+import { Schema } from "effect";
+
+//#region src/web-search/WebSearchTool.d.ts
+declare namespace WebSearchTool_d_exports {
+  export { WebSearchToolArgs, WebSearchToolOptions, webSearchTool };
+}
+/**
+ * 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.
+ */
+declare const WebSearchToolArgs: Schema.Struct<{
+  readonly query: Schema.String;
+  readonly recency: Schema.optional<Schema.Literals<readonly ["hour", "day", "week", "month", "year"]>>;
+}>;
+type WebSearchToolArgs = typeof WebSearchToolArgs.Type;
+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.
+ */
+declare const webSearchTool: (options?: WebSearchToolOptions) => Tool<string, WebSearchToolArgs, never, string, WebSearch>;
+//#endregion
+export { WebSearchToolArgs, WebSearchToolOptions, WebSearchTool_d_exports as t, webSearchTool };
+//# sourceMappingURL=WebSearchTool.d.mts.map

package/dist/web-search/WebSearchTool.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearchTool.d.mts","names":[],"sources":["../../src/web-search/WebSearchTool.ts"],"mappings":";;;;;;;;;;;;;;;;cAYM,iBAAA,EAAiB,MAAA,CAAA,MAAA;EAAA;;;KAKX,iBAAA,UAA2B,iBAAA,CAAkB,IAAA;AAAA,KAa7C,oBAAA;EAlBW,iEAoBZ,IAAA;EApBY;;;;EAAA,SAyBZ,UAAA;;;;;WAKA,cAAA,GAAiB,aAAA;WAEjB,cAAA,GAAiB,aAAA;;AA3B5B;;;WAgCW,MAAA,IAAU,OAAA,EAAS,aAAA,CAAc,YAAA;AAAA;AAnB5C;;;;;;;;;;;;;;AAAA,cAoCa,aAAA,GACX,OAAA,GAAU,oBAAA,KACT,IAAA,SAAkB,iBAAA,iBAAkC,SAAA"}

package/dist/web-search/WebSearchTool.mjs

@@ -0,0 +1,69 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { SearchRecency, search } from "./WebSearch.mjs";
+import { fromEffectSchema, make } from "../tool/Tool.mjs";
+import { Effect, Schema } from "effect";
+//#region src/web-search/WebSearchTool.ts
+var WebSearchTool_exports = /* @__PURE__ */ __exportAll({ webSearchTool: () => webSearchTool });
+/**
+* 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)
+});
+/** Numbered `title / url / snippet` list - what a model reads best. */
+const defaultRender = (results) => results.length === 0 ? "No results found." : results.map((r, i) => {
+	const head = `${i + 1}. ${r.title ?? r.url}\n   ${r.url}`;
+	return r.snippet === void 0 ? head : `${head}\n   ${r.snippet}`;
+}).join("\n\n");
+/**
+* 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.
+*/
+const webSearchTool = (options) => {
+	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 make({
+		name,
+		description: "Search the web for current information. Returns ranked results with titles, URLs, and snippets.",
+		inputSchema: fromEffectSchema(WebSearchToolArgs),
+		run: (args) => search({
+			query: args.query,
+			maxResults,
+			...args.recency !== void 0 && { recency: args.recency },
+			...includeDomains !== void 0 && { includeDomains },
+			...excludeDomains !== void 0 && { 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 !== void 0 && { "web_search.recency": args.recency },
+				...includeDomains !== void 0 && { "web_search.include_domains": includeDomains },
+				...excludeDomains !== void 0 && { "web_search.exclude_domains": excludeDomains }
+			}
+		}))
+	});
+};
+//#endregion
+export { WebSearchTool_exports as t, webSearchTool };
+
+//# sourceMappingURL=WebSearchTool.mjs.map

package/dist/web-search/WebSearchTool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSearchTool.mjs","names":["Tool.make","Tool.fromEffectSchema"],"sources":["../../src/web-search/WebSearchTool.ts"],"sourcesContent":["import { Effect, Schema } from \"effect\"\nimport * as Tool from \"../tool/Tool.js\"\nimport { search, SearchRecency, type SearchResult, WebSearch } from \"./WebSearch.js\"\n\n/**\n * Model-facing argument schema. Deliberately narrow: `query` plus the one\n * filter that is genuinely the model's call - `recency` (it knows whether a\n * question is about current events or evergreen). App-policy scoping\n * (`includeDomains` / `excludeDomains`) and the `maxResults` cost ceiling\n * are pinned on the constructor instead, so they are guaranteed rather than\n * left to the model to remember each call.\n */\nconst WebSearchToolArgs = Schema.Struct({\n  query: Schema.String,\n  recency: Schema.optional(SearchRecency),\n})\n\nexport type WebSearchToolArgs = typeof WebSearchToolArgs.Type\n\n/** Numbered `title / url / snippet` list - what a model reads best. */\nconst defaultRender = (results: ReadonlyArray<SearchResult>): string =>\n  results.length === 0\n    ? \"No results found.\"\n    : results\n        .map((r, i) => {\n          const head = `${i + 1}. ${r.title ?? r.url}\\n   ${r.url}`\n          return r.snippet === undefined ? head : `${head}\\n   ${r.snippet}`\n        })\n        .join(\"\\n\\n\")\n\nexport type WebSearchToolOptions = {\n  /** Tool name the model sees. Default `\"web_search\"`. */\n  readonly name?: string\n  /**\n   * App-fixed ceiling on results per call - a cost guard, not exposed to\n   * the model. Default `5`.\n   */\n  readonly maxResults?: number\n  /**\n   * App-fixed allowlist applied to every search. A policy scope (\"only\n   * search our docs\"), not a model knob - so it is enforced, not requested.\n   */\n  readonly includeDomains?: ReadonlyArray<string>\n  /** App-fixed denylist applied to every search (\"never return X\"). */\n  readonly excludeDomains?: ReadonlyArray<string>\n  /**\n   * Override how results are rendered into the model-facing string.\n   * Default: a numbered `title / url / snippet` list.\n   */\n  readonly render?: (results: ReadonlyArray<SearchResult>) => string\n}\n\n/**\n * The canonical web-search tool. Its `R` is just `WebSearch`, so providing\n * any search-provider Layer satisfies it and the model-facing contract\n * (name, description, schema) is identical no matter which backend answers\n * - swap `PerplexitySearch.layer` for `ExaSearch.layer` and the tool the\n * model sees does not change. Drops straight into a `Toolkit` and the\n * `LanguageModel` tool-calling loop.\n *\n * The model controls only `query` and `recency`; domain scoping and the\n * result cap are app policy, fixed here on the constructor. `Output` is\n * rendered text, not raw `SearchResult[]`: the model reads the list, while\n * the app still gets the structured results through the normal tool-result\n * channel. Pass `render` to change the format.\n */\nexport const webSearchTool = (\n  options?: WebSearchToolOptions,\n): Tool.Tool<string, WebSearchToolArgs, never, string, WebSearch> => {\n  const name = options?.name ?? \"web_search\"\n  const render = options?.render ?? defaultRender\n  const maxResults = options?.maxResults ?? 5\n  const includeDomains = options?.includeDomains\n  const excludeDomains = options?.excludeDomains\n  return Tool.make({\n    name,\n    description:\n      \"Search the web for current information. Returns ranked results with titles, URLs, and snippets.\",\n    inputSchema: Tool.fromEffectSchema(WebSearchToolArgs),\n    // The call is wrapped in a tracing span so agent traces show the tool\n    // invocation (query, filters, result count) nested under the model turn.\n    // `withSpan` is a no-op until a Tracer is installed, so this is free by\n    // default and adds nothing to the requirements.\n    run: (args) =>\n      search({\n        query: args.query,\n        maxResults,\n        ...(args.recency !== undefined && { recency: args.recency }),\n        ...(includeDomains !== undefined && { includeDomains }),\n        ...(excludeDomains !== undefined && { excludeDomains }),\n      }).pipe(\n        Effect.tap((r) => Effect.annotateCurrentSpan(\"web_search.result_count\", r.results.length)),\n        Effect.map((r) => render(r.results)),\n        Effect.withSpan(name, {\n          kind: \"client\",\n          attributes: {\n            \"web_search.query\": args.query,\n            \"web_search.max_results\": maxResults,\n            ...(args.recency !== undefined && { \"web_search.recency\": args.recency }),\n            ...(includeDomains !== undefined && { \"web_search.include_domains\": includeDomains }),\n            ...(excludeDomains !== undefined && { \"web_search.exclude_domains\": excludeDomains }),\n          },\n        }),\n      ),\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAM,oBAAoB,OAAO,OAAO;CACtC,OAAO,OAAO;CACd,SAAS,OAAO,SAAS,cAAc;CACxC,CAAC;;AAKF,MAAM,iBAAiB,YACrB,QAAQ,WAAW,IACf,sBACA,QACG,KAAK,GAAG,MAAM;CACb,MAAM,OAAO,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,OAAO,EAAE;AACpD,QAAO,EAAE,YAAY,KAAA,IAAY,OAAO,GAAG,KAAK,OAAO,EAAE;EACzD,CACD,KAAK,OAAO;;;;;;;;;;;;;;;AAsCrB,MAAa,iBACX,YACmE;CACnE,MAAM,OAAO,SAAS,QAAQ;CAC9B,MAAM,SAAS,SAAS,UAAU;CAClC,MAAM,aAAa,SAAS,cAAc;CAC1C,MAAM,iBAAiB,SAAS;CAChC,MAAM,iBAAiB,SAAS;AAChC,QAAOA,KAAU;EACf;EACA,aACE;EACF,aAAaC,iBAAsB,kBAAkB;EAKrD,MAAM,SACJ,OAAO;GACL,OAAO,KAAK;GACZ;GACA,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,SAAS,KAAK,SAAS;GAC3D,GAAI,mBAAmB,KAAA,KAAa,EAAE,gBAAgB;GACtD,GAAI,mBAAmB,KAAA,KAAa,EAAE,gBAAgB;GACvD,CAAC,CAAC,KACD,OAAO,KAAK,MAAM,OAAO,oBAAoB,2BAA2B,EAAE,QAAQ,OAAO,CAAC,EAC1F,OAAO,KAAK,MAAM,OAAO,EAAE,QAAQ,CAAC,EACpC,OAAO,SAAS,MAAM;GACpB,MAAM;GACN,YAAY;IACV,oBAAoB,KAAK;IACzB,0BAA0B;IAC1B,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,sBAAsB,KAAK,SAAS;IACxE,GAAI,mBAAmB,KAAA,KAAa,EAAE,8BAA8B,gBAAgB;IACpF,GAAI,mBAAmB,KAAA,KAAa,EAAE,8BAA8B,gBAAgB;IACrF;GACF,CAAC,CACH;EACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -110,6 +110,14 @@
       "types": "./dist/transcriber/Transcriber.d.mts",
       "import": "./dist/transcriber/Transcriber.mjs"
     },
+    "./WebSearch": {
+      "types": "./dist/web-search/WebSearch.d.mts",
+      "import": "./dist/web-search/WebSearch.mjs"
+    },
+    "./WebSearchTool": {
+      "types": "./dist/web-search/WebSearchTool.d.mts",
+      "import": "./dist/web-search/WebSearchTool.mjs"
+    },
     "./Loop": {
       "types": "./dist/loop/Loop.d.mts",
       "import": "./dist/loop/Loop.mjs"

package/src/embedding-model/EmbeddingModel.test.ts

@@ -81,10 +81,14 @@ describe("embed / embedMany free exports preserve E in their return type", () =>
     // of the cross-provider request set. Requesting them on the generic
     // helper is a compile error; they're reachable only via the typed
     // `JinaEmbedding` tag.
+    // These calls exist only to assert the encoding is a compile error; they
+    // are intentionally never run, so the floating-effect check is off here.
+    // @effect-diagnostics effect/floatingEffect:off
     // @ts-expect-error "multivector" is not an EmbedEncoding
     embedMany({ inputs: ["x"], model: "m", encoding: "multivector" })
     // @ts-expect-error "sparse" is not an EmbedEncoding
     embed({ input: "x", model: "m", encoding: "sparse" })
+    // @effect-diagnostics effect/floatingEffect:error
   })
 
   it("when the request is widened to CommonEmbedRequest, the response is the open union", () => {

package/src/index.ts

@@ -18,6 +18,8 @@ export * as SandboxImage from "./sandbox/SandboxImage.js"
 export * as SandboxNetwork from "./sandbox/SandboxNetwork.js"
 export * as SpeechSynthesizer from "./speech-synthesizer/SpeechSynthesizer.js"
 export * as Transcriber from "./transcriber/Transcriber.js"
+export * as WebSearch from "./web-search/WebSearch.js"
+export * as WebSearchTool from "./web-search/WebSearchTool.js"
 export * as Vector from "./math/Vector.js"
 export * as Loop from "./loop/Loop.js"
 export * as Retry from "./retry/Retry.js"
@@ -32,3 +34,4 @@ export * as Lines from "./streaming/Lines.js"
 export * as SSE from "./streaming/SSE.js"
 export * as StructuredFormat from "./structured-format/StructuredFormat.js"
 export * as Metrics from "./observability/Metrics.js"
+export * as Telemetry from "./observability/Telemetry.js"

package/src/language-model/LanguageModel.ts

@@ -2,7 +2,7 @@ import { Array as Arr, Context, Effect, Option, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
 import type { HistoryItem } from "../domain/Items.js"
 import type * as StructuredFormat from "../structured-format/StructuredFormat.js"
-import type { ToolDescriptor } from "../tool/Tool.js"
+import type { Toolkit } from "../tool/Toolkit.js"
 import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
 
 /**
@@ -18,7 +18,12 @@ export type CommonRequest = {
    * so code that yields a typed provider tag gets autocompletion.
    */
   readonly model: string
-  readonly tools?: ReadonlyArray<ToolDescriptor>
+  /**
+   * The model-visible tools for this request, as a `Toolkit`. The provider
+   * renders it to wire descriptors (`Tool.descriptorsOf`); omit it for a turn
+   * with no tools.
+   */
+  readonly tools?: Toolkit
   readonly toolChoice?:
     | "auto"
     | "required"

package/src/loop/Loop.test.ts

@@ -179,6 +179,28 @@ describe("Loop.loop", () => {
     expect(b.length).toBe(3)
   })
 
+  it("onTurnComplete: handler may return a step stream directly (not just Effect<Stream>)", async () => {
+    // The handler can skip the Effect wrapper when no effect is needed -
+    // bare stop() / next(s), mirroring loop's body.
+    const turnComplete: TurnEvent = TurnEvent.TurnComplete({
+      turn: { items: [], usage: { input_tokens: 0, output_tokens: 0 }, stop_reason: "stop" },
+    })
+    const deltas: Stream.Stream<TurnEvent> = Stream.fromIterable([
+      TurnEvent.TextDelta({ text: "hi" }),
+      turnComplete,
+    ])
+
+    const plain = deltas.pipe(onTurnComplete(() => stop()))
+    const effectful = deltas.pipe(onTurnComplete(() => Effect.sync(() => stop())))
+
+    const a = await Effect.runPromise(Stream.runCollect(plain))
+    const b = await Effect.runPromise(Stream.runCollect(effectful))
+
+    // Two value(delta) wraps + one stop sentinel; both return forms behave identically.
+    expect(a.length).toBe(3)
+    expect(b.length).toBe(3)
+  })
+
   it("is stack-safe and linear-time across many iterations", async () => {
     // 100k iterations far exceeds V8's typical stack depth (~10–15k frames).
     const N = 100_000

package/src/loop/Loop.ts

@@ -67,6 +67,16 @@ interface StepDef extends Data.TaggedEnum.WithGenerics<2> {
 
 const Step = Data.taggedEnum<StepDef>()
 
+/**
+ * Bare step constructors, so a loop body can emit `Value(...)`, `Next(...)`,
+ * `Stop()`, `StopWith(...)` directly inside a `Stream.make(...)` without the
+ * `Step.` prefix. (The `Step` object itself can't be exported under that name
+ * because it collides with the exported `Step` type.) For the common cases
+ * prefer the `value` / `next` / `stop` helpers, which also handle the
+ * single-element-stream wrapping for `next` / `stop`.
+ */
+export const { Value, Next, Stop, StopWith } = Step
+
 /** Wrap a value so it flows through the loop to downstream consumers. */
 export const value = <A>(a: A): Step<A, never> => Step.Value({ value: a })
 
@@ -103,6 +113,11 @@ export const stop = <S = never>(state?: S): Stream.Stream<Step<never, S>> =>
  * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
  * the raw delta stream cover anything an `emit`-style callback would do.
  *
+ * `then` may return the step stream directly, or an `Effect` that produces
+ * it (for branches that need to read a `Ref`, decode tool args, log, etc.).
+ * Mirrors `loop`'s body: return a bare `stop()` / `next(s)` where no effect
+ * is needed, lift to `Effect` only where one is.
+ *
  * If the upstream ends without a `TurnComplete`, the resulting stream
  * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
  * you want to recover.
@@ -110,21 +125,25 @@ export const stop = <S = never>(state?: S): Stream.Stream<Step<never, S>> =>
  * Dual: data-first `onTurnComplete(deltas, then)` and data-last
  * `deltas.pipe(onTurnComplete(then))` both work.
  */
+type TurnContinuation<S, A, E2, R2> =
+  | Stream.Stream<Step<A, S>, E2, R2>
+  | Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>
+
 export const onTurnComplete: {
   <S, A, E2 = never, R2 = never>(
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
   ): <E, R>(
     deltas: Stream.Stream<TurnEvent, E, R>,
   ) => Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
   <S, A, E, R, E2 = never, R2 = never>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
   ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
 } = Function.dual(
   2,
   <S, A, E, R, E2, R2>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
+    then: (turn: Turn) => TurnContinuation<S, A, E2, R2>,
   ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>
     Stream.unwrap(
       Effect.gen(function* () {
@@ -141,7 +160,8 @@ export const onTurnComplete: {
           Effect.gen(function* () {
             const opt = yield* Ref.get(turnRef)
             if (Option.isNone(opt)) return yield* new IncompleteTurn({})
-            return yield* then(opt.value)
+            const result = then(opt.value)
+            return Effect.isEffect(result) ? yield* result : result
           }),
         )
 
@@ -287,6 +307,9 @@ export const loop: {
             }
           })
 
+          // `Stream.fromPull` expects the generator to RETURN the pull effect,
+          // not run it; `return yield* pull` would execute a pull and break it.
+          // @effect-diagnostics-next-line effect/returnEffectInGen:off
           return pull
         }),
       ),