@telemai/sdk 0.2.0 → 0.2.1

package/README.md

@@ -42,7 +42,7 @@ See [Authentication](https://docs.telem.ai/authentication/) for the full rules.
 
 ```ts
 
-const telem = new Telem()          // environment, then ~/.telem/credentials.json
+const telem = new Telem          // environment, then ~/.telem/credentials.json
 const telem = new Telem("tlm_...") // just a key
 const telem = new Telem({
   apiKey: "tlm_...",
@@ -176,7 +176,7 @@ Do not expect a shorter list. The options are on the
 List the providers the deployment can run:
 
 ```ts
-for (const provider of await telem.providers()) {
+for (const provider of await telem.providers) {
   console.log(provider.name, provider.activeByDefault, provider.tiers)
 }
 ```
@@ -187,7 +187,7 @@ Every search belongs to a session. The response carries its id as `sessionId`. R
 your sessions back to see what an agent searched for. Both methods require an API key:
 
 ```ts
-for (const session of await telem.sessions.list()) {
+for (const session of await telem.sessions.list) {
   console.log(session.id, session.interactionCount, session.latestInteractionAt)
 }
 
@@ -210,7 +210,7 @@ import { generateText } from "ai"
 import Telem from "@telemai/sdk"
 import { createTelemVercelTools } from "@telemai/sdk/vercel"
 
-const telem = new Telem()
+const telem = new Telem
 const tools = createTelemVercelTools({ telem, harness: "my-app" })
 
 const result = await generateText({ model, tools, prompt: "Is the Nintendo Museum open over New Year?" })
@@ -222,7 +222,7 @@ then appear in the console under the tool call that started it. `ai` version 5
 or later is an optional peer dependency, used by this subpath only. The full
 guide, subagents, your own tools, and the options, is on the
 [Vercel AI SDK page](https://docs.telem.ai/integrations/vercel-ai/). The runnable example is `examples/vercel-ai-agents.mjs`
-in the SDK source, first in the [examples list](https://github.com/TelemAI/TelemSDK/tree/main/js-sdk/examples).
+in the SDK source, first in the [examples list](https://github.com/TelemAI/telem-js-sdk/tree/main/examples).
 
 ## Query lineage
 
@@ -251,8 +251,8 @@ Node SDK, where the completion id is the turn and each tool call has its own id:
 
 ```ts
 
-const telem = new Telem()
-const openai = new OpenAI()
+const telem = new Telem
+const openai = new OpenAI
 const messages = [{ role: "user" as const, content: "Is the Nintendo Museum open over New Year?" }]
 const tools = [
   {
@@ -269,7 +269,7 @@ const tools = [
   },
 ]
 
-const conversationId = crypto.randomUUID()     // once, when the conversation starts
+const conversationId = crypto.randomUUID     // once, when the conversation starts
 const windowId = await windowAnchor(messages)  // once, from the first message
 
 const completion = await openai.chat.completions.create({ model: "gpt-4o", messages, tools })

package/dist/index.cjs

@@ -59,7 +59,7 @@ var TimeoutError = class extends TelemError {
 };
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.2.1";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -74,6 +74,9 @@ function csvEnv(raw) {
   const items = raw.split(",").map(trimBlank).filter((item) => item !== "");
   return items.length ? items : void 0;
 }
+function intEnv(raw) {
+  return raw !== void 0 && /^\s*[+-]?\d+\s*$/.test(raw) ? Number(raw) : void 0;
+}
 function readCredentials(env) {
   try {
     const proc = globalThis.process;
@@ -150,7 +153,10 @@ function resolveConfig(options) {
       fields: opts.fields ?? csvEnv(env.TELEM_FIELDS),
       providersInclude: opts.providersInclude ?? csvEnv(env.TELEM_PROVIDERS_INCLUDE),
       providersExclude: opts.providersExclude ?? csvEnv(env.TELEM_PROVIDERS_EXCLUDE),
-      includeFullContent: opts.includeFullContent ?? (env.TELEM_FULL_CONTENT === "1" || void 0)
+      includeFullContent: opts.includeFullContent ?? (env.TELEM_FULL_CONTENT === "1" || void 0),
+      autoRouting: opts.autoRouting ?? (trimBlank(env.TELEM_AUTO_ROUTING ?? "") || void 0),
+      maxRoutingProviders: opts.maxRoutingProviders ?? intEnv(env.TELEM_MAX_ROUTING_PROVIDERS),
+      topic: opts.topic ?? (trimBlank(env.TELEM_TOPIC ?? "") || void 0)
     }
   };
 }
@@ -587,6 +593,12 @@ function searchBlock(defaults, options) {
   if (options.includeRaw !== void 0) block.include_raw = options.includeRaw;
   if (options.rerank !== void 0) block.rerank = options.rerank;
   if (includeFullContent !== void 0) block.include_full_content = includeFullContent;
+  const autoRouting = options.autoRouting ?? defaults.autoRouting;
+  if (autoRouting !== void 0) block.auto_routing = autoRouting;
+  const maxRoutingProviders = options.maxRoutingProviders ?? defaults.maxRoutingProviders;
+  if (maxRoutingProviders !== void 0) block.max_routing_providers = maxRoutingProviders;
+  const topic = options.topic ?? defaults.topic;
+  if (topic !== void 0) block.topic = topic;
   return block;
 }
 function userInput(query) {
@@ -755,7 +767,7 @@ var Telem = class {
   timeoutMs;
   /** Resolved retry budget (attempts after the first). */
   maxRetries;
-  /** The session read surface: `list()` and `results(id)`. */
+  /** The session read surface: `list` and `results(id)`. */
   sessions;
   #config;
   /**

package/dist/index.d.cts

@@ -61,6 +61,9 @@ type SearchOptions = {
     numResults?: number;
     includeRaw?: boolean;
     includeFullContent?: boolean;
+    autoRouting?: string;
+    maxRoutingProviders?: number;
+    topic?: string;
     /** Opt this request into the server's rerank stage. It is the only path where
      *  `context`, the reasoning on the last assistant entry of the lineage history
      *  (that entry only), and `goal` change result ORDER (in that precedence) —
@@ -80,7 +83,7 @@ type SearchOptions = {
 };
 /** The subset of search options that may also be set as a client default.
  *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
-type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent">;
+type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent" | "autoRouting" | "maxRoutingProviders" | "topic">;
 type FetchOptions = {
     providers?: string[];
     inlineContent?: boolean;
@@ -187,7 +190,7 @@ type ProviderInfo = {
     normalized: boolean;
     tiers: string[];
 };
-/** One session as `sessions.list()` reports it. */
+/** One session as `sessions.list` reports it. */
 type SessionSummary = {
     id: string;
     createdAt: string | null;
@@ -264,7 +267,7 @@ declare function snapshotNodeKey(harness: string, conversationId: string, messag
 /** Stable anchor id for content a host did not assign an id to.
  *  Length-prefixed like every other key component, so concatenation stays injective. */
 declare function contentAnchor(...parts: string[]): Promise<string>;
-/** `tool_marker` from telem/integrations/_trajectory_v5.py: one tool call as the
+/** `tool_marker` from the Python SDK's _trajectory_v5.py: one tool call as the
  *  compact acting-trace marker every harness renders into history. The exporter
  *  cuts goals on `[tool telem_search:`, so the text is a contract. Compact JSON,
  *  key order kept, matches Python's `separators=(",", ":")`; an unserializable
@@ -330,7 +333,7 @@ declare function withTrajectory(options: FetchOptions, envelope: TrajectoryEnvel
  *
  * @example
  * ```ts
- * const telem = new Telem()                    // env / credentials-file resolution
+ * const telem = new Telem                    // env / credentials-file resolution
  * const telem = new Telem("tlm_...")           // bare API-key shorthand
  * const telem = new Telem({ apiKey, baseUrl, tier: "max" })
  * ```
@@ -345,7 +348,7 @@ declare class Telem {
     readonly timeoutMs: number;
     /** Resolved retry budget (attempts after the first). */
     readonly maxRetries: number;
-    /** The session read surface: `list()` and `results(id)`. */
+    /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset

package/dist/index.d.ts

@@ -61,6 +61,9 @@ type SearchOptions = {
     numResults?: number;
     includeRaw?: boolean;
     includeFullContent?: boolean;
+    autoRouting?: string;
+    maxRoutingProviders?: number;
+    topic?: string;
     /** Opt this request into the server's rerank stage. It is the only path where
      *  `context`, the reasoning on the last assistant entry of the lineage history
      *  (that entry only), and `goal` change result ORDER (in that precedence) —
@@ -80,7 +83,7 @@ type SearchOptions = {
 };
 /** The subset of search options that may also be set as a client default.
  *  `numResults`/`includeRaw`/`rerank`/`providerOverrides` are per-call intent only. */
-type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent">;
+type SearchDefaults = Pick<SearchOptions, "tier" | "fields" | "providersInclude" | "providersExclude" | "includeFullContent" | "autoRouting" | "maxRoutingProviders" | "topic">;
 type FetchOptions = {
     providers?: string[];
     inlineContent?: boolean;
@@ -187,7 +190,7 @@ type ProviderInfo = {
     normalized: boolean;
     tiers: string[];
 };
-/** One session as `sessions.list()` reports it. */
+/** One session as `sessions.list` reports it. */
 type SessionSummary = {
     id: string;
     createdAt: string | null;
@@ -264,7 +267,7 @@ declare function snapshotNodeKey(harness: string, conversationId: string, messag
 /** Stable anchor id for content a host did not assign an id to.
  *  Length-prefixed like every other key component, so concatenation stays injective. */
 declare function contentAnchor(...parts: string[]): Promise<string>;
-/** `tool_marker` from telem/integrations/_trajectory_v5.py: one tool call as the
+/** `tool_marker` from the Python SDK's _trajectory_v5.py: one tool call as the
  *  compact acting-trace marker every harness renders into history. The exporter
  *  cuts goals on `[tool telem_search:`, so the text is a contract. Compact JSON,
  *  key order kept, matches Python's `separators=(",", ":")`; an unserializable
@@ -330,7 +333,7 @@ declare function withTrajectory(options: FetchOptions, envelope: TrajectoryEnvel
  *
  * @example
  * ```ts
- * const telem = new Telem()                    // env / credentials-file resolution
+ * const telem = new Telem                    // env / credentials-file resolution
  * const telem = new Telem("tlm_...")           // bare API-key shorthand
  * const telem = new Telem({ apiKey, baseUrl, tier: "max" })
  * ```
@@ -345,7 +348,7 @@ declare class Telem {
     readonly timeoutMs: number;
     /** Resolved retry budget (attempts after the first). */
     readonly maxRetries: number;
-    /** The session read surface: `list()` and `results(id)`. */
+    /** The session read surface: `list` and `results(id)`. */
     readonly sessions: SessionsResource;
     /**
      * @param options - An API key string, or an options object. Anything left unset

package/dist/index.js

@@ -22,7 +22,7 @@ import {
 } from "./chunk-RYY4S5LP.js";
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.2.1";
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://router.telem.ai";
@@ -37,6 +37,9 @@ function csvEnv(raw) {
   const items = raw.split(",").map(trimBlank).filter((item) => item !== "");
   return items.length ? items : void 0;
 }
+function intEnv(raw) {
+  return raw !== void 0 && /^\s*[+-]?\d+\s*$/.test(raw) ? Number(raw) : void 0;
+}
 function readCredentials(env) {
   try {
     const proc = globalThis.process;
@@ -113,7 +116,10 @@ function resolveConfig(options) {
       fields: opts.fields ?? csvEnv(env.TELEM_FIELDS),
       providersInclude: opts.providersInclude ?? csvEnv(env.TELEM_PROVIDERS_INCLUDE),
       providersExclude: opts.providersExclude ?? csvEnv(env.TELEM_PROVIDERS_EXCLUDE),
-      includeFullContent: opts.includeFullContent ?? (env.TELEM_FULL_CONTENT === "1" || void 0)
+      includeFullContent: opts.includeFullContent ?? (env.TELEM_FULL_CONTENT === "1" || void 0),
+      autoRouting: opts.autoRouting ?? (trimBlank(env.TELEM_AUTO_ROUTING ?? "") || void 0),
+      maxRoutingProviders: opts.maxRoutingProviders ?? intEnv(env.TELEM_MAX_ROUTING_PROVIDERS),
+      topic: opts.topic ?? (trimBlank(env.TELEM_TOPIC ?? "") || void 0)
     }
   };
 }
@@ -222,6 +228,12 @@ function searchBlock(defaults, options) {
   if (options.includeRaw !== void 0) block.include_raw = options.includeRaw;
   if (options.rerank !== void 0) block.rerank = options.rerank;
   if (includeFullContent !== void 0) block.include_full_content = includeFullContent;
+  const autoRouting = options.autoRouting ?? defaults.autoRouting;
+  if (autoRouting !== void 0) block.auto_routing = autoRouting;
+  const maxRoutingProviders = options.maxRoutingProviders ?? defaults.maxRoutingProviders;
+  if (maxRoutingProviders !== void 0) block.max_routing_providers = maxRoutingProviders;
+  const topic = options.topic ?? defaults.topic;
+  if (topic !== void 0) block.topic = topic;
   return block;
 }
 function userInput(query) {
@@ -390,7 +402,7 @@ var Telem = class {
   timeoutMs;
   /** Resolved retry budget (attempts after the first). */
   maxRetries;
-  /** The session read surface: `list()` and `results(id)`. */
+  /** The session read surface: `list` and `results(id)`. */
   sessions;
   #config;
   /**

package/dist/vercel/index.d.cts

@@ -121,7 +121,7 @@ type TelemVercelAgentOptions = {
      *  several HTTP requests must pass a stable id (the chat id), or every request
      *  becomes its own session. */
     conversationId?: string;
-    /** The root-first chain this agent hangs under; `child()` fills it. */
+    /** The root-first chain this agent hangs under; `child` fills it. */
     ancestors?: readonly TrajectorySnapshot[];
     /** `ancestors` (phase 1, the default), `history` (both phases) or `off`.
      *  Unset reads `TELEM_INCREMENTAL` per call. */
@@ -133,7 +133,7 @@ type TelemVercelAgentOptions = {
      *  without replacing a tool. A throw or a rejection here is swallowed; it
      *  never fails the call. */
     onResponse?: (event: TelemVercelCallEvent) => void | Promise<void>;
-    /** Advanced: the ledgers to share. `child()` passes its parent's, so a child
+    /** Advanced: the ledgers to share. `child` passes its parent's, so a child
      *  never re-sends what the parent already proved delivered. */
     incrementalState?: IncrementalState;
 };
@@ -238,11 +238,7 @@ type TelemVercelTools<T extends Record<string, TelemVercelToolLike>> = T & Telem
  *
  * @example
  * ```ts
- * const delegate = tool({
- *   description: "Research one question.",
- *   inputSchema: z.object({ brief: z.string() }),
- *   execute: async ({ brief }): Promise<string> => (await generateText({ model, tools, prompt: brief })).text,
- * })
+ * // `delegate` is a tool of yours whose execute starts another generateText with the same `tools`.
  * const tools = createTelemVercelTools({ telem, harness: "my-app", tools: { delegate } })
  * await generateText({ model, tools, prompt })
  * ```

package/dist/vercel/index.d.ts

@@ -121,7 +121,7 @@ type TelemVercelAgentOptions = {
      *  several HTTP requests must pass a stable id (the chat id), or every request
      *  becomes its own session. */
     conversationId?: string;
-    /** The root-first chain this agent hangs under; `child()` fills it. */
+    /** The root-first chain this agent hangs under; `child` fills it. */
     ancestors?: readonly TrajectorySnapshot[];
     /** `ancestors` (phase 1, the default), `history` (both phases) or `off`.
      *  Unset reads `TELEM_INCREMENTAL` per call. */
@@ -133,7 +133,7 @@ type TelemVercelAgentOptions = {
      *  without replacing a tool. A throw or a rejection here is swallowed; it
      *  never fails the call. */
     onResponse?: (event: TelemVercelCallEvent) => void | Promise<void>;
-    /** Advanced: the ledgers to share. `child()` passes its parent's, so a child
+    /** Advanced: the ledgers to share. `child` passes its parent's, so a child
      *  never re-sends what the parent already proved delivered. */
     incrementalState?: IncrementalState;
 };
@@ -238,11 +238,7 @@ type TelemVercelTools<T extends Record<string, TelemVercelToolLike>> = T & Telem
  *
  * @example
  * ```ts
- * const delegate = tool({
- *   description: "Research one question.",
- *   inputSchema: z.object({ brief: z.string() }),
- *   execute: async ({ brief }): Promise<string> => (await generateText({ model, tools, prompt: brief })).text,
- * })
+ * // `delegate` is a tool of yours whose execute starts another generateText with the same `tools`.
  * const tools = createTelemVercelTools({ telem, harness: "my-app", tools: { delegate } })
  * await generateText({ model, tools, prompt })
  * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemai/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Telem web search and fetch for JavaScript and TypeScript.",
   "type": "module",
   "license": "Apache-2.0",
@@ -42,14 +42,10 @@
     "node": ">=20.16"
   },
   "scripts": {
-    "pretest": "npm run build",
-    "test": "node --test 'test/**/*.test.ts'",
-    "typecheck": "tsc --noEmit",
-    "gen-version": "node scripts/gen-version.mjs",
-    "prebuild": "node scripts/gen-version.mjs",
     "build": "tsup",
+    "typecheck": "tsc --noEmit",
     "prepack": "npm run build",
-    "smoke:vercel": "node scripts/vercel-live.mjs"
+    "test": "node scripts/smoke.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
@@ -71,5 +67,13 @@
         "./dist/vercel/index.d.ts"
       ]
     }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TelemAI/telem-js-sdk.git"
+  },
+  "homepage": "https://docs.telem.ai/sdks/javascript/",
+  "bugs": {
+    "url": "https://github.com/TelemAI/telem-js-sdk/issues"
   }
 }