@spendgraph/tools 0.6.0 → 0.8.0

package/dist/memories/remember/remember.js

@@ -0,0 +1 @@
+import{tool as h}from"../../tool/index.js";import{contextId as y,contextIds as a,fixedRoot as x,rootOf as w}from"../context.js";const g=["fact","decision","constraint","feedback","observation"],b="assistant",C=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),q=(e,t)=>{if(t==null)return{data:e};if(!C(t))throw new Error("details must be a JSON object of named fields.");return{...t,data:e}},d=(e,t)=>t?.length?{[e]:t}:{};function v(e){const t=e.defaultContextType,u=e.rootContextId===void 0?"":` under ${x(e.rootContextId)??"your root"}`,m=(c,l)=>{const s=w(e.rootContextId),i=a(l,t)??[],r=s?[s,...i]:i;return[...new Set(r)].filter(n=>n!==c)};return h({name:"remember",effect:"idempotent",description:`Records one thing in your own memory${u} so a later run can recall it. File it under a context named type:name, like person:alice or decision:pricing_tier, reusing a name from explore_memory when one fits. One fact per call; the text should stand on its own without the conversation around it.`,args:[{name:"context",type:"string",required:!0,maxLength:200,description:"Where it is filed, as type:name."},{name:"text",type:"string",required:!0,maxLength:4e3,description:"The thing to remember, as a complete sentence or two."},{name:"kind",type:"enum",required:!1,options:g,description:"What sort of thing it is. Default fact."},{name:"details",type:"json",required:!1,description:"Structured fields worth keeping with the note, as a JSON object: amounts, dates, ids, URLs. The text is still what a recall shows; these ride along with it."},{name:"extends",type:"list",required:!1,description:"Contexts this is a more specific detail of, as type:name."},{name:"related_to",type:"list",required:!1,description:"Contexts this sits alongside, as type:name."},{name:"reinforces",type:"list",required:!1,description:"Contexts this backs up with more evidence, as type:name."},{name:"contradicts",type:"list",required:!1,description:"Contexts this supersedes, as type:name."}],run:async({context:c,text:l,kind:s="fact",details:i,...r})=>{const n=y(c,t),f={event_kind:s,context_id:n,source:e.source??b,payload:q(l,i),...d("extends",m(n,r.extends)),...d("related_to",a(r.related_to,t)),...d("reinforces",a(r.reinforces,t)),...d("contradicts",a(r.contradicts,t))},p=await e.client.storeEventsBatch([f],e.graphId),[o]=p.results;if(!o||o.status==="error")throw new Error(o?.error??"The memory was not stored, and the server did not say why.");return o.status==="filtered"?{stored:!1,context:n,reason:o.error??"judged not worth keeping"}:{stored:!0,context:n,relevance:o.relevance}}})}export{v as remember};

package/dist/papers/consensus/consensus.d.ts

@@ -0,0 +1,12 @@
+import { type PaperSearcher, type PaperSearcherOptions } from "../papers.js";
+export interface ConsensusOptions extends PaperSearcherOptions {
+    apiKey: string;
+    studyTypes?: string[];
+    humanOnly?: boolean;
+    controlledOnly?: boolean;
+    excludePreprints?: boolean;
+    minSampleSize?: number;
+    domain?: string;
+    journalName?: string;
+}
+export declare function consensus(opts: ConsensusOptions): PaperSearcher;

package/dist/papers/consensus/consensus.js

@@ -0,0 +1 @@
+import{retrying as l}from"../../search/retry.js";import{DEFAULT_MAX_PAPERS as m,paperLimit as d}from"../papers.js";import{readReply as y}from"./reply.js";const f="https://api.consensus.app/v1/search",_="consensus",S=6e4,h=500;function g(e){return{...e.studyTypes?.length?{study_types:e.studyTypes.join(",")}:{},...e.humanOnly?{human:"true"}:{},...e.controlledOnly?{controlled:"true"}:{},...e.excludePreprints?{exclude_preprints:"true"}:{},...e.minSampleSize?{sample_size_min:String(e.minSampleSize)}:{},...e.domain?{domain:e.domain}:{},...e.journalName?{journal_name:e.journalName}:{}}}function p(e){return{...e.yearMin===void 0?{}:{year_min:String(e.yearMin)},...e.yearMax===void 0?{}:{year_max:String(e.yearMax)},...e.minCitations===void 0?{}:{citation_min:String(e.minCitations)},...e.openAccess?{open_access:"true"}:{}}}function w(e){if(!e.apiKey?.trim())throw new Error("consensus needs an apiKey; it will not read one from the process.");const s=e.fetch??globalThis.fetch.bind(globalThis),o=e.maxResults??m,c=l(e);return Object.assign(async i=>{const t=d(i,o),a=new URL(f);for(const[r,u]of Object.entries({query:i.query,page_size:String(t),...p(i),...g(e)}))a.searchParams.set(r,u);const n=await c(()=>s(a,{signal:AbortSignal.timeout(e.timeoutMs??S),headers:{"x-api-key":e.apiKey,accept:"application/json"}}));if(!n.ok){const r=(await n.text()).slice(0,h);throw new Error(`Consensus returned ${n.status}: ${r}`)}return y(await n.json(),t,e.costMicroUsd)},{source:_})}export{w as consensus};

package/dist/papers/consensus/index.d.ts

@@ -0,0 +1,4 @@
+export type { ConsensusOptions } from "./consensus.js";
+export { consensus } from "./consensus.js";
+export type { ConsensusReply } from "./reply.js";
+export { readReply } from "./reply.js";

package/dist/papers/consensus/index.js

@@ -0,0 +1 @@
+import{consensus as r}from"./consensus.js";import{readReply as s}from"./reply.js";export{r as consensus,s as readReply};

package/dist/papers/consensus/reply.d.ts

@@ -0,0 +1,24 @@
+import type { PapersFound } from "../papers.js";
+interface RawResult {
+    title?: string | null;
+    authors?: string[] | null;
+    publish_year?: number | null;
+    doi?: string | null;
+    journal_name?: string | null;
+    citation_count?: number | null;
+    study_type?: string | null;
+    sample_size?: number | null;
+    takeaway?: string | null;
+    abstract?: string | null;
+    url?: string | null;
+    pdf_url?: string | null;
+}
+export interface ConsensusReply {
+    results?: RawResult[];
+    page?: number;
+    page_size?: number;
+    is_end?: boolean;
+    next_page?: number | null;
+}
+export declare function readReply(raw: ConsensusReply, maxResults: number, costMicroUsd?: number): PapersFound;
+export {};

package/dist/papers/consensus/reply.js

@@ -0,0 +1 @@
+const s="consensus";function i(t){return{title:t.title?.trim()||"(untitled)",year:t.publish_year??null,authors:t.authors??[],venue:t.journal_name||null,citations:t.citation_count??0,doi:t.doi?.replace(/^https?:\/\/doi\.org\//,"")||null,pdf:t.pdf_url||null,url:t.url||null,studyType:t.study_type||null,sampleSize:t.sample_size??null,takeaway:t.takeaway||null,abstract:t.abstract??""}}function o(t,u,e){const l=t.results??[],n=l.slice(0,u);return{papers:n.map(i),source:s,total:null,truncated:l.length>n.length||t.is_end===!1,...e===void 0?{}:{costMicroUsd:e}}}export{o as readReply};

package/dist/papers/every.d.ts

@@ -0,0 +1,6 @@
+import { type PaperSearcher } from "./papers.js";
+export interface EveryPaperOptions {
+    maxResults?: number;
+}
+export declare function listed(names: string[]): string;
+export declare function everyPaper(searchers: PaperSearcher[], opts?: EveryPaperOptions): PaperSearcher;

package/dist/papers/every.js

@@ -0,0 +1 @@
+import{DEFAULT_MAX_PAPERS as h,paperLimit as m}from"./papers.js";function g(e){const t=[];for(let n=0;;n++){let o=!1;for(const a of e){const u=a[n];u!==void 0&&(o=!0,t.push(u))}if(!o)return t}}function w(e){return e.doi?`doi:${e.doi.toLowerCase()}`:`title:${e.title.toLowerCase().replace(/[^a-z0-9]+/g," ").trim()}`}function v(e,t){return{title:e.title,year:e.year??t.year,authors:e.authors.length>0?e.authors:t.authors,venue:e.venue??t.venue,citations:Math.max(e.citations,t.citations),doi:e.doi??t.doi,pdf:e.pdf??t.pdf,url:e.url??t.url,studyType:e.studyType??t.studyType,sampleSize:e.sampleSize??t.sampleSize,takeaway:e.takeaway??t.takeaway,abstract:e.abstract||t.abstract}}function M(e){const t=new Map;for(const n of e){const o=w(n),a=t.get(o);t.set(o,a?v(a,n):n)}return[...t.values()]}const $=e=>e instanceof Error?e.message:String(e);function b(e){return e.map((t,n)=>t.source??`source ${n+1}`)}function f(e){return e.length<2?e[0]??"":`${e.slice(0,-1).join(", ")} and ${e.at(-1)}`}function x(e){const t=e.flatMap(n=>n.costMicroUsd===void 0?[]:[n.costMicroUsd]);return t.length>0?t.reduce((n,o)=>n+o,0):void 0}function E(e){const t=e.flatMap(n=>n.total===null?[]:[n.total]);return t.length>0?t.reduce((n,o)=>n+o,0):null}function L(e,t={}){if(e.length===0)throw new Error("everyPaper needs at least one paper searcher to run.");const n=b(e),o=t.maxResults??h;return Object.assign(async a=>{const u=m(a,o),p=await Promise.allSettled(e.map(r=>r({...a,limit:u}))),s=[],i=[];if(p.forEach((r,y)=>{r.status==="fulfilled"?s.push(r.value):i.push({source:n[y],reason:$(r.reason)})}),s.length===0)throw new Error(`No paper searcher answered. ${i.map(r=>`${r.source}: ${r.reason}`).join(" ")}`);const c=M(g(s.map(r=>r.papers))),l=c.slice(0,u),d=x(s);return{papers:l,source:f(s.map(r=>r.source)),total:E(s),truncated:c.length>l.length||s.some(r=>r.truncated),...d===void 0?{}:{costMicroUsd:d},...i.length>0?{failed:i}:{}}},{source:f(n)})}export{L as everyPaper,f as listed};

package/dist/papers/index.d.ts

@@ -0,0 +1,11 @@
+export type { ConsensusOptions, ConsensusReply } from "./consensus/index.js";
+export { consensus } from "./consensus/index.js";
+export type { EveryPaperOptions } from "./every.js";
+export { everyPaper } from "./every.js";
+export type { OpenAlexPapersOptions } from "./openalex/index.js";
+export { openAlexPapers } from "./openalex/index.js";
+export type { Paper, PaperAsk, PaperFailure, PaperFilters, PaperSearcher, PaperSearcherOptions, PapersFound, } from "./papers.js";
+export { DEFAULT_ABSTRACT_CHARS, DEFAULT_MAX_PAPERS } from "./papers.js";
+export { rendered } from "./render.js";
+export type { SemanticScholarOptions, SemanticScholarReply } from "./semantic-scholar/index.js";
+export { semanticScholar } from "./semantic-scholar/index.js";

package/dist/papers/index.js

@@ -0,0 +1 @@
+import{consensus as o}from"./consensus/index.js";import{everyPaper as A}from"./every.js";import{openAlexPapers as t}from"./openalex/index.js";import{DEFAULT_ABSTRACT_CHARS as f,DEFAULT_MAX_PAPERS as n}from"./papers.js";import{rendered as a}from"./render.js";import{semanticScholar as S}from"./semantic-scholar/index.js";export{f as DEFAULT_ABSTRACT_CHARS,n as DEFAULT_MAX_PAPERS,o as consensus,A as everyPaper,t as openAlexPapers,a as rendered,S as semanticScholar};

package/dist/papers/openalex/index.d.ts

@@ -0,0 +1,2 @@
+export type { OpenAlexPapersOptions } from "./openalex.js";
+export { openAlexPapers } from "./openalex.js";

package/dist/papers/openalex/index.js

@@ -0,0 +1 @@
+import{openAlexPapers as p}from"./openalex.js";export{p as openAlexPapers};

package/dist/papers/openalex/openalex.d.ts

@@ -0,0 +1,8 @@
+import { type ApiOptions, type OpenAlexApi } from "../../builtin/openalex/api.js";
+import { type PaperSearcher } from "../papers.js";
+export interface OpenAlexPapersOptions extends ApiOptions {
+    maxResults?: number;
+    costMicroUsd?: number;
+    api?: OpenAlexApi;
+}
+export declare function openAlexPapers(opts?: OpenAlexPapersOptions): PaperSearcher;

package/dist/papers/openalex/openalex.js

@@ -0,0 +1 @@
+import{openAlexApi as u}from"../../builtin/openalex/api.js";import{DEFAULT_MAX_PAPERS as c,paperLimit as l}from"../papers.js";const s="openalex";function p(e){return{...e,url:null,studyType:null,sampleSize:null,takeaway:null}}function d(e={}){const o=e.api??u(e),a=e.maxResults??c;return Object.assign(async n=>{const r=await o.search(n.query,l(n,a),n),t=r.costMicroUsd??e.costMicroUsd;return{papers:r.papers.map(p),source:s,total:null,truncated:!1,...t===void 0?{}:{costMicroUsd:t}}},{source:s})}export{d as openAlexPapers};

package/dist/papers/papers.d.ts

@@ -0,0 +1,54 @@
+export interface Paper {
+    title: string;
+    year: number | null;
+    authors: string[];
+    venue: string | null;
+    citations: number;
+    doi: string | null;
+    pdf: string | null;
+    url: string | null;
+    studyType: string | null;
+    sampleSize: number | null;
+    takeaway: string | null;
+    abstract: string;
+}
+export interface PaperFilters {
+    yearMin?: number;
+    yearMax?: number;
+    openAccess?: boolean;
+    minCitations?: number;
+}
+export interface PaperAsk extends PaperFilters {
+    query: string;
+    limit?: number;
+}
+export interface PaperFailure {
+    source: string;
+    reason: string;
+}
+export interface PapersFound {
+    papers: Paper[];
+    source: string;
+    total: number | null;
+    truncated: boolean;
+    costMicroUsd?: number;
+    failed?: PaperFailure[];
+}
+export type PaperSearcher = ((ask: PaperAsk) => Promise<PapersFound>) & {
+    source?: string;
+};
+export interface PaperSearcherOptions {
+    maxResults?: number;
+    costMicroUsd?: number;
+    timeoutMs?: number;
+    attempts?: number;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+}
+export declare const DEFAULT_MAX_PAPERS = 10;
+export declare const DEFAULT_ABSTRACT_CHARS = 400;
+export declare function paperLimit(ask: PaperAsk, ceiling: number): number;
+export declare function yearRange({ yearMin, yearMax }: PaperFilters): string | null;
+export declare const MICRO_USD = 1000000;
+export declare const microUsd: (usd: number | undefined) => number | undefined;

package/dist/papers/papers.js

@@ -0,0 +1 @@
+const r=10,o=400;function i(t,n){return Math.max(1,Math.min(t.limit??n,n))}function u({yearMin:t,yearMax:n}){return t===void 0&&n===void 0?null:`${t??""}-${n??""}`}const e=1e6,p=t=>typeof t=="number"&&Number.isFinite(t)?Math.round(t*e):void 0;export{o as DEFAULT_ABSTRACT_CHARS,r as DEFAULT_MAX_PAPERS,e as MICRO_USD,p as microUsd,i as paperLimit,u as yearRange};

package/dist/papers/render.d.ts

@@ -0,0 +1,2 @@
+import type { Paper } from "./papers.js";
+export declare function rendered(query: string, papers: readonly Paper[], maxChars: number): string;

package/dist/papers/render.js

@@ -0,0 +1,4 @@
+const m=3;function c(n){const t=n.authors.slice(0,3).map(e=>e.split(" ").at(-1)??e),o=n.authors.length-t.length;return t.length===0?"unknown authors":o>0?`${t.join(", ")} +${o}`:t.join(", ")}function d(n){const t=n.year===null?"":` (${n.year})`,o=n.venue?` \xB7 ${n.venue}`:"";return`${n.title}${t} \u2014 ${c(n)}${o} \xB7 ${n.citations} citations`}function $(n){const o=[n.studyType,n.sampleSize===null?null:`n=${n.sampleSize}`].filter(e=>!!e);return o.length>0?o.join(" \xB7 "):null}function f(n){const o=[n.doi?`doi:${n.doi}`:null,n.pdf?`pdf: ${n.pdf}`:null].filter(e=>e!==null);return o.length>0?o.join(" \xB7 "):n.url}function h(n){const t=n.takeaway?.trim();return t?`Found: ${t}`:null}function a(n,t){const o=n.abstract.trim();return o?o.length>t?`${o.slice(0,t).trimEnd()}\u2026`:o:null}function g(n,t,o){const e=`${t.length} paper${t.length===1?"":"s"} on "${n}", most relevant first`,i=t.map((u,s)=>[`${s+1}. ${d(u)}`,$(u),f(u),h(u),a(u,o)].filter(l=>l!==null).map((l,r)=>r===0?l:`   ${l}`).join(`
+`));return[e,...i].join(`
+
+`)}export{g as rendered};

package/dist/papers/semantic-scholar/index.d.ts

@@ -0,0 +1,4 @@
+export type { SemanticScholarReply } from "./reply.js";
+export { readReply } from "./reply.js";
+export type { SemanticScholarOptions } from "./semantic-scholar.js";
+export { semanticScholar } from "./semantic-scholar.js";

package/dist/papers/semantic-scholar/index.js

@@ -0,0 +1 @@
+import{readReply as o}from"./reply.js";import{semanticScholar as m}from"./semantic-scholar.js";export{o as readReply,m as semanticScholar};

package/dist/papers/semantic-scholar/reply.d.ts

@@ -0,0 +1,29 @@
+import type { PapersFound } from "../papers.js";
+interface RawPaper {
+    title?: string | null;
+    abstract?: string | null;
+    year?: number | null;
+    venue?: string | null;
+    citationCount?: number | null;
+    authors?: {
+        name?: string | null;
+    }[] | null;
+    externalIds?: {
+        DOI?: string | null;
+    } | null;
+    openAccessPdf?: {
+        url?: string | null;
+    } | null;
+    url?: string | null;
+    tldr?: {
+        text?: string | null;
+    } | null;
+}
+export interface SemanticScholarReply {
+    total?: number;
+    offset?: number;
+    next?: number;
+    data?: RawPaper[];
+}
+export declare function readReply(raw: SemanticScholarReply, maxResults: number, costMicroUsd?: number): PapersFound;
+export {};

package/dist/papers/semantic-scholar/reply.js

@@ -0,0 +1 @@
+const s="semantic-scholar";function o(t){return{title:t.title?.trim()||"(untitled)",year:t.year??null,authors:(t.authors??[]).flatMap(l=>l.name?[l.name]:[]),venue:t.venue?.trim()||null,citations:t.citationCount??0,doi:t.externalIds?.DOI||null,pdf:t.openAccessPdf?.url||null,url:t.url||null,studyType:null,sampleSize:null,takeaway:t.tldr?.text||null,abstract:t.abstract??""}}function c(t,l,u){const a=t.data??[],n=a.slice(0,l),e=t.total??null;return{papers:n.map(o),source:s,total:e,truncated:a.length>n.length||e!==null&&e>n.length,...u===void 0?{}:{costMicroUsd:u}}}export{c as readReply};

package/dist/papers/semantic-scholar/semantic-scholar.d.ts

@@ -0,0 +1,8 @@
+import { type PaperSearcher, type PaperSearcherOptions } from "../papers.js";
+export interface SemanticScholarOptions extends PaperSearcherOptions {
+    apiKey?: string;
+    fieldsOfStudy?: string[];
+    publicationTypes?: string[];
+    venues?: string[];
+}
+export declare function semanticScholar(opts?: SemanticScholarOptions): PaperSearcher;

package/dist/papers/semantic-scholar/semantic-scholar.js

@@ -0,0 +1 @@
+import{retrying as u}from"../../search/retry.js";import{DEFAULT_MAX_PAPERS as f,paperLimit as d,yearRange as m}from"../papers.js";import{readReply as h}from"./reply.js";const y="https://api.semanticscholar.org/graph/v1/paper/search",p="semantic-scholar",S=6e4,g=500,A=["title","abstract","year","venue","citationCount","authors","externalIds","openAccessPdf","url","tldr"].join(",");function T(e){return{...e.fieldsOfStudy?.length?{fieldsOfStudy:e.fieldsOfStudy.join(",")}:{},...e.publicationTypes?.length?{publicationTypes:e.publicationTypes.join(",")}:{},...e.venues?.length?{venue:e.venues.join(",")}:{}}}function R(e){const t=m(e);return{...t===null?{}:{year:t},...e.minCitations===void 0?{}:{minCitationCount:String(e.minCitations)},...e.openAccess?{openAccessPdf:""}:{}}}function j(e={}){const t=e.fetch??globalThis.fetch.bind(globalThis),s=e.maxResults??f,c=u(e);return Object.assign(async i=>{const a=d(i,s),o=new URL(y);for(const[r,l]of Object.entries({query:i.query,limit:String(a),fields:A,...R(i),...T(e)}))o.searchParams.set(r,l);const n=await c(()=>t(o,{signal:AbortSignal.timeout(e.timeoutMs??S),headers:{accept:"application/json",...e.apiKey?{"x-api-key":e.apiKey}:{}}}));if(!n.ok){const r=(await n.text()).slice(0,g);throw new Error(`Semantic Scholar returned ${n.status}: ${r}`)}return h(await n.json(),a,e.costMicroUsd)},{source:p})}export{j as semanticScholar};

package/dist/search/every.d.ts

@@ -0,0 +1,6 @@
+import { type Searcher } from "./search.js";
+export interface EverySearchOptions {
+    maxChars?: number;
+    maxResults?: number;
+}
+export declare function everySearch(searchers: Searcher[], opts?: EverySearchOptions): Searcher;

package/dist/search/every.js

@@ -0,0 +1,4 @@
+import{DEFAULT_MAX_CHARS as T,DEFAULT_MAX_RESULTS as k}from"./search.js";const g={inputTokens:0,outputTokens:0,citationTokens:0,reasoningTokens:0,searchQueries:0};function w(e){return e.reduce((n,t)=>({inputTokens:n.inputTokens+t.inputTokens,outputTokens:n.outputTokens+t.outputTokens,citationTokens:n.citationTokens+t.citationTokens,reasoningTokens:n.reasoningTokens+t.reasoningTokens,searchQueries:n.searchQueries+t.searchQueries}),g)}function S(e){const n=[];for(let t=0;;t++){let r=!1;for(const u of e){const a=u[t];a!==void 0&&(r=!0,n.push(a))}if(!r)return n}}const d=e=>e.url.replace(/\/+$/,"").toLowerCase();function E(e){const n=new Set;return e.filter(t=>!n.has(d(t))&&n.add(d(t)))}const $=e=>e instanceof Error?e.message:String(e);function v(e){return e.map((n,t)=>n.source??`searcher ${t+1}`)}function x(e){if(e.every(n=>n.domains?.length))return[...new Set(e.flatMap(n=>[...n.domains??[]]))]}const j=e=>`# via ${e.model}
+${e.answer}`;function A(e,n={}){if(e.length===0)throw new Error("everySearch needs at least one searcher to run.");const t=v(e),r=n.maxChars??T,u=n.maxResults??k,a=x(e);return Object.assign(async m=>{const p=await Promise.allSettled(e.map(s=>s(m))),o=[],i=[];if(p.forEach((s,h)=>{s.status==="fulfilled"?o.push(s.value):i.push({source:t[h],reason:$(s.reason)})}),o.length===0)throw new Error(`No searcher answered. ${i.map(s=>`${s.source}: ${s.reason}`).join(" ")}`);const c=o.map(j).join(`
+
+`),l=E(S(o.map(s=>s.results))),f=l.slice(0,u);return{answer:c.slice(0,r),results:f,model:o.map(s=>s.model).join(", "),truncated:c.length>r||l.length>f.length||o.some(s=>s.truncated),usage:w(o.map(s=>s.usage)),...i.length>0?{failed:i}:{}}},{source:t.join(", "),...a?{domains:a}:{}})}export{A as everySearch};

package/dist/search/index.d.ts

@@ -0,0 +1,7 @@
+export type { EverySearchOptions } from "./every.js";
+export { everySearch } from "./every.js";
+export type { Recency, SearchAsk, SearchDepth, Searched, Searcher, SearcherOptions, SearchFailure, SearchUsage, Source, } from "./search.js";
+export { DEPTHS, NO_TOKENS } from "./search.js";
+export { type SearxngOptions, searxng, textOf } from "./searxng/index.js";
+export { readReply, type SonarOptions, sonar } from "./sonar/index.js";
+export { type TavilyOptions, tavily } from "./tavily/index.js";

package/dist/search/index.js

@@ -0,0 +1 @@
+import{everySearch as o}from"./every.js";import{DEPTHS as x,NO_TOKENS as f}from"./search.js";import{searxng as a,textOf as m}from"./searxng/index.js";import{readReply as O,sonar as S}from"./sonar/index.js";import{tavily as n}from"./tavily/index.js";export{x as DEPTHS,f as NO_TOKENS,o as everySearch,O as readReply,a as searxng,S as sonar,n as tavily,m as textOf};

package/dist/search/retry.d.ts

@@ -0,0 +1,6 @@
+import type { SearcherOptions } from "./search.js";
+/**
+ * Sends again while the answer is a 429 or a 5xx and tries remain, then hands
+ * back whatever came last, ok or not, for the caller to read or refuse.
+ */
+export declare function retrying(opts: Pick<SearcherOptions, "attempts" | "sleep" | "random">): (send: () => Promise<Response>) => Promise<Response>;

package/dist/search/retry.js

@@ -0,0 +1 @@
+const M=500,f=8e3;function m(t){const r=t.headers.get("retry-after");if(!r)return null;const e=Number(r);return Number.isFinite(e)&&e>=0?e*1e3:null}const u=t=>t===429||t>=500;function A(t){const r=Math.max(1,t.attempts??3),e=t.sleep??(o=>new Promise(n=>setTimeout(n,o))),c=t.random??Math.random;return async o=>{for(let n=1;;n++){const s=await o();if(s.ok||!u(s.status)||n===r)return s;const a=Math.min(8e3,500*2**(n-1)),i=m(s)??a;await e(i+a*c())}}}export{A as retrying};

package/dist/search/search.d.ts

@@ -0,0 +1,69 @@
+/** How much searching one call is worth. */
+export type SearchDepth = "quick" | "pro" | "deep";
+export declare const DEPTHS: readonly SearchDepth[];
+export type Recency = "day" | "week" | "month" | "year";
+export interface Source {
+    url: string;
+    title?: string;
+    date?: string;
+}
+export interface SearchUsage {
+    inputTokens: number;
+    outputTokens: number;
+    citationTokens: number;
+    reasoningTokens: number;
+    searchQueries: number;
+}
+export interface SearchFailure {
+    source: string;
+    reason: string;
+}
+/** What every searcher hands back, whoever did the searching. */
+export interface Searched {
+    answer: string;
+    results: Source[];
+    model: string;
+    truncated: boolean;
+    usage: SearchUsage;
+    failed?: SearchFailure[];
+}
+export interface SearchAsk {
+    query: string;
+    depth: SearchDepth;
+    recency?: Recency;
+}
+export type Searcher = ((ask: SearchAsk) => Promise<Searched>) & {
+    domains?: readonly string[];
+    source?: string;
+};
+/** What every searcher is configured with; each adds only where its answers come from. */
+export interface SearcherOptions {
+    /** Hosts results are restricted to. Set here, so the model cannot widen it. */
+    domains?: string[];
+    /** Give up on a request after this. */
+    timeoutMs?: number;
+    /** Longest answer handed back. Default 20000 characters. */
+    maxChars?: number;
+    /** Longest source list handed back. Default 20. */
+    maxResults?: number;
+    /**
+     * Tries for a rate limit or a bad minute on the other side. Default 3.
+     *
+     * A wave of sub-questions searches in parallel, so two calls landing together
+     * is ordinary and a 429 on the second is not a failure worth surfacing — it
+     * is a wait. `retry-after` is honoured where the server sends one, and the
+     * wait is spread by up to one backoff on top: a whole wave limited at the
+     * same instant computes the same delay, and retrying in step rebuilds the
+     * burst that caused it.
+     */
+    attempts?: number;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+    /** Injected for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injected for tests. Returns 0 to 1, and spreads a retried wave apart. */
+    random?: () => number;
+}
+export declare const DEFAULT_MAX_CHARS = 20000;
+export declare const DEFAULT_MAX_RESULTS = 20;
+export declare const NO_TOKENS: SearchUsage;

package/dist/search/search.js

@@ -0,0 +1 @@
+const o=["quick","pro","deep"],e=2e4,t=20,n={inputTokens:0,outputTokens:0,citationTokens:0,reasoningTokens:0,searchQueries:1};export{e as DEFAULT_MAX_CHARS,t as DEFAULT_MAX_RESULTS,o as DEPTHS,n as NO_TOKENS};

package/dist/search/searxng/index.d.ts

@@ -0,0 +1,2 @@
+export { type SearxngOptions, searxng } from "./searxng.js";
+export { textOf } from "./text.js";

package/dist/search/searxng/index.js

@@ -0,0 +1 @@
+import{searxng as o}from"./searxng.js";import{textOf as x}from"./text.js";export{o as searxng,x as textOf};

package/dist/search/searxng/searxng.d.ts

@@ -0,0 +1,14 @@
+import { type SearchDepth, type Searcher, type SearcherOptions } from "../search.js";
+export interface SearxngOptions extends SearcherOptions {
+    /** The SearXNG instance, such as http://localhost:8080. Required. */
+    baseUrl: string;
+    /** Pin which engines answer. Default: whatever the instance runs. */
+    engines?: string[];
+    /** Pin the language. Default: the instance's own. */
+    language?: string;
+    /** Text kept from each page read. Default 6000 characters. */
+    pageChars?: number;
+    /** Pages read at each depth. Default 5, 8 and 10. */
+    pages?: Partial<Record<SearchDepth, number>>;
+}
+export declare function searxng(opts: SearxngOptions): Searcher;

package/dist/search/searxng/searxng.js

@@ -0,0 +1,5 @@
+import{checkUrl as x}from"../../builtin/http/allow.js";import{retrying as y}from"../retry.js";import{DEFAULT_MAX_CHARS as N,DEFAULT_MAX_RESULTS as F,NO_TOKENS as A}from"../search.js";import{textOf as T}from"./text.js";const f="searxng",U=["*"],G=2e4,X=6e3,L=4e5,H={quick:5,pro:8,deep:10},I=/https?:\/\/[^\s"'<>)\]]+/,Q=2;function W(t){return!t.url||!t.title?null:{url:t.url,title:t.title,...t.publishedDate?{date:t.publishedDate}:{},snippet:t.content??""}}function q({url:t,title:r,date:i}){return{url:t,title:r,...i?{date:i}:{}}}function K(t,r){return`## ${t.title}
+${t.url}
+${r}`}const Y=3,v=t=>t.status>=300&&t.status<400;function R(t,r){if(!r?.length)return!0;const i=new URL(t.url).hostname.toLowerCase();return r.some(u=>{const h=u.toLowerCase().replace(/^\./,"");return i===h||i.endsWith(`.${h}`)})}function z(t){const r=new Set;return t.flatMap(i=>i.hits).filter(i=>!r.has(i.url)&&r.add(i.url))}function tt(t){if(!t.baseUrl?.trim())throw new Error("searxng needs the baseUrl of a SearXNG instance, such as http://localhost:8080.");const r=t.fetch??globalThis.fetch.bind(globalThis),i=t.baseUrl.replace(/\/+$/,""),u=t.timeoutMs??G,h=Math.max(1,t.maxResults??F),g=t.maxChars??N,d=t.pageChars??X,b={...H,...t.pages},O=y(t);async function p(n,s){const e=new URL(`${i}/search`);e.searchParams.set("q",n),e.searchParams.set("format","json"),s&&e.searchParams.set("time_range",s),t.language&&e.searchParams.set("language",t.language),t.engines?.length&&e.searchParams.set("engines",t.engines.join(","));const a=await O(()=>r(e,{signal:AbortSignal.timeout(u),headers:{accept:"application/json"}}));if(!a.ok){const o=a.status===403?" SearXNG refuses the json format unless settings.yml lists it under search.formats and the limiter is off.":"";throw new Error(`SearXNG returned ${a.status}.${o}`)}const c=await a.json();return{hits:(c.results??[]).flatMap(o=>{const l=W(o);return l&&R(l,t.domains)?[l]:[]}),suggestions:c.suggestions??[]}}async function P(n,s){const e=n.suggestions.slice(0,Q);return[n,...await Promise.all(e.map(a=>p(a,s)))]}async function w(n){const s=AbortSignal.timeout(u);let e=x(n,U),a=await r(e,{signal:s,redirect:"manual"});for(let c=0;c<Y&&v(a);c++){const o=a.headers.get("location");if(!o)break;e=x(new URL(o,a.url||e).toString(),U),a=await r(e,{signal:s,redirect:"manual"})}return a}async function M(n){try{const s=await w(n.url);if(!s.ok)return n.snippet;const e=T((await s.text()).slice(0,L));return e?e.slice(0,d):n.snippet}catch{return n.snippet}}async function D(n){if(!R({url:n,snippet:""},t.domains))return null;try{const s=await w(n);return s.ok&&T((await s.text()).slice(0,L)).slice(0,d)||null}catch{return null}}const C=(n,s)=>({answer:s.slice(0,g),results:[{url:n}],model:f,truncated:s.length>g,usage:{...A,searchQueries:0}});return Object.assign(async({query:n,depth:s,recency:e})=>{const a=n.match(I)?.[0],c=a?await D(a):null;if(a&&c)return C(a,c);const o=await p(n,e),l=s==="deep"?await P(o,e):[o],_=z(l),m=_.slice(0,h),E=m.slice(0,b[s]),k=await Promise.all(E.map(M)),S=E.map(($,j)=>K($,k[j])).join(`
+
+`);return{answer:S.slice(0,g),results:m.map(q),model:f,truncated:S.length>g||_.length>m.length,usage:{...A,searchQueries:l.length}}},{source:f,...t.domains?.length?{domains:[...t.domains]}:{}})}export{tt as searxng};

package/dist/search/searxng/text.d.ts

@@ -0,0 +1,2 @@
+/** A page's readable text: the main content where it is marked, with menus, scripts and markup gone. */
+export declare function textOf(html: string): string;

package/dist/search/searxng/text.js

@@ -0,0 +1,3 @@
+const r=/<(nav|header|footer|aside|form)\b[\s\S]*?<\/\1>/gi,c=/<(main|article)\b[^>]*>([\s\S]*?)<\/\1>/i;function t(e){return e.match(c)?.[2]??e}function a(e){return t(e).replace(/<!--[\s\S]*?-->/g," ").replace(/<script[\s\S]*?<\/script>/gi," ").replace(/<style[\s\S]*?<\/style>/gi," ").replace(/<noscript[\s\S]*?<\/noscript>/gi," ").replace(r," ").replace(/<\/(p|div|li|h[1-6]|tr|br|section|article)>/gi,`
+`).replace(/<[^>]+>/g," ").replace(/&nbsp;/g," ").replace(/&amp;/g,"&").replace(/&lt;/g,"<").replace(/&gt;/g,">").replace(/&quot;/g,'"').replace(/&#39;|&apos;/g,"'").replace(/[ \t]+/g," ").replace(/\s*\n\s*/g,`
+`).trim()}export{a as textOf};

package/dist/search/sonar/index.d.ts

@@ -0,0 +1,2 @@
+export { readReply } from "./reply.js";
+export { type SonarOptions, sonar } from "./sonar.js";

package/dist/search/sonar/index.js

@@ -0,0 +1 @@
+import{readReply as e}from"./reply.js";import{sonar as a}from"./sonar.js";export{e as readReply,a as sonar};

package/dist/search/sonar/sonar.d.ts

@@ -0,0 +1,13 @@
+import { type Searcher, type SearcherOptions } from "../search.js";
+export interface SonarOptions extends SearcherOptions {
+    /** Perplexity key. Required, and read from here rather than the environment. */
+    apiKey: string;
+}
+/**
+ * The live web through Perplexity's Sonar models, one model per depth.
+ *
+ * Perplexity searches, reads and writes the answer itself, with citation
+ * marks, and bills citation and reasoning tokens on top of the usual two.
+ * The timeout defaults to a minute, or five on a deep search.
+ */
+export declare function sonar(opts: SonarOptions): Searcher;

package/dist/search/sonar/sonar.js

@@ -0,0 +1 @@
+import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as d,DEFAULT_MAX_RESULTS as h}from"../search.js";import{readReply as _}from"./reply.js";const E={quick:"sonar",pro:"sonar-pro",deep:"sonar-deep-research"},f="sonar",p="https://api.perplexity.ai/chat/completions",u=6e4,T=3e5,y=500;function O(e){if(!e.apiKey?.trim())throw new Error("sonar needs a Perplexity apiKey; it will not read one from the process.");const a=e.fetch??globalThis.fetch.bind(globalThis),i=m(e);return Object.assign(async({query:s,depth:o,recency:n})=>{const r=E[o],c=e.timeoutMs??(o==="deep"?T:u),t=await i(()=>a(p,{method:"POST",signal:AbortSignal.timeout(c),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({model:r,messages:[{role:"user",content:s}],...n?{search_recency_filter:n}:{},...e.domains?.length?{search_domain_filter:e.domains}:{}})}));if(!t.ok){const l=(await t.text()).slice(0,y);throw new Error(`Perplexity returned ${t.status} for ${r}: ${l}`)}return _(await t.json(),r,e.maxChars??d,e.maxResults??h)},{source:f,...e.domains?.length?{domains:[...e.domains]}:{}})}export{O as sonar};

package/dist/search/tavily/index.d.ts

@@ -0,0 +1,4 @@
+export type { TavilyReply } from "./reply.js";
+export { readReply } from "./reply.js";
+export type { TavilyOptions } from "./tavily.js";
+export { tavily } from "./tavily.js";

package/dist/search/tavily/index.js

@@ -0,0 +1 @@
+import{readReply as o}from"./reply.js";import{tavily as t}from"./tavily.js";export{o as readReply,t as tavily};

package/dist/search/tavily/reply.d.ts

@@ -0,0 +1,22 @@
+import { type Searched } from "../search.js";
+interface Hit {
+    url?: string;
+    title?: string;
+    content?: string;
+    raw_content?: string | null;
+    published_date?: string;
+}
+export interface TavilyReply {
+    answer?: string | null;
+    results?: Hit[];
+    auto_parameters?: Record<string, unknown>;
+}
+/**
+ * Tavily's reply as a `Searched`.
+ *
+ * Its own `answer` leads where it gave one, because it is a summary written
+ * across every result; the per-result text follows so a later stage can quote
+ * a source rather than the summary of it.
+ */
+export declare function readReply(raw: TavilyReply, model: string, maxChars: number, maxResults: number): Searched;
+export {};

package/dist/search/tavily/reply.js

@@ -0,0 +1,5 @@
+import{NO_TOKENS as c}from"../search.js";function i(e){return e.url?{url:e.url,...e.title?{title:e.title}:{},...e.published_date?{date:e.published_date}:{}}:null}function a(e){const t=(e.raw_content??e.content??"").trim();return`## ${e.title??e.url}
+${e.url}
+${t}`}function p(e,t,r,s){const u=(e.results??[]).filter(l=>!!l.url),n=u.slice(0,s),o=[e.answer?.trim(),...n.map(a)].filter(Boolean).join(`
+
+`);return{answer:o.slice(0,r),results:n.map(i).filter(l=>l!==null),model:t,truncated:o.length>r||u.length>n.length,usage:{...c}}}export{p as readReply};

package/dist/search/tavily/tavily.d.ts

@@ -0,0 +1,14 @@
+import { type Searcher, type SearcherOptions } from "../search.js";
+export interface TavilyOptions extends SearcherOptions {
+    /** Tavily key. Required, and read from here rather than the environment. */
+    apiKey: string;
+}
+/**
+ * The live web through Tavily, which searches and extracts in one call.
+ *
+ * Built for retrieval rather than for a person reading a results page: it
+ * returns the text of each page alongside its url, so a finding keeps both
+ * what was said and where it was said. Depth buys a wider search and more
+ * pages read, not a different model.
+ */
+export declare function tavily(opts: TavilyOptions): Searcher;

package/dist/search/tavily/tavily.js

@@ -0,0 +1 @@
+import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as u,DEFAULT_MAX_RESULTS as n}from"../search.js";import{readReply as _}from"./reply.js";const y="https://api.tavily.com/search",i="tavily-search",g=6e4,p=500,T={quick:{search_depth:"basic",pages:3},pro:{search_depth:"advanced",pages:5},deep:{search_depth:"advanced",pages:10}},E={day:1,week:7,month:30,year:365};function S(e){if(!e.apiKey?.trim())throw new Error("tavily needs an apiKey; it will not read one from the process.");const r=e.fetch??globalThis.fetch.bind(globalThis),s=m(e);return Object.assign(async({query:o,depth:c,recency:t})=>{const{search_depth:d,pages:h}=T[c],a=await s(()=>r(y,{method:"POST",signal:AbortSignal.timeout(e.timeoutMs??g),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({query:o,search_depth:d,include_answer:!0,include_raw_content:!0,max_results:Math.min(h,e.maxResults??n),...t?{days:E[t]}:{},...e.domains?.length?{include_domains:e.domains}:{}})}));if(!a.ok){const l=(await a.text()).slice(0,p);throw new Error(`Tavily returned ${a.status}: ${l}`)}return _(await a.json(),i,e.maxChars??u,e.maxResults??n)},{source:i,...e.domains?.length?{domains:[...e.domains]}:{}})}export{S as tavily};

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { type Replay, replaying, type Unrecorded } from "./replay.js";
+export { type MemorySeed, type MemoryStore, memoryStore, type ObservedMoment, type StoredMemory, } from "./store.js";

package/dist/testing/index.js

@@ -0,0 +1 @@
+import{replaying as e}from"./replay.js";import{memoryStore as p}from"./store.js";export{p as memoryStore,e as replaying};

package/dist/testing/replay.d.ts

@@ -0,0 +1,55 @@
+import type { ToolResult } from "../types/index.js";
+/** A call the recording had no answer for. */
+export interface Unrecorded {
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface ReplayOptions {
+    /**
+     * Tools that must still run for real, by name.
+     *
+     * A replay stands in for the world, not for the agent's own bookkeeping.
+     * `finish` carries the answer — the thing actually under test — so replaying
+     * it would mean a reworded prompt could only ever produce the old wording,
+     * and the run stalls the first time it says anything differently. `think` and
+     * `notes` are the same: they change nothing outside the process, so there is
+     * nothing to stand in for.
+     *
+     * Their recordings are dropped rather than kept unused, because a result
+     * nothing was ever going to ask for is not a step the new run skipped.
+     */
+    live?: readonly string[];
+    /** What runs the tools named in `live`. Required with it, and refused without. */
+    on?: {
+        invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    };
+}
+export interface Replay {
+    /** Hands back what the recording holds, or a failed result saying it does not. */
+    invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /** Calls this run made that the recording could not answer, in order. */
+    unrecorded: Unrecorded[];
+    /** Recorded results this run never asked for. */
+    unused(): ToolResult[];
+}
+/**
+ * The tool results a run already produced, handed back instead of running anything.
+ *
+ * What a recorded trace is for: re-run the reasoning against a new prompt or a
+ * new model while the tools answer exactly as they did, so the only thing that
+ * changed is the thing under test. Nothing reaches a database, an API or a
+ * customer, and the comparison is not confounded by the world having moved.
+ *
+ * Matched on the arguments as well as the name, which is the whole value and
+ * also the part that looks like a limitation. A replay that answered
+ * `track("ORD-9")` with the recording of `track("ORD-1")` would be a green run
+ * proving nothing. A call the recording cannot answer is the finding: the new
+ * prompt asked something the old one never did, and the recording is not
+ * evidence about it either way.
+ *
+ * It offers no `effectOf`, and that is not an omission. Nothing runs during a
+ * replay, so nothing is destructive — a rail that gates on effect has nothing
+ * to guard, and giving it the original effects would have it blocking calls
+ * that are already only paper.
+ */
+export declare function replaying(recorded: readonly ToolResult[], opts?: ReplayOptions): Replay;

package/dist/testing/replay.js

@@ -0,0 +1 @@
+const u=(i,n,e)=>i.name===n&&JSON.stringify(i.args)===JSON.stringify(e),f=(i,n,e)=>({name:i,args:n,status:"failed",output:"",error:`Nothing recorded for ${i}(${JSON.stringify(n)}). The recording holds: ${[...new Set(e.map(o=>o.name))].join(", ")||"nothing"}`,latencyMs:0});function l(i,n={}){const e=new Set(n.live??[]);if(e.size>0&&!n.on)throw new Error(`replaying names ${[...e].join(", ")} as live, but nothing to run them on.`);const o=i.filter(t=>!e.has(t.name)),s=new Set,c=[];return{unrecorded:c,unused:()=>o.filter((t,r)=>!s.has(r)),invoke:async(t,r)=>{if(e.has(t))return n.on.invoke(t,r);const a=o.findIndex((d,h)=>!s.has(h)&&u(d,t,r));return a===-1?(c.push({name:t,args:r}),f(t,r,o)):(s.add(a),{...o[a]})}}}export{l as replaying};

package/dist/testing/store.d.ts

@@ -0,0 +1,35 @@
+import type { MemoryClient, MemorySource } from "../memories/client.js";
+export interface StoredMemory {
+    id: string;
+    context: string;
+    kind: string;
+    source: string;
+    text: string;
+    details: Record<string, unknown>;
+    extends: string[];
+    related_to: string[];
+    reinforces: string[];
+    contradicts: string[];
+}
+export interface ObservedMoment {
+    source: string;
+    payload: string | Record<string, unknown>;
+    stream?: string;
+}
+export interface MemorySeed {
+    context: string;
+    text: string;
+    details?: Record<string, unknown>;
+    kind?: string;
+    source?: MemorySource;
+    extends?: string[];
+    related_to?: string[];
+    reinforces?: string[];
+    contradicts?: string[];
+}
+export interface MemoryStore extends MemoryClient {
+    memories: StoredMemory[];
+    observed: ObservedMoment[];
+    remember(seed: MemorySeed): StoredMemory;
+}
+export declare function memoryStore(seeds?: MemorySeed[]): MemoryStore;