@absolutejs/ai 0.2.6 → 0.2.8

package/dist/ai/research.js

@@ -0,0 +1,84 @@
+// @bun
+var __require = import.meta.require;
+
+// src/ai/research.ts
+import {
+  boundedQueries,
+  evidenceText,
+  sourceSupportsQuote
+} from "@absolutejs/search";
+var researchWithEvidence = async (input) => {
+  const requested = input.queries ?? boundedQueries(input.query);
+  const maxQueries = input.maxQueries ?? 2;
+  if (!Number.isInteger(maxQueries) || maxQueries < 1)
+    throw new Error("Research requires a positive query budget");
+  const searches = [];
+  const limitations = [];
+  const generatedAt = new Date().toISOString();
+  if (requested.length > maxQueries)
+    limitations.push("Query budget reached; some requested research was not performed");
+  for (const query of requested.slice(0, maxQueries)) {
+    input.signal?.throwIfAborted();
+    searches.push(await input.provider.search({
+      query,
+      mode: "context",
+      signal: input.signal,
+      maxTokens: input.maxTokens ?? 4096,
+      freshness: input.freshness
+    }));
+  }
+  input.signal?.throwIfAborted();
+  const byUrl = new Map;
+  for (const search of searches) {
+    limitations.push(...search.limitations);
+    for (const source of search.sources) {
+      const previous = byUrl.get(source.url);
+      byUrl.set(source.url, previous ? {
+        ...previous,
+        excerpts: [
+          ...new Set([...previous.excerpts, ...source.excerpts])
+        ]
+      } : source);
+    }
+  }
+  const normalize = (value) => value.normalize("NFKC").toLowerCase().replace(/\s+/gu, " ").trim();
+  const requiredPhrases = input.requiredPhrases ?? [...input.query.matchAll(/"([^"\n]+)"/gu)].map((match) => match[1]);
+  const sources = [...byUrl.values()].filter((source) => requiredPhrases.every((phrase) => normalize(`${source.title} ${source.excerpts.join(" ")}`).includes(normalize(phrase))));
+  if (sources.length < byUrl.size)
+    limitations.push("Sources that did not establish the required literal entity were excluded; similarly named entities are not substitutes.");
+  const complete = searches.length > 0 && searches.every((search) => search.status === "ok" || search.status === "empty") && requested.length <= maxQueries;
+  const base = { searches, sources, limitations, generatedAt };
+  if (!sources.length)
+    return {
+      ...base,
+      status: complete ? "empty" : "unavailable",
+      text: "",
+      findings: []
+    };
+  input.signal?.throwIfAborted();
+  const synthesis = await input.synthesize(evidenceText(sources), input.signal);
+  const findings = synthesis.findings.filter((finding) => {
+    const source = sources.find((source2) => source2.id === finding.sourceId);
+    return typeof finding.claim === "string" && Boolean(finding.claim.trim()) && typeof finding.quote === "string" && source && sourceSupportsQuote(source, finding.quote);
+  });
+  if (findings.length !== synthesis.findings.length)
+    limitations.push("Unsupported source references or quotations were excluded");
+  limitations.push(...synthesis.limitations ?? []);
+  const text = findings.map((finding) => `${finding.claim}
+Evidence: ${finding.quote}
+Source: ${sources.find((source) => source.id === finding.sourceId).url}`).join(`
+
+`);
+  return {
+    ...base,
+    status: complete && findings.length > 0 && !limitations.length ? "grounded" : "partial",
+    text,
+    findings
+  };
+};
+export {
+  researchWithEvidence
+};
+
+//# debugId=0CBE93DA058E304664756E2164756E21
+//# sourceMappingURL=research.js.map

package/dist/ai/research.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/ai/research.ts"],
+  "sourcesContent": [
+    "import {\n  boundedQueries,\n  evidenceText,\n  sourceSupportsQuote,\n  type SearchProvider,\n  type SearchResult,\n  type SearchSource,\n} from \"@absolutejs/search\";\nexport type ResearchFinding = {\n  claim: string;\n  sourceId: string;\n  quote: string;\n  eventDate?: string;\n};\nexport type ResearchEvidence = {\n  status: \"grounded\" | \"partial\" | \"empty\" | \"unavailable\";\n  text: string;\n  findings: ResearchFinding[];\n  sources: SearchSource[];\n  searches: SearchResult[];\n  limitations: string[];\n  generatedAt: string;\n};\nexport type ResearchSynthesis = {\n  findings: ResearchFinding[];\n  limitations?: string[];\n};\n/** Retrieval and synthesis are separate injected capabilities. No hosted search is enabled here. */\nexport const researchWithEvidence = async (input: {\n  query: string;\n  queries?: string[];\n  provider: SearchProvider;\n  signal?: AbortSignal;\n  maxQueries?: number;\n  maxTokens?: number;\n  freshness?: string;\n  /** Required literal entity phrases; defaults to quoted phrases in the question. */\n  requiredPhrases?: string[];\n  synthesize: (\n    evidence: string,\n    signal?: AbortSignal,\n  ) => Promise<ResearchSynthesis>;\n}): Promise<ResearchEvidence> => {\n  const requested = input.queries ?? boundedQueries(input.query);\n  const maxQueries = input.maxQueries ?? 2;\n  if (!Number.isInteger(maxQueries) || maxQueries < 1)\n    throw new Error(\"Research requires a positive query budget\");\n  const searches: SearchResult[] = [];\n  const limitations: string[] = [];\n  const generatedAt = new Date().toISOString();\n  if (requested.length > maxQueries)\n    limitations.push(\n      \"Query budget reached; some requested research was not performed\",\n    );\n  for (const query of requested.slice(0, maxQueries)) {\n    input.signal?.throwIfAborted();\n    searches.push(\n      await input.provider.search({\n        query,\n        mode: \"context\",\n        signal: input.signal,\n        maxTokens: input.maxTokens ?? 4096,\n        freshness: input.freshness,\n      }),\n    );\n  }\n  input.signal?.throwIfAborted();\n  const byUrl = new Map<string, SearchSource>();\n  for (const search of searches) {\n    limitations.push(...search.limitations);\n    for (const source of search.sources) {\n      const previous = byUrl.get(source.url);\n      byUrl.set(\n        source.url,\n        previous\n          ? {\n              ...previous,\n              excerpts: [\n                ...new Set([...previous.excerpts, ...source.excerpts]),\n              ],\n            }\n          : source,\n      );\n    }\n  }\n  const normalize = (value: string) =>\n    value.normalize(\"NFKC\").toLowerCase().replace(/\\s+/gu, \" \").trim();\n  const requiredPhrases =\n    input.requiredPhrases ??\n    [...input.query.matchAll(/\"([^\"\\n]+)\"/gu)].map((match) => match[1]!);\n  const sources = [...byUrl.values()].filter((source) =>\n    requiredPhrases.every((phrase) =>\n      normalize(`${source.title} ${source.excerpts.join(\" \")}`).includes(\n        normalize(phrase),\n      ),\n    ),\n  );\n  if (sources.length < byUrl.size)\n    limitations.push(\n      \"Sources that did not establish the required literal entity were excluded; similarly named entities are not substitutes.\",\n    );\n  const complete =\n    searches.length > 0 &&\n    searches.every(\n      (search) => search.status === \"ok\" || search.status === \"empty\",\n    ) &&\n    requested.length <= maxQueries;\n  const base = { searches, sources, limitations, generatedAt };\n  if (!sources.length)\n    return {\n      ...base,\n      status: complete ? \"empty\" : \"unavailable\",\n      text: \"\",\n      findings: [],\n    };\n  input.signal?.throwIfAborted();\n  const synthesis = await input.synthesize(evidenceText(sources), input.signal);\n  const findings = synthesis.findings.filter((finding) => {\n    const source = sources.find((source) => source.id === finding.sourceId);\n    return (\n      typeof finding.claim === \"string\" &&\n      Boolean(finding.claim.trim()) &&\n      typeof finding.quote === \"string\" &&\n      source &&\n      sourceSupportsQuote(source, finding.quote)\n    );\n  });\n  if (findings.length !== synthesis.findings.length)\n    limitations.push(\n      \"Unsupported source references or quotations were excluded\",\n    );\n  limitations.push(...(synthesis.limitations ?? []));\n  const text = findings\n    .map(\n      (finding) =>\n        `${finding.claim}\\nEvidence: ${finding.quote}\\nSource: ${sources.find((source) => source.id === finding.sourceId)!.url}`,\n    )\n    .join(\"\\n\\n\");\n  // Quotation/source checks establish provenance, not semantic entailment. Host review remains necessary.\n  return {\n    ...base,\n    status:\n      complete && findings.length > 0 && !limitations.length\n        ? \"grounded\"\n        : \"partial\",\n    text,\n    findings,\n  };\n};\n"
+  ],
+  "mappings": ";;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA4BO,IAAM,uBAAuB,OAAO,UAcV;AAAA,EAC/B,MAAM,YAAY,MAAM,WAAW,eAAe,MAAM,KAAK;AAAA,EAC7D,MAAM,aAAa,MAAM,cAAc;AAAA,EACvC,IAAI,CAAC,OAAO,UAAU,UAAU,KAAK,aAAa;AAAA,IAChD,MAAM,IAAI,MAAM,2CAA2C;AAAA,EAC7D,MAAM,WAA2B,CAAC;AAAA,EAClC,MAAM,cAAwB,CAAC;AAAA,EAC/B,MAAM,cAAc,IAAI,KAAK,EAAE,YAAY;AAAA,EAC3C,IAAI,UAAU,SAAS;AAAA,IACrB,YAAY,KACV,iEACF;AAAA,EACF,WAAW,SAAS,UAAU,MAAM,GAAG,UAAU,GAAG;AAAA,IAClD,MAAM,QAAQ,eAAe;AAAA,IAC7B,SAAS,KACP,MAAM,MAAM,SAAS,OAAO;AAAA,MAC1B;AAAA,MACA,MAAM;AAAA,MACN,QAAQ,MAAM;AAAA,MACd,WAAW,MAAM,aAAa;AAAA,MAC9B,WAAW,MAAM;AAAA,IACnB,CAAC,CACH;AAAA,EACF;AAAA,EACA,MAAM,QAAQ,eAAe;AAAA,EAC7B,MAAM,QAAQ,IAAI;AAAA,EAClB,WAAW,UAAU,UAAU;AAAA,IAC7B,YAAY,KAAK,GAAG,OAAO,WAAW;AAAA,IACtC,WAAW,UAAU,OAAO,SAAS;AAAA,MACnC,MAAM,WAAW,MAAM,IAAI,OAAO,GAAG;AAAA,MACrC,MAAM,IACJ,OAAO,KACP,WACI;AAAA,WACK;AAAA,QACH,UAAU;AAAA,UACR,GAAG,IAAI,IAAI,CAAC,GAAG,SAAS,UAAU,GAAG,OAAO,QAAQ,CAAC;AAAA,QACvD;AAAA,MACF,IACA,MACN;AAAA,IACF;AAAA,EACF;AAAA,EACA,MAAM,YAAY,CAAC,UACjB,MAAM,UAAU,MAAM,EAAE,YAAY,EAAE,QAAQ,SAAS,GAAG,EAAE,KAAK;AAAA,EACnE,MAAM,kBACJ,MAAM,mBACN,CAAC,GAAG,MAAM,MAAM,SAAS,eAAe,CAAC,EAAE,IAAI,CAAC,UAAU,MAAM,EAAG;AAAA,EACrE,MAAM,UAAU,CAAC,GAAG,MAAM,OAAO,CAAC,EAAE,OAAO,CAAC,WAC1C,gBAAgB,MAAM,CAAC,WACrB,UAAU,GAAG,OAAO,SAAS,OAAO,SAAS,KAAK,GAAG,GAAG,EAAE,SACxD,UAAU,MAAM,CAClB,CACF,CACF;AAAA,EACA,IAAI,QAAQ,SAAS,MAAM;AAAA,IACzB,YAAY,KACV,yHACF;AAAA,EACF,MAAM,WACJ,SAAS,SAAS,KAClB,SAAS,MACP,CAAC,WAAW,OAAO,WAAW,QAAQ,OAAO,WAAW,OAC1D,KACA,UAAU,UAAU;AAAA,EACtB,MAAM,OAAO,EAAE,UAAU,SAAS,aAAa,YAAY;AAAA,EAC3D,IAAI,CAAC,QAAQ;AAAA,IACX,OAAO;AAAA,SACF;AAAA,MACH,QAAQ,WAAW,UAAU;AAAA,MAC7B,MAAM;AAAA,MACN,UAAU,CAAC;AAAA,IACb;AAAA,EACF,MAAM,QAAQ,eAAe;AAAA,EAC7B,MAAM,YAAY,MAAM,MAAM,WAAW,aAAa,OAAO,GAAG,MAAM,MAAM;AAAA,EAC5E,MAAM,WAAW,UAAU,SAAS,OAAO,CAAC,YAAY;AAAA,IACtD,MAAM,SAAS,QAAQ,KAAK,CAAC,YAAW,QAAO,OAAO,QAAQ,QAAQ;AAAA,IACtE,OACE,OAAO,QAAQ,UAAU,YACzB,QAAQ,QAAQ,MAAM,KAAK,CAAC,KAC5B,OAAO,QAAQ,UAAU,YACzB,UACA,oBAAoB,QAAQ,QAAQ,KAAK;AAAA,GAE5C;AAAA,EACD,IAAI,SAAS,WAAW,UAAU,SAAS;AAAA,IACzC,YAAY,KACV,2DACF;AAAA,EACF,YAAY,KAAK,GAAI,UAAU,eAAe,CAAC,CAAE;AAAA,EACjD,MAAM,OAAO,SACV,IACC,CAAC,YACC,GAAG,QAAQ;AAAA,YAAoB,QAAQ;AAAA,UAAkB,QAAQ,KAAK,CAAC,WAAW,OAAO,OAAO,QAAQ,QAAQ,EAAG,KACvH,EACC,KAAK;AAAA;AAAA,CAAM;AAAA,EAEd,OAAO;AAAA,OACF;AAAA,IACH,QACE,YAAY,SAAS,SAAS,KAAK,CAAC,YAAY,SAC5C,aACA;AAAA,IACN;AAAA,IACA;AAAA,EACF;AAAA;",
+  "debugId": "0CBE93DA058E304664756E2164756E21",
+  "names": []
+}

package/dist/src/ai/generateAI.d.ts

@@ -6,6 +6,7 @@ export type GenerateAIToolCall = {
     input: unknown;
 };
 export type GenerateAIOptions = {
+    maxRetries?: number;
     contextPolicy?: AIContextPolicy | false;
     provider: AIProviderConfig;
     model: string;
@@ -73,6 +74,7 @@ export declare const toProviderTools: (tools: AIToolMap) => AIProviderToolDefini
  */
 export declare const generateAIWithTools: (options: GenerateAIWithToolsOptions) => Promise<GenerateAIWithToolsResult>;
 export type GenerateObjectAIOptions<T> = {
+    maxRetries?: number;
     contextPolicy?: AIContextPolicy | false;
     provider: AIProviderConfig;
     model: string;

package/dist/src/ai/models/catalog.d.ts

@@ -1,4 +1,5 @@
 import type { ModelMetadata } from "./index";
-/** Reviewed provider support, independent of application feature availability. */
+/** Reviewed provider support, independent of application feature availability.
+ * Anthropic entries come from the Models API (`max_input_tokens`, `capabilities`). */
 export declare const MODEL_METADATA: Readonly<Record<string, ModelMetadata>>;
 export declare const getModelMetadata: (provider: string, id: string) => ModelMetadata | undefined;

package/dist/src/ai/models/directory.d.ts

@@ -0,0 +1,38 @@
+import { modelCapabilities } from "./index";
+/** Display names for the providers the directory covers. */
+export declare const MODEL_PROVIDERS: Readonly<Record<string, string>>;
+export type ModelDirectoryEntry = {
+    provider: string;
+    /** The exact model ID sent to the provider. */
+    id: string;
+    name: string;
+    /** One short, plain sentence for pickers. */
+    description: string;
+    /** A current flagship worth showing first. */
+    featured?: boolean;
+    /** Superseded by a newer model in the same line; hide by default. */
+    legacy?: boolean;
+};
+/**
+ * Human-facing model directory for pickers, newest first within each provider.
+ * Capabilities and context windows come from MODEL_METADATA, not from here.
+ * Anthropic entries were checked against the Models API on 2026-09-25.
+ */
+export declare const MODEL_DIRECTORY: readonly ModelDirectoryEntry[];
+export declare const modelKey: (model: {
+    provider: string;
+    id: string;
+}) => string;
+export type ListedModel = ModelDirectoryEntry & {
+    key: string;
+    providerName: string;
+    capabilities: ReturnType<typeof modelCapabilities>;
+    contextWindow: number | null;
+    reasoningEfforts: readonly string[];
+};
+/** Directory entries joined with reviewed metadata, ready for a picker. */
+export declare const listModels: (options?: {
+    providers?: readonly string[];
+    includeLegacy?: boolean;
+}) => ListedModel[];
+export declare const findModel: (provider: string, id: string) => ModelDirectoryEntry | undefined;

package/dist/src/ai/models/index.d.ts

@@ -30,3 +30,4 @@ export type ModelCapability = keyof typeof MODEL_CAPABILITY_DESCRIPTIONS;
 export declare const modelCapabilities: (metadata?: ModelMetadata) => ModelCapability[];
 export { MODEL_METADATA, getModelMetadata } from "./catalog";
 export { MODEL_REASONING, REASONING_EFFORTS, getModelReasoning, isReasoningSelection, supportsReasoningSelection, reasoningSelectionLabel, type ModelReasoning, type ReasoningSelection, } from "./reasoning";
+export { MODEL_DIRECTORY, MODEL_PROVIDERS, findModel, listModels, modelKey, type ListedModel, type ModelDirectoryEntry, } from "./directory";

package/dist/src/ai/models/reasoning.d.ts

@@ -8,7 +8,8 @@ export type ModelReasoning = {
     source: string;
 };
 export declare const isReasoningSelection: (value: unknown) => value is ReasoningSelection;
-/** Exact reviewed IDs; unknown models expose only the provider default. Reviewed 2026-09-20. */
+/** Exact reviewed IDs; unknown models expose only the provider default. Reviewed 2026-09-20;
+ * Anthropic effort levels re-checked against the Models API 2026-09-25. */
 export declare const MODEL_REASONING: Readonly<Record<string, ModelReasoning>>;
 export declare const getModelReasoning: (provider: string, model: string) => ModelReasoning | undefined;
 export declare const supportsReasoningSelection: (provider: string, model: string, selection: ReasoningSelection) => boolean;

package/dist/src/ai/research.d.ts

@@ -0,0 +1,33 @@
+import { type SearchProvider, type SearchResult, type SearchSource } from "@absolutejs/search";
+export type ResearchFinding = {
+    claim: string;
+    sourceId: string;
+    quote: string;
+    eventDate?: string;
+};
+export type ResearchEvidence = {
+    status: "grounded" | "partial" | "empty" | "unavailable";
+    text: string;
+    findings: ResearchFinding[];
+    sources: SearchSource[];
+    searches: SearchResult[];
+    limitations: string[];
+    generatedAt: string;
+};
+export type ResearchSynthesis = {
+    findings: ResearchFinding[];
+    limitations?: string[];
+};
+/** Retrieval and synthesis are separate injected capabilities. No hosted search is enabled here. */
+export declare const researchWithEvidence: (input: {
+    query: string;
+    queries?: string[];
+    provider: SearchProvider;
+    signal?: AbortSignal;
+    maxQueries?: number;
+    maxTokens?: number;
+    freshness?: string;
+    /** Required literal entity phrases; defaults to quoted phrases in the question. */
+    requiredPhrases?: string[];
+    synthesize: (evidence: string, signal?: AbortSignal) => Promise<ResearchSynthesis>;
+}) => Promise<ResearchEvidence>;

package/dist/src/ai/research.test.d.ts

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

package/dist/types/ai.d.ts

@@ -204,6 +204,8 @@ export type ReasoningConfig = {
     effort?: ReasoningEffort;
 };
 export type AIProviderStreamParams = {
+    /** Override transport retries for operations whose host owns attempt accounting. */
+    maxRetries?: number;
     /**
      * Mark the system prompt as cacheable (Anthropic prompt caching). The system
      * block is sent with `cache_control: ephemeral`, so repeated calls reusing the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/ai",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "homepage": "https://github.com/absolutejs/ai",
   "bugs": {
     "url": "https://github.com/absolutejs/ai/issues"
@@ -92,11 +92,16 @@
     "./models": {
       "import": "./dist/ai/models/index.js",
       "types": "./dist/src/ai/models/index.d.ts"
+    },
+    "./research": {
+      "types": "./dist/src/ai/research.d.ts",
+      "import": "./dist/ai/research.js"
     }
   },
   "dependencies": {
     "@absolutejs/linked-providers": "0.0.2",
-    "@openrouter/sdk": "^1.2.47"
+    "@openrouter/sdk": "^1.2.47",
+    "@absolutejs/search": "^0.1.0"
   },
   "peerDependencies": {
     "@absolutejs/isolated-jsc": ">= 0.4.0",