@takoviz/ai-sdk 2.0.1 → 4.0.0

package/README.md

@@ -10,7 +10,7 @@ npm install @takoviz/ai-sdk ai
 
 ## Setup
 
-Get an API key from the [Tako developer console](https://developer.tako.com/console/api-keys) and set it as an environment variable:
+Get an API key from the [Tako developer console](https://tako.com/console/api-keys) and set it as an environment variable:
 
 ```bash
 export TAKO_API_KEY=your_api_key_here
@@ -32,7 +32,7 @@ import { openai } from '@ai-sdk/openai';
 import { generateText, isStepCount } from 'ai';
 
 const { text } = await generateText({
-  model: openai('gpt-4o-mini'),
+  model: openai('gpt-5.4-mini'),
   prompt: 'Did AMD or Nvidia grow headcount faster over the last decade?',
   tools: { tako_answer: takoAnswer() },
   stopWhen: isStepCount(5),
@@ -55,38 +55,68 @@ const tools = {
 
 ## Configuration
 
-`takoSearch` and `takoAnswer` take the same config:
+A tool's config is the API request body for its endpoint, minus the field the model supplies, plus `apiKey` and `baseUrl`. Keys are the API's own names, exactly as [`tako-sdk`](https://www.npmjs.com/package/tako-sdk) declares them, so every option in the [API reference](https://docs.tako.com) works here without a release of this package.
+
+| Tool | Config type | Is the request body of | Minus |
+| --- | --- | --- | --- |
+| `takoSearch` | `TakoRetrievalConfig` | `POST /api/v3/search` | `query` |
+| `takoAnswer` | `TakoAnswerConfig` | `POST /api/v1/answer` | `query` |
+| `takoContents` | `TakoContentsConfig` | `POST /api/v1/contents` | `url` |
+
+Every field is optional. Omit one and the API's default applies; this package restates none of them. The model supplies only `{ query }` or `{ url }` per call.
+
+Three `sources.data` keys aren't exposed, because you can't use them correctly from here: `mode` (the API documents it as having no effect on Tako cards), and `node_ids` with `strict` (they take graph ids from endpoints this package doesn't wrap). Call the API through `tako-sdk` directly if you need them.
+
+### Examples
+
+Deep search over Tako's data only, ten cards, with the rows inlined as typed columns:
 
 ```typescript
 takoSearch({
-  apiKey: 'your_api_key',      // optional; defaults to TAKO_API_KEY
-  baseUrl: 'https://tako.com', // optional; override for staging
-  effort: 'fast',              // 'fast' (default) | 'instant' | 'deep'
-  sources: {                   // a source is searched iff its key is present; omit to search both
-    tako: { count: 5, includeContents: false, deferDataRetrieval: false },
-    web: { count: 5, includeContents: false },
-  },
-  countryCode: 'US',           // default 'US'
-  locale: 'en-US',             // default 'en-US'
-  timezone: 'America/New_York',// optional IANA timezone
-  outputSettings: {
-    imageDarkMode: false,
-    forceRefresh: false,       // instant mode only
-  },
+  effort: 'deep',
+  sources: { data: { count: 10, include_contents: true, content_format: 'json_compact' } },
+});
+```
+
+News from the last week. Build dates with the ISO-string constructor: `new Date('2026-08-19')` is UTC midnight and serializes as that day everywhere; `new Date(2026, 7, 19)` is local midnight and serializes as the day before in any UTC+ timezone.
+
+Check that your date parsed before you pass it. `new Date()` returns an `Invalid Date` for a string it can't read, and that fails during serialization, so the tool call rejects with `Failed to search with Tako: Invalid time value` — a message that names neither the field nor the value, and reaches the model rather than you. The request never leaves the process.
+
+```typescript
+takoSearch({
+  sources: { web: { category: 'news', published_after: new Date('2026-08-19'), count: 5 } },
 });
 ```
 
-`takoContents` takes:
+An answer shaped by a JSON Schema. Tako fills it from the same evidence as `answer` and returns it as `structured_output`; a nullable type is how you let it say "no evidence" instead of inventing a zero.
 
 ```typescript
-takoContents({
-  apiKey: 'your_api_key',
-  baseUrl: 'https://tako.com',
-  mode: 'url',                 // 'url' (default) → presigned link; 'inline' → content in the response
+takoAnswer({
+  output_schema: {
+    type: 'object',
+    properties: {
+      revenue_usd: { type: ['number', 'null'], description: 'Latest annual revenue in USD' },
+      fiscal_year: { type: ['integer', 'null'] },
+    },
+    required: ['revenue_usd', 'fiscal_year'],
+    additionalProperties: false,
+  },
 });
 ```
 
-The LLM supplies only the dynamic input: `{ query }` for `takoSearch`/`takoAnswer`, and `{ url }` (a card's `webpage_url` or a web result's `url`) for `takoContents`.
+A `TakoRetrievalConfig` is also a valid `TakoAnswerConfig`, so one object can build both tools.
+
+### Contents delivery
+
+Two `takoContents` options also change the description the model reads, so pick them deliberately:
+
+- `mode: 'url'` returns a short-lived presigned download link. The description tells the model to surface the link, not parse it.
+- `mode: 'inline'` returns the rows or page text in the response. The description tells the model to read and compute over them.
+- `quote_only: true` returns the export price and no content, for free. The description tells the model to report the price and not call again expecting rows.
+
+Leave `mode` unset and the API chooses — `'url'` today. This package sends no default and names none in the description; the model is told to read the response instead. Set `mode` to pin the delivery and tell the model which one to expect.
+
+`max_rows` fails quietly: a value over the 2,000-row ceiling is clamped, not rejected, and every row returned is billed. Read `total_rows` and `truncated` on the item to see what you got.
 
 ## Responses
 
@@ -96,12 +126,40 @@ The LLM supplies only the dynamic input: `{ query }` for `takoSearch`/`takoAnswe
 {
   cards: TakoCard[];          // Tako knowledge cards (title, description, image_url, webpage_url, sources, ...)
   web_results: TakoWebResult[];
-  contents_total_cost: number;
   request_id: string;
+  usage?: TakoUsage | null;   // { total_cost_usd, compute?, data? } — see note
 }
 ```
 
-`takoAnswer` additionally includes `answer: string` (with `cards[0]` as the lead card). `takoContents` resolves to `{ contents: TakoContentItem[]; request_id: string }`, where each item has a `format` (`'csv'` | `'text'`), a `cost`, and either a presigned `url`/`expires_at` (url mode) or inline `data`/`total_rows`/`truncated` (inline mode).
+> **Cost reporting.** `usage` is what the API spec defines for per-request cost, but as of 2026-08 it is not populated on any endpoint. For pricing today, read the per-item `content.cost` and `content.export_pricing` on each card, which are populated.
+
+`takoAnswer` additionally includes `answer: string` (with `cards[0]` as the lead card). `takoContents` resolves to `{ contents: TakoContentItem[]; request_id: string; usage? }`.
+
+The API guarantees only `request_id` — the contract permits omitting the collections — so the tools normalize: `cards`, `web_results` and `contents` are **always arrays**. No `?.` needed.
+
+### Reading a card
+
+Two fields are worth knowing about:
+
+- **`exportable`** — whether `takoContents` can download that card's data. `false` means don't bother; the call returns 403. `true` is eligibility, not a guarantee, so still handle errors.
+- **`data_freshness`** — `{ data_as_of, last_updated }`, so you can tell how current a number is.
+
+### Reading a contents item
+
+Each item carries a `cost` (USD) and either a presigned `url` + `expires_at` (url mode) or an inline payload (inline mode). `content_format` tells you what you got:
+
+| `content_format` | Payload field | Meaning |
+| --- | --- | --- |
+| `null` *or absent* | `data` | A web page's extracted text |
+| `'csv'` | `data` | Card data as CSV |
+| `'json_records'` | `records` | Card data as row objects |
+| `'json_compact'` | `dataset` | Card data as typed columns + positional rows |
+
+`total_rows` and `truncated` tell you whether the card held more rows than were returned.
+
+Which format you get depends on the surface. Left unset, `takoContents` returns `'csv'` for cards and no format for web pages, while a card inlined by `sources.data.include_contents` arrives as `'json_compact'` (a `dataset`). Set `content_format` to choose: on `takoContents` for an explicit fetch, or on `sources.data` for a card inlined by a search.
+
+`content_format` is optional as well as nullable, so branch on it loosely — `content_format == null` means web text; `=== null` misses the absent case.
 
 Full type definitions ship with the package.
 
@@ -110,22 +168,34 @@ Full type definitions ship with the package.
 ```typescript
 import type {
   TakoRetrievalConfig,
+  TakoAnswerConfig,
   TakoContentsConfig,
   TakoSearchResult,
   TakoAnswerResult,
   TakoContentsResult,
   TakoCard,
+  TakoCardSource,
   TakoWebResult,
   TakoContentItem,
+  TakoDataset,
+  TakoUsage,
 } from '@takoviz/ai-sdk';
 ```
 
+Every wire type is [`tako-sdk`](https://www.npmjs.com/package/tako-sdk)'s, Tako's client generated from the OpenAPI spec, re-exported under the names above. This package declares only its config types and the normalized tool results. When the API adds a field, it appears here as soon as `tako-sdk` publishes — no release of this package needed.
+
+`tako-sdk` is a runtime dependency. It uses the global `fetch` and runs wherever this package does.
+
+If you need the raw wire shapes (where collections are optional, before the tools normalize them), import `TakoSearchResponse`, `TakoAnswerResponse` or `TakoContentsResponse`.
+
 ## License
 
 MIT
 
 ## Links
 
+- [Migrating from 3.x](./MIGRATING.md#3x--40)
+- [Migrating from 2.x](./MIGRATING.md#2x--30)
 - [Tako documentation](https://docs.tako.com)
 - [Vercel AI SDK](https://sdk.vercel.ai/docs)
 - [GitHub repository](https://github.com/TakoData/ai-sdk)

package/dist/index.d.ts

@@ -1,141 +1,152 @@
 import { Tool } from 'ai';
+import * as sdk from 'tako-sdk';
 
-type TakoSearchEffort = "fast" | "instant" | "deep";
-type TakoContentsMode = "url" | "inline";
-type TakoContentFormat = "csv" | "text";
-/** CardSourceIndex on the response surface. */
-type TakoCardSourceIndex = "tako" | "web" | "connected_data" | "tako_deep_v2";
-type TakoKnowledgeCardRelevance = "High" | "Medium" | "Low";
+type TakoSearchEffort = sdk.SearchEffortLevel;
+type TakoContentsMode = sdk.ContentsDeliveryMode;
+/** Serialization of tabular (Tako card) data. Web text carries no format. */
+type TakoContentFormat = sdk.ContentsFormat;
+/** Public source taxonomy for the card surfaces. */
+type TakoSourceIndex = sdk.TakoSourceIndex;
+type TakoKnowledgeCardRelevance = sdk.KnowledgeCardRelevance;
+type TakoGraphNodeType = sdk.GraphNodeType;
+type TakoDatasetColumnType = sdk.TakoDatasetColumnType;
+/** Web result category. Only "news" filters today; the others are accepted and inert. */
+type TakoWebCategory = sdk.WebCategory;
 interface TakoBaseConfig {
     /** Tako API key. Falls back to TAKO_API_KEY / TAKO_API_TOKEN env vars. */
     apiKey?: string;
     /** API base URL. Default "https://tako.com". */
     baseUrl?: string;
 }
-interface TakoSourceOptions {
-    /** Max results for this source, 1–20 (server default 5). */
-    count?: number;
-    /** Inline this source's underlying data in the response. */
-    includeContents?: boolean;
-}
-interface TakoCardSourceOptions extends TakoSourceOptions {
-    /** Defer data retrieval (faster, less detail). Mutually exclusive with includeContents. */
-    deferDataRetrieval?: boolean;
-}
-interface TakoRetrievalConfig extends TakoBaseConfig {
-    /** "fast" (default) | "instant" | "deep". */
-    effort?: TakoSearchEffort;
-    /** Per-source settings. A source is searched iff its key is present. Omit to search tako + web. */
-    sources?: {
-        tako?: TakoCardSourceOptions;
-        web?: TakoSourceOptions;
-    };
-    /** ISO 3166-1 alpha-2 country code. Default "US". */
-    countryCode?: string;
-    /** BCP-47 locale tag. Default "en-US". */
-    locale?: string;
-    /** IANA timezone, e.g. "America/New_York". */
-    timezone?: string;
-    outputSettings?: {
-        imageDarkMode?: boolean;
-        /** Instant mode only. */
-        forceRefresh?: boolean;
-    };
-}
-interface TakoContentsConfig extends TakoBaseConfig {
-    /** "url" (default) returns a presigned link; "inline" returns content in the body. */
-    mode?: TakoContentsMode;
-}
-interface TakoResultContent {
-    format: TakoContentFormat;
-    cost: number;
-    data?: string | null;
-    total_rows?: number | null;
-    truncated?: boolean;
-}
-interface TakoCardSourceIndexSegment {
-    index_type: TakoCardSourceIndex;
-    segment_id: string;
-}
-interface TakoCardSourcePrivateIndex {
-    index_type: TakoCardSourceIndex;
-    private_index_id: string;
-    /** Optional for private indexes. */
-    segment_id?: string | null;
-}
-interface TakoKnowledgeCardSource {
-    source_name: string | null;
-    source_description: string | null;
-    source_index: TakoCardSourceIndex | TakoCardSourceIndexSegment | TakoCardSourcePrivateIndex;
-    url: string | null;
-    source_text?: string | null;
-}
-interface TakoKnowledgeCardMethodology {
-    methodology_name: string | null;
-    methodology_description: string | null;
-}
-interface TakoCard {
-    card_id?: string | null;
-    title?: string | null;
-    description?: string | null;
-    semantic_description?: string | null;
-    webpage_url?: string | null;
-    image_url?: string | null;
-    embed_url?: string | null;
-    sources?: TakoKnowledgeCardSource[] | null;
-    methodologies?: TakoKnowledgeCardMethodology[] | null;
-    source_indexes?: (TakoCardSourceIndex | TakoCardSourceIndexSegment)[] | null;
-    card_type?: string | null;
-    relevance?: TakoKnowledgeCardRelevance | null;
-    content?: TakoResultContent | null;
-}
-interface TakoWebResult {
-    title: string;
-    url: string;
-    snippet?: string | null;
-    source_name?: string | null;
-    publish_date?: string | null;
-    content?: TakoResultContent | null;
-    citation_number?: number | null;
-}
-interface TakoContentItem extends TakoResultContent {
-    source_url: string;
-    url?: string | null;
-    expires_at?: string | null;
-}
-interface TakoSearchResult {
+/**
+ * The curated Tako data source. Three `DataSourceSettings` keys are omitted
+ * because you can't use them correctly from this package:
+ *
+ * - `mode` — the API documents it as having no effect on Tako cards, which
+ *   always inline rows. Setting `"url"` looks like it should return download
+ *   links and doesn't.
+ * - `node_ids` — takes ids from the `/v1/graph` endpoints, which this package
+ *   doesn't wrap, and the ids don't survive a knowledge-graph rebuild.
+ * - `strict` — only meaningful with `node_ids`.
+ *
+ * The omission is a type. The API accepts the keys if you send them anyway.
+ */
+type TakoDataSourceOptions = Omit<sdk.DataSourceSettings, "mode" | "node_ids" | "strict">;
+/** The web source. Every `WebSourceSettings` key, unchanged. */
+type TakoWebSourceOptions = sdk.WebSourceSettings;
+/**
+ * Tako searches exactly the sources whose keys are present. Omit `sources` to
+ * search data and web.
+ *
+ * Derived from `sdk.Sources`, not a literal `{ data, web }` pair. Spelling the
+ * pair out is the one edit that silently breaks this file's promise: a source
+ * Tako adds would serialize on the wire and still be unreachable here, and the
+ * `keyof` pin in `config_types.test.ts` would stay green because a hand-written
+ * source set is what forced it to exclude `sources` in the first place.
+ */
+interface TakoSources extends Omit<sdk.Sources, "data"> {
+    data?: TakoDataSourceOptions;
+}
+/** Config for `takoSearch`: the `/v3/search` request body without `query`. */
+interface TakoRetrievalConfig extends TakoBaseConfig, Omit<sdk.SearchRequest, "query" | "sources"> {
+    sources?: TakoSources;
+}
+/**
+ * Config for `takoAnswer`: the `/v1/answer` request body without `query`.
+ * A superset of {@link TakoRetrievalConfig}, so one config object can build
+ * both tools. Adds `output_schema`, a JSON Schema Tako fills from the same
+ * evidence as `answer` and returns as `structured_output`.
+ *
+ * `output_schema` needs `effort` `"fast"` or `"deep"`. `takoAnswer` throws on
+ * the pair rather than letting every call 400.
+ */
+interface TakoAnswerConfig extends TakoBaseConfig, Omit<sdk.AnswerRequest, "query" | "sources"> {
+    sources?: TakoSources;
+}
+/**
+ * Config for `takoContents`: the `/v1/contents` request body without `url`.
+ * `mode` and `quote_only` also change the tool description the model reads.
+ */
+interface TakoContentsConfig extends TakoBaseConfig, Omit<sdk.ContentsRequest, "url"> {
+}
+type TakoUsageCompute = sdk.UsageCompute;
+type TakoUsageData = sdk.UsageData;
+/**
+ * Usage for one metered request. As of 2026-08 the API doesn't populate it on
+ * search, answer or contents. For per-item pricing today, read
+ * `TakoResultContent.cost` and `TakoResultContent.export_pricing`.
+ */
+type TakoUsage = sdk.Usage;
+type TakoDatasetColumn = sdk.TakoDatasetColumn;
+type TakoDatasetSource = sdk.TakoDatasetSource;
+type TakoDatasetCell = sdk.TakoDatasetCell;
+type TakoDataset = sdk.TakoDataset;
+type TakoExportPricing = sdk.ExportPricing;
+type TakoColumnDescriptor = sdk.ColumnDescriptor;
+/**
+ * Describes the downloadable content behind a result. `content_format` is
+ * optional as well as nullable — web text may arrive as `null` or an absent key.
+ * Test it loosely (`content_format == null`), never with `=== null`.
+ */
+type TakoResultContent = sdk.ResultContent;
+type TakoContentItem = sdk.ContentItem;
+type TakoCardSource = sdk.TakoCardSource;
+type TakoKnowledgeCardMethodology = sdk.KnowledgeCardMethodology;
+type TakoCardNode = sdk.TakoCardNode;
+type TakoMetricDefinition = sdk.MetricDefinition;
+type TakoDataFreshness = sdk.DataFreshness;
+type TakoCard = sdk.TakoCard;
+type TakoWebResult = sdk.WebResult;
+/** The raw `POST /api/v3/search` body. Only `request_id` is guaranteed. */
+type TakoSearchResponse = sdk.SearchResponse;
+/** The raw `POST /api/v1/answer` body. */
+type TakoAnswerResponse = sdk.AnswerResponse;
+/** The raw `POST /api/v1/contents` body. */
+type TakoContentsResponse = sdk.ContentsResponse;
+type TakoSearchResult = Omit<TakoSearchResponse, "cards" | "web_results"> & {
     cards: TakoCard[];
     web_results: TakoWebResult[];
-    contents_total_cost: number;
-    request_id: string;
-}
-interface TakoAnswerResult {
+};
+type TakoAnswerResult = Omit<TakoAnswerResponse, "cards" | "web_results"> & {
     /** Synthesized text answer. */
     answer: string;
     /** Backing cards; cards[0] is the lead card. */
     cards: TakoCard[];
     web_results: TakoWebResult[];
-    contents_total_cost: number;
-    request_id: string;
-}
-interface TakoContentsResult {
+};
+type TakoContentsResult = Omit<TakoContentsResponse, "contents"> & {
     contents: TakoContentItem[];
-    request_id: string;
-}
+};
 
 /** Tako fast-pipeline search: returns Tako cards + web results, no LLM synthesis. */
 declare function takoSearch(config?: TakoRetrievalConfig): Tool<{
     query: string;
 }, TakoSearchResult>;
 
-/** Tako answer: fast-pipeline retrieval plus an LLM-synthesized answer grounded in the results. */
-declare function takoAnswer(config?: TakoRetrievalConfig): Tool<{
+/**
+ * Tako answer: fast-pipeline retrieval plus an LLM-synthesized answer grounded in the results.
+ *
+ * Resolves to `{ answer, cards, web_results, ... }` — `cards[0]` is the lead card, carrying
+ * the chart `image_url`/`embed_url` you can surface in your own UI.
+ */
+declare function takoAnswer(config?: TakoAnswerConfig): Tool<{
     query: string;
 }, TakoAnswerResult>;
 
-/** Download the data behind a result URL: a Tako card's CSV or a web page's text. */
+/**
+ * Download the data behind a result URL: a Tako card's CSV or a web page's text.
+ *
+ * `mode` sets the delivery, and is reflected in the tool description the model reads:
+ * - `"url"` — a short-lived presigned download url. Use when handing a
+ *   download/embed link to a user, or for large data you won't read yourself.
+ * - `"inline"` — the content in the response body, so the model can read and reason
+ *   over the numbers directly.
+ *
+ * Left unset, the API chooses and the description tells the model to read the response.
+ * Set `mode` to pin the delivery and tell the model which one to expect.
+ */
 declare function takoContents(config?: TakoContentsConfig): Tool<{
     url: string;
 }, TakoContentsResult>;
 
-export { type TakoAnswerResult, type TakoBaseConfig, type TakoCard, type TakoCardSourceIndex, type TakoCardSourceIndexSegment, type TakoCardSourceOptions, type TakoCardSourcePrivateIndex, type TakoContentFormat, type TakoContentItem, type TakoContentsConfig, type TakoContentsMode, type TakoContentsResult, type TakoKnowledgeCardMethodology, type TakoKnowledgeCardRelevance, type TakoKnowledgeCardSource, type TakoResultContent, type TakoRetrievalConfig, type TakoSearchEffort, type TakoSearchResult, type TakoSourceOptions, type TakoWebResult, takoAnswer, takoContents, takoSearch };
+export { type TakoAnswerConfig, type TakoAnswerResponse, type TakoAnswerResult, type TakoBaseConfig, type TakoCard, type TakoCardNode, type TakoCardSource, type TakoColumnDescriptor, type TakoContentFormat, type TakoContentItem, type TakoContentsConfig, type TakoContentsMode, type TakoContentsResponse, type TakoContentsResult, type TakoDataFreshness, type TakoDataSourceOptions, type TakoDataset, type TakoDatasetCell, type TakoDatasetColumn, type TakoDatasetColumnType, type TakoDatasetSource, type TakoExportPricing, type TakoGraphNodeType, type TakoKnowledgeCardMethodology, type TakoKnowledgeCardRelevance, type TakoMetricDefinition, type TakoResultContent, type TakoRetrievalConfig, type TakoSearchEffort, type TakoSearchResponse, type TakoSearchResult, type TakoSourceIndex, type TakoSources, type TakoUsage, type TakoUsageCompute, type TakoUsageData, type TakoWebCategory, type TakoWebResult, type TakoWebSourceOptions, takoAnswer, takoContents, takoSearch };

package/dist/index.js

@@ -3,33 +3,28 @@ import { tool } from "ai";
 import { z } from "zod";
 
 // src/client.ts
-async function callTako(opts) {
-  const { baseUrl, path, apiKey, body, operation } = opts;
-  if (!apiKey) {
-    throw new Error(
-      "TAKO_API_KEY is required. Set it in environment variables or pass it in config."
-    );
+import { Tako } from "tako-sdk";
+
+// src/errors.ts
+import { FetchError, ResponseError } from "tako-sdk";
+function isResponseError(error) {
+  return error instanceof ResponseError || error instanceof Error && error.name === "ResponseError" && "response" in error;
+}
+function isFetchError(error) {
+  return error instanceof FetchError || error instanceof Error && error.name === "FetchError" && "cause" in error;
+}
+async function wrapTakoError(error, operation) {
+  const prefix = `Failed to ${operation} with Tako: `;
+  if (isResponseError(error)) {
+    const body = await error.response.text().catch(() => "");
+    return new Error(`${prefix}Tako API error: ${error.response.status} - ${body}`, { cause: error });
   }
-  try {
-    const response = await fetch(`${baseUrl}${path}`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-API-Key": apiKey
-      },
-      body: JSON.stringify(body)
-    });
-    if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`Tako API error: ${response.status} - ${errorText}`);
-    }
-    return await response.json();
-  } catch (error) {
-    if (error instanceof Error) {
-      throw new Error(`Failed to ${operation} with Tako: ${error.message}`);
-    }
-    throw error;
+  if (isFetchError(error)) {
+    const cause = error.cause instanceof Error ? error.cause.message : String(error.cause);
+    return new Error(`${prefix}${cause}`, { cause: error });
   }
+  if (error instanceof Error) return new Error(`${prefix}${error.message}`, { cause: error });
+  return new Error(`${prefix}${String(error)}`, { cause: error });
 }
 
 // src/request.ts
@@ -41,53 +36,77 @@ function resolveBaseUrl(config) {
   return (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 }
 function buildSearchRequestBody(config, query) {
-  const body = {
-    query,
-    effort: config.effort ?? "fast",
-    country_code: config.countryCode ?? "US",
-    locale: config.locale ?? "en-US"
+  const { apiKey: _apiKey, baseUrl: _baseUrl, ...request } = config;
+  return { ...request, query };
+}
+function buildAnswerRequestBody(config, query) {
+  const { apiKey: _apiKey, baseUrl: _baseUrl, ...request } = config;
+  return { ...request, query };
+}
+function buildContentsRequestBody(url, config) {
+  const { apiKey: _apiKey, baseUrl: _baseUrl, ...request } = config;
+  return { ...request, url };
+}
+function normalizeSearchResult(response) {
+  return {
+    ...response,
+    cards: response.cards ?? [],
+    web_results: response.web_results ?? []
   };
-  if (config.sources) {
-    const sources = {};
-    if (config.sources.tako) {
-      const tako = {};
-      if (config.sources.tako.count !== void 0) tako.count = config.sources.tako.count;
-      if (config.sources.tako.includeContents !== void 0) tako.include_contents = config.sources.tako.includeContents;
-      if (config.sources.tako.deferDataRetrieval !== void 0) tako.defer_data_retrieval = config.sources.tako.deferDataRetrieval;
-      sources.tako = tako;
-    }
-    if (config.sources.web) {
-      const web = {};
-      if (config.sources.web.count !== void 0) web.count = config.sources.web.count;
-      if (config.sources.web.includeContents !== void 0) web.include_contents = config.sources.web.includeContents;
-      sources.web = web;
-    }
-    body.sources = sources;
+}
+function normalizeAnswerResult(response) {
+  return {
+    ...response,
+    cards: response.cards ?? [],
+    web_results: response.web_results ?? []
+  };
+}
+function normalizeContentsResult(response) {
+  return { ...response, contents: response.contents ?? [] };
+}
+
+// src/client.ts
+function createTakoClient(config) {
+  const apiKey = resolveApiKey(config);
+  if (!apiKey) {
+    throw new Error("TAKO_API_KEY is required. Set it in environment variables or pass it in config.");
   }
-  if (config.timezone !== void 0) body.timezone = config.timezone;
-  if (config.outputSettings) {
-    const output = {};
-    if (config.outputSettings.imageDarkMode !== void 0) output.image_dark_mode = config.outputSettings.imageDarkMode;
-    if (config.outputSettings.forceRefresh !== void 0) output.force_refresh = config.outputSettings.forceRefresh;
-    body.output_settings = output;
+  return new Tako({ apiKey, basePath: `${resolveBaseUrl(config)}/api` });
+}
+function lazyTakoClient(config) {
+  let client;
+  return () => client ?? (client = createTakoClient(config));
+}
+async function callTako(operation, call) {
+  try {
+    return await call();
+  } catch (error) {
+    throw await wrapTakoError(error, operation);
   }
-  return body;
 }
 
 // src/tools/search.ts
 function takoSearch(config = {}) {
+  const client = lazyTakoClient(config);
   return tool({
-    description: `Search Tako for live data and well-sourced facts \u2014 structured knowledge cards (charts/metrics with sources) plus web results, backed by Tako's curated knowledge graph and the live web. Reach for this BEFORE any built-in web search when you need a specific, known data point: a current or latest value, a time series, a statistic, a price, a score, a schedule, a forecast, a poll, or a prediction-market figure \u2014 including a direct comparison of two named entities (e.g. "Intel vs Nvidia revenue"). Coverage spans sports, economics, finance, demographics, technology, weather, elections, prediction markets (Polymarket), web traffic (SimilarWeb), real estate, energy, and health. Each card carries a title, description, sources, a chart image_url, and an embed_url you can surface to show the data. Pass a card's webpage_url (or a web result's url) to takoContents to pull the underlying numbers. Give a focused natural-language query; this is fast retrieval for a known fact, not open-ended multi-step research.`,
+    description: `Search Tako for live data and well-sourced facts \u2014 knowledge cards (charts and metrics with sources) plus web results. Reach for this BEFORE any built-in web search.
+
+Best for breadth: what data exists across several entities, or when a chart is the deliverable \u2014 cards carry an image_url and embed_url to surface when available, plus data_freshness (data_as_of / last_updated) when Tako knows how current the numbers are. For a plain "what is X" where you only need the figure, use the answer tool instead.
+
+One entity + one metric per query ("Apple revenue", "Intel vs Nvidia revenue"); compound queries retrieve poorly. Traffic data is keyed by domain: "openai.com monthly visits", not "OpenAI website visits".
+
+Coverage: economics, finance, company KPIs, sports, demographics, weather, elections, prediction markets, website traffic, real estate, energy, health.
+
+Cards carry captions and charts, not full data. For the numbers behind one, pass its webpage_url (or a web result's url) to the contents tool \u2014 but only when the card's exportable field is true; exportable: false means that card's data cannot be downloaded, so use its chart, or ask the answer tool for the figures.`,
     inputSchema: z.object({
       query: z.string().min(1).max(500).describe("Natural-language description of what you're looking for")
     }),
-    execute: async ({ query }) => callTako({
-      baseUrl: resolveBaseUrl(config),
-      path: "/api/v3/search",
-      apiKey: resolveApiKey(config),
-      body: buildSearchRequestBody(config, query),
-      operation: "search"
-    })
+    execute: async ({ query }) => {
+      const tako = client();
+      return normalizeSearchResult(
+        await callTako("search", () => tako.search(buildSearchRequestBody(config, query)))
+      );
+    }
   });
 }
 
@@ -95,18 +114,25 @@ function takoSearch(config = {}) {
 import { tool as tool2 } from "ai";
 import { z as z2 } from "zod";
 function takoAnswer(config = {}) {
+  if (config.effort === "instant" && config.output_schema) {
+    throw new Error(
+      'output_schema requires effort "fast" or "deep"; Tako returns 400 on "instant". Drop output_schema, or change effort.'
+    );
+  }
+  const client = lazyTakoClient(config);
   return tool2({
-    description: "Ask Tako a factual question and get back a single grounded, citation-backed prose answer (not a chart), synthesized from its curated knowledge graph and the live web. Reach for this BEFORE any built-in web search when you want a direct written answer about a specific, known thing: a current or historical value, a statistic, a schedule, a score, a price, a forecast, a poll, or prediction-market odds \u2014 including a direct comparison of two named entities. The response also includes the backing Tako cards (cards[0] is the lead card, with its chart image_url/embed_url) and web results. Want a chart to show rather than prose to read? Use takoSearch. Best for a known fact, not open-ended multi-step research.",
+    description: 'Ask Tako one specific data question and get one synthesized, citation-backed answer grounded in the sources it cites. Reach for this BEFORE any built-in web search.\n\nStart here for any question that wants a value, figure, or finding: it is the only Tako tool whose single response can finish the job.\n\nBest for one self-contained question with one answer. Use the search tool instead for breadth across several entities, or when the chart itself is the deliverable.\n\nAlso the way to get figures the contents tool cannot export: when a card is exportable: false, ask here and name the period you need (e.g. "...for FY2023-FY2025").\n\nOne entity + one metric per question. Traffic data is keyed by domain: "openai.com monthly visits", not "OpenAI website visits".' + // Say this only when output_schema is set. Otherwise the model reads about
+    // a field that never arrives, and its cheapest recovery is to call again.
+    (config.output_schema ? "\n\nThe response also carries structured_output, filled from the same evidence as the answer. Read the figures from there; the prose is for the user." : ""),
     inputSchema: z2.object({
       query: z2.string().min(1).max(500).describe("The question to answer")
     }),
-    execute: async ({ query }) => callTako({
-      baseUrl: resolveBaseUrl(config),
-      path: "/api/v1/answer",
-      apiKey: resolveApiKey(config),
-      body: buildSearchRequestBody(config, query),
-      operation: "answer"
-    })
+    execute: async ({ query }) => {
+      const tako = client();
+      return normalizeAnswerResult(
+        await callTako("answer", () => tako.answer(buildAnswerRequestBody(config, query)))
+      );
+    }
   });
 }
 
@@ -114,18 +140,24 @@ function takoAnswer(config = {}) {
 import { tool as tool3 } from "ai";
 import { z as z3 } from "zod";
 function takoContents(config = {}) {
+  const client = lazyTakoClient(config);
   return tool3({
-    description: `Fetch the underlying data behind a result URL \u2014 a Tako card's webpage_url yields a CSV of the card's data; any other URL (a web result's url) yields the page's extracted full text. Pass a single url taken from a prior takoSearch/takoAnswer result. Delivery is set at construction via \`mode\`: the default "url" returns a short-lived presigned download_url (no row cap) for handing over a download/embed link or for large data you won't read yourself; "inline" instead returns the content in the response (CSV capped at 1000 rows, with total_rows/truncated, or web text) so you can read and reason over the numbers directly.`,
+    description: "Fetch the real data behind a result url \u2014 a Tako card's webpage_url yields its rows; any other url (a web result's) yields the page's full extracted text. Only call this on a url returned by a prior search or answer call, which gives you a caption and a chart but not the rows.\n\n" + // `quote_only` outranks `mode`: the API ignores mode on a quote and returns
+    // null for url and every payload field. Describing either delivery here
+    // would promise content that never arrives, and the model's cheapest
+    // recovery from an unexplained null is to call again.
+    (config.quote_only ? "Configured for price quotes only: returns the export cost and rate card, and NO content. The url and data fields are always null and the call is free \u2014 report the price, and do not call again expecting rows.\n\n" : config.mode === "inline" ? "Returns the content in the response body \u2014 read and compute over the numbers directly.\n\n" : config.mode === "url" ? "Returns a short-lived presigned download url, NOT the data itself: surface the link, do not parse it or call again expecting rows.\n\n" : "Delivery follows the API's own default, so read the response rather than assuming: if the item carries a url and no content, surface the link and do not parse it; if it carries content, read and compute over it directly.\n\n") + "Only cards whose exportable field is true can be downloaded; a non-exportable card always returns 403 and retrying will not change that \u2014 get its figures from the answer tool instead, naming the period you need. Web urls always work, so this is also the fallback when a search surfaced a relevant web result but no fitting data card.\n\nOn each returned item, content_format names the serialization for card data and is null or absent for web page text; total_rows and truncated tell you whether the card had more rows than were returned.",
     inputSchema: z3.object({
-      url: z3.string().min(1).describe("A TakoCard.webpage_url or WebResult.url to download contents for")
+      // Validated as a url so a malformed value fails here, with a message the
+      // model can act on, instead of costing a priced round trip to the API.
+      url: z3.url().describe("A TakoCard.webpage_url or WebResult.url to download contents for")
     }),
-    execute: async ({ url }) => callTako({
-      baseUrl: resolveBaseUrl(config),
-      path: "/api/v1/contents",
-      apiKey: resolveApiKey(config),
-      body: { url, mode: config.mode ?? "url" },
-      operation: "fetch contents"
-    })
+    execute: async ({ url }) => {
+      const tako = client();
+      return normalizeContentsResult(
+        await callTako("fetch contents", () => tako.contents(buildContentsRequestBody(url, config)))
+      );
+    }
   });
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takoviz/ai-sdk",
-  "version": "2.0.1",
+  "version": "4.0.0",
   "description": "Tako knowledge search, answer, and contents tools for the Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -8,10 +8,11 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
+  "sideEffects": false,
   "files": [
     "dist"
   ],
@@ -41,16 +42,25 @@
   "devDependencies": {
     "@ai-sdk/openai": "^4.0.0",
     "@types/node": "^24.10.1",
+    "@types/semver": "^7.8.0",
     "ai": "^7.0.0",
+    "semver": "^7.8.5",
     "tsup": "^8.5.0",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
     "vitest": "^3.0.0"
   },
+  "dependencies": {
+    "tako-sdk": "^1.3.0"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",
     "typecheck": "tsc --noEmit -p tsconfig.check.json",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:live": "vitest run --config vitest.live.config.ts",
+    "test:package": "node scripts/verify-package.mjs",
+    "lint:package": "npm run --silent build && npx -y publint@latest --strict --pack npm && npx -y @arethetypeswrong/cli@latest --pack . --ignore-rules cjs-resolves-to-esm",
+    "check:sdk-lag": "tsx scripts/check-sdk-lag.ts"
   }
 }