@takoviz/ai-sdk 3.0.0 → 4.0.0

package/README.md

@@ -55,87 +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
-    data: { count: 5, includeContents: false }, // legacy alias: tako
-    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' } },
 });
 ```
 
-`takoContents` takes:
+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
-takoContents({
-  apiKey: 'your_api_key',
-  baseUrl: 'https://tako.com',
-  mode: 'url',                 // 'url' (default) → presigned link; 'inline' → content in the response
+takoSearch({
+  sources: { web: { category: 'news', published_after: new Date('2026-08-19'), count: 5 } },
 });
 ```
 
-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`.
-
-### Search and answer options
-
-Both tools take the same config. Every field is optional; omit one and the API's default applies.
+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.
 
-| Option | Type | Notes |
-| --- | --- | --- |
-| `effort` | `"fast" \| "instant" \| "deep"` | Default `"fast"`. |
-| `countryCode` / `locale` / `timezone` | `string` | Default `"US"` / `"en-US"`. |
-| `location` | `{ latitude, longitude }` | End-user coordinates. |
-| `outputSettings.imageDarkMode` | `boolean` | |
-| `outputSettings.forceRefresh` | `boolean` | Instant mode only. |
-
-**`sources.data`** — the curated Tako source:
-
-| Option | Type | Notes |
-| --- | --- | --- |
-| `count` | `number` | 1-20, server default 5. |
-| `includeContents` | `boolean` | Inline the card data. |
-| `contentFormat` | `"csv" \| "json_records" \| "json_compact"` | Server default `"json_compact"`. |
-| `nodeIds` | `string[]` | Pin graph nodes. Ids come from the `/v1/graph` endpoints. |
-| `strict` | `boolean` | Return only cards matching a pinned node. Requires `nodeIds`. |
-| `mode` | `"url" \| "inline"` | Server default `"inline"`. Accepted, but the API documents no effect on Tako cards. |
+```typescript
+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,
+  },
+});
+```
 
-**`sources.web`**:
+A `TakoRetrievalConfig` is also a valid `TakoAnswerConfig`, so one object can build both tools.
 
-| Option | Type | Notes |
-| --- | --- | --- |
-| `count` | `number` | 1-20. Server default 5 for `takoSearch`, 3 for `takoAnswer`. |
-| `includeContents` | `boolean` | Include full article text. |
-| `category` | `"news" \| "sports" \| "finance"` | Only `"news"` filters today. |
-| `includeDomains` / `excludeDomains` | `string[]` | Bare hosts, for example `"cnn.com"`. |
-| `publishedAfter` / `publishedBefore` | `string` | ISO `"YYYY-MM-DD"`. Results with no known date are kept. |
-| `snippetMaxChars` | `number` | Server default 1000. |
-| `articleContentMaxChars` | `number` | Server default 30000. |
+### Contents delivery
 
-### Contents options
+Two `takoContents` options also change the description the model reads, so pick them deliberately:
 
-| Option | Type | Notes |
-| --- | --- | --- |
-| `mode` | `"url" \| "inline"` | Default `"url"`. Changes the tool description the model reads. |
-| `contentFormat` | `"csv" \| "json_records" \| "json_compact"` | Server default `"csv"` on this surface. |
-| `maxRows` | `number` | Card exports only. The first 20 rows are free; **rows above that bill at the per-1000-row rate**. |
-| `maxChars` | `number` | Web page text only. Server default 1000000, the full page text. |
-| `quoteOnly` | `boolean` | Price the export without fetching it. The request is free and the payload is null. |
+- `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.
 
-This SDK does not check the numeric ranges. The API enforces them, so a limit Tako raises works immediately without an SDK release. Most out-of-range values return a 400.
+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.
 
-**`maxRows` is the exception, and it fails quietly.** A value above the 2,000-row ceiling is clamped, not rejected, and billing counts the rows actually returned. You get a short export, a charge for it, and no error. Check `total_rows` and `truncated` on the returned item to see what you actually got.
+`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
 
@@ -176,7 +157,7 @@ Each item carries a `cost` (USD) and either a presigned `url` + `expires_at` (ur
 
 `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.includeContents` arrives as `'json_compact'` (a `dataset`). Set `contentFormat` to choose: on `takoContents` for an explicit fetch, or on `sources.data` for a card inlined by a search.
+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.
 
@@ -187,6 +168,7 @@ Full type definitions ship with the package.
 ```typescript
 import type {
   TakoRetrievalConfig,
+  TakoAnswerConfig,
   TakoContentsConfig,
   TakoSearchResult,
   TakoAnswerResult,
@@ -200,7 +182,9 @@ import type {
 } from '@takoviz/ai-sdk';
 ```
 
-The types mirror Tako's published OpenAPI document. `tests/contract/` validates them against a vendored copy of that spec and against [`tako-sdk`](https://www.npmjs.com/package/tako-sdk), Tako's official generated client, so a type that stops matching the API fails CI. Both references are pinned snapshots, refreshed by `pnpm spec:refresh` and a `tako-sdk` bump.
+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`.
 
@@ -210,7 +194,8 @@ MIT
 
 ## Links
 
-- [Migrating from 2.x](./MIGRATING.md)
+- [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,363 +1,122 @@
 import { Tool } from 'ai';
+import * as sdk from 'tako-sdk';
 
-type TakoSearchEffort = "fast" | "instant" | "deep";
-type TakoContentsMode = "url" | "inline";
+type TakoSearchEffort = sdk.SearchEffortLevel;
+type TakoContentsMode = sdk.ContentsDeliveryMode;
 /** Serialization of tabular (Tako card) data. Web text carries no format. */
-type TakoContentFormat = "csv" | "json_records" | "json_compact";
+type TakoContentFormat = sdk.ContentsFormat;
 /** Public source taxonomy for the card surfaces. */
-type TakoSourceIndex = "data" | "web";
-/**
- * @deprecated Renamed to {@link TakoSourceIndex}, and the value set collapsed:
- * 2.x had `"tako" | "web" | "connected_data" | "tako_deep_v2"`, this resolves to
- * `"data" | "web"`. Comparisons against the removed values no longer compile.
- */
-type TakoCardSourceIndex = TakoSourceIndex;
-type TakoKnowledgeCardRelevance = "High" | "Medium" | "Low";
-type TakoGraphNodeType = "metric" | "entity";
-type TakoDatasetColumnType = "string" | "number" | "boolean" | "date" | "datetime";
+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 = "news" | "sports" | "finance";
+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.
-     *
-     * The server default differs by tool: `takoSearch` returns 5, `takoAnswer`
-     * returns 3. Set this value when you need the same count from both.
-     */
-    count?: number;
-    /** Inline this source's underlying data in the response. */
-    includeContents?: boolean;
-}
-/** Options for the curated Tako data source. Mirrors the API's `DataSourceSettings`. */
-interface TakoDataSourceOptions extends TakoSourceOptions {
-    /**
-     * Delivery for card data inlined by this search.
-     *
-     * The API documents this field as having no effect on Tako cards, which always
-     * return a small inline preview. It stays for schema stability. This is a
-     * different field from {@link TakoContentsConfig.mode}, which does control
-     * delivery for an explicit contents call.
-     */
-    mode?: TakoContentsMode;
-    /** Serialization for inlined card data. Server default "json_compact". */
-    contentFormat?: TakoContentFormat;
-    /**
-     * Graph node ids to pin into the search. Get ids from the /v1/graph endpoints,
-     * which this SDK does not wrap. Ids do not survive a knowledge-graph rebuild:
-     * resolve them per request rather than storing them.
-     */
-    nodeIds?: string[];
-    /** Return only cards that match a pinned node. Requires a non-empty `nodeIds`. */
-    strict?: boolean;
-}
-/** Options for the web source. Mirrors the API's `WebSourceSettings`. */
-interface TakoWebSourceOptions extends TakoSourceOptions {
-    /** Restrict web results to a category. */
-    category?: TakoWebCategory;
-    /** Return only results from these bare hosts, for example "cnn.com". */
-    includeDomains?: string[];
-    /** Drop results from these bare hosts. */
-    excludeDomains?: string[];
-    /** Character cap on the excerpt per web result. Server default 1000. */
-    snippetMaxChars?: number;
-    /** Character cap on full article text when `includeContents` is true. Server default 30000. */
-    articleContentMaxChars?: number;
-    /**
-     * Keep results published on or after this ISO date, "YYYY-MM-DD".
-     *
-     * This is not a recency guarantee. The API keeps a result whose publication
-     * date it does not know, so undated pages still arrive.
-     */
-    publishedAfter?: string;
-    /**
-     * Keep results published on or before this ISO date, "YYYY-MM-DD".
-     *
-     * The API keeps a result whose publication date it does not know.
-     */
-    publishedBefore?: string;
-}
-/** @deprecated Renamed to {@link TakoDataSourceOptions}. */
-type TakoCardSourceOptions = TakoDataSourceOptions;
-/** End-user coordinates used to localize results. */
-interface TakoGeoLocation {
-    /** Degrees, -90 to 90. */
-    latitude: number;
-    /** Degrees, -180 to 180. */
-    longitude: number;
-}
-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 data + web. */
-    sources?: {
-        /** The curated Tako data source. */
-        data?: TakoDataSourceOptions;
-        web?: TakoWebSourceOptions;
-        /** @deprecated Use `data`. Legacy alias for the curated Tako source. */
-        tako?: TakoDataSourceOptions;
-    };
-    /** End-user coordinates. Use with `countryCode` for location-sensitive queries. */
-    location?: TakoGeoLocation;
-    /** 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;
-    /** Serialization for card data. Server default "csv" on this surface. */
-    contentFormat?: TakoContentFormat;
-    /**
-     * Cap on rows returned for a card export. The server default is the 20-row free
-     * allowance. Rows above that allowance bill at the per-1000-row rate, so raise
-     * this only when you need the extra rows. Web urls ignore this field.
-     */
-    maxRows?: number;
-    /** Character cap on extracted web page text. Server default 1000000, the full page text. Card urls ignore this field. */
-    maxChars?: number;
-    /**
-     * Return only the price of the export, without the content. The request is free
-     * and the item's payload and url are null. The server ignores `mode` and
-     * `contentFormat`.
-     */
-    quoteOnly?: boolean;
-}
-interface TakoUsageCompute {
-    /** USD cost of running the operation. */
-    cost_usd: number;
-}
-interface TakoUsageData {
-    /** USD cost of the inline data delivered in the response. */
-    cost_usd: number;
-    /** Number of billed data units (datasets) in the response. */
-    datasets: number;
-}
 /**
- * Usage for one metered request. `total_cost_usd` always equals the sum of
- * whichever breakdown components are present.
+ * The curated Tako data source. Three `DataSourceSettings` keys are omitted
+ * because you can't use them correctly from this package:
  *
- * The spec defines this as the successor to the removed `contents_total_cost`,
- * but as of 2026-08 the API does not populate it on search, answer or contents
- * (verified live across plain, deep and include_contents calls). Treat it as
- * genuinely optional. For per-item pricing today, read `TakoResultContent.cost`
- * and `TakoResultContent.export_pricing`, which are populated.
+ * - `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.
  */
-interface TakoUsage {
-    /** Total quoted USD cost of this request. */
-    total_cost_usd: number;
-    /** Compute breakdown. Absent on surfaces with no compute step (contents). */
-    compute?: TakoUsageCompute | null;
-    /** Inline-data breakdown. Present only when billable inline data was emitted. */
-    data?: TakoUsageData | null;
-}
-interface TakoDatasetColumn {
-    name: string;
-    type: TakoDatasetColumnType;
-    /** Structured unit, e.g. "USD billions", "%". Null when unitless. */
-    unit?: string | null;
-}
-interface TakoDatasetSource {
-    /** Human-readable source name, e.g. "FRED". */
-    name: string;
-    index?: TakoSourceIndex;
-}
-type TakoDatasetCell = string | number | boolean | null;
-/** Exact retrieved rows as positional arrays in `columns` order. */
-interface TakoDataset {
-    columns: TakoDatasetColumn[];
-    rows: TakoDatasetCell[][];
-    total_rows: number;
-    truncated: boolean;
-    /** Source URL the dataset was derived from. */
-    ref: string;
-    sources: TakoDatasetSource[];
-    provenance?: "query" | "web_extraction";
-}
+type TakoDataSourceOptions = Omit<sdk.DataSourceSettings, "mode" | "node_ids" | "strict">;
+/** The web source. Every `WebSourceSettings` key, unchanged. */
+type TakoWebSourceOptions = sdk.WebSourceSettings;
 /**
- * Rate card for a card export, so cost can be computed before fetching:
- * `baseline_usd + row_cpm_usd * max(0, rows - free_rows) / 1000`.
+ * 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 TakoExportPricing {
-    baseline_usd: number;
-    row_cpm_usd: number;
-    free_rows: number;
-    max_rows_ceiling: number;
+interface TakoSources extends Omit<sdk.Sources, "data"> {
+    data?: TakoDataSourceOptions;
 }
-/** Per-column metadata; entry i describes column i. */
-interface TakoColumnDescriptor {
-    name?: string | null;
-    metric?: string | null;
-    entity?: string | null;
-    unit?: string | null;
-    dtype?: TakoDatasetColumnType | null;
+/** Config for `takoSearch`: the `/v3/search` request body without `query`. */
+interface TakoRetrievalConfig extends TakoBaseConfig, Omit<sdk.SearchRequest, "query" | "sources"> {
+    sources?: TakoSources;
 }
 /**
- * Describes the downloadable content behind a result.
- *
- * Exactly one payload group is populated once contents are delivered: `data`
- * (CSV or web text), `records` (verbose JSON), `dataset` (compact), or
- * `url` + `expires_at` (presigned download). When every payload field is unset
- * this is just a price quote.
+ * 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`.
  *
- * `content_format` distinguishes a web page's extracted text from a card's
- * tabular data, but it is optional as well as nullable — web text may arrive as
- * either `null` or an absent key. Test it loosely (`content_format == null`),
- * never with `=== null`.
+ * `output_schema` needs `effort` `"fast"` or `"deep"`. `takoAnswer` throws on
+ * the pair rather than letting every call 400.
  */
-interface TakoResultContent {
-    content_format?: TakoContentFormat | null;
-    /** USD price of this item. On search/answer cards this is a prospective /contents quote. */
-    cost?: number;
-    /** Inline payload as text: CSV card data, or a web page's extracted text. */
-    data?: string | null;
-    /** Inline card data as row objects keyed by column name ("json_records"). */
-    records?: Record<string, TakoDatasetCell>[] | null;
-    /** Inline card data as a compact dataset ("json_compact"). */
-    dataset?: TakoDataset | null;
-    /** Presigned download URL ("url" delivery mode). */
-    url?: string | null;
-    expires_at?: string | null;
-    /** True total rows in the card's data, independent of how many were returned. */
-    total_rows?: number | null;
-    truncated?: boolean;
-    export_pricing?: TakoExportPricing | null;
-    manifest?: TakoColumnDescriptor[] | null;
-}
-interface TakoContentItem extends TakoResultContent {
-    /** The originating result URL from the request. */
-    source_url: string;
-}
-interface TakoCardSource {
-    source_name?: string | null;
-    source_description?: string | null;
-    source_index: TakoSourceIndex;
-    url?: string | null;
-    /** Raw excerpts from the source page. Present for web sources; null for data. */
-    source_text?: string | null;
-}
-/** @deprecated Renamed to {@link TakoCardSource}. */
-type TakoKnowledgeCardSource = TakoCardSource;
-/** Both keys are always present on the wire, though either value may be null. */
-interface TakoKnowledgeCardMethodology {
-    methodology_name: string | null;
-    methodology_description: string | null;
-}
-/** Graph node (entity or metric) behind a card. */
-interface TakoCardNode {
-    /** Opaque public id (`ent::…` / `mt::…`). Not durable across graph rebuilds. */
-    id: string;
-    type: TakoGraphNodeType;
-    name: string;
-    description?: string | null;
-}
-interface TakoMetricDefinition {
-    name: string;
-    definition: string;
-}
-/** Freshness dates for a card's data. */
-interface TakoDataFreshness {
-    /** Coverage date of the data. */
-    data_as_of?: string | null;
-    /** Date the data was last refreshed. */
-    last_updated?: 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?: TakoCardSource[] | null;
-    methodologies?: TakoKnowledgeCardMethodology[] | null;
-    source_indexes?: TakoSourceIndex[] | null;
-    card_type?: string | null;
-    relevance?: TakoKnowledgeCardRelevance | null;
-    content?: TakoResultContent | null;
-    /**
-     * Whether /contents can download this card's data. `false` means the export is
-     * unavailable — don't call takoContents on it. `true` is eligible but not
-     * guaranteed (a 403 is still possible), so fall back to the inline preview.
-     */
-    exportable?: boolean;
-    /** Relevance on a 1.0–5.0 scale. Only populated for entitled accounts. */
-    relevance_score?: number | null;
-    /** Graph nodes behind this card. Absent for web-only cards. */
-    nodes?: TakoCardNode[] | null;
-    metric_definitions?: TakoMetricDefinition[] | null;
-    data_freshness?: TakoDataFreshness | null;
-}
-interface TakoWebResult {
-    title: string;
-    url: string;
-    /** Excerpt(s) from the page that matched the query. */
-    snippet?: string | null;
-    source_name?: string | null;
-    publish_date?: string | null;
-    content?: TakoResultContent | null;
-    /** 1-based citation number for inline [N] markers. Null on raw retrieval. */
-    citation_number?: number | null;
+interface TakoAnswerConfig extends TakoBaseConfig, Omit<sdk.AnswerRequest, "query" | "sources"> {
+    sources?: TakoSources;
 }
 /**
- * The raw `POST /api/v3/search` body. Only `request_id` is guaranteed — the
- * contract permits omitting the collections, though the API currently sends them
- * empty. Tools normalize either shape and return {@link TakoSearchResult}.
+ * Config for `takoContents`: the `/v1/contents` request body without `url`.
+ * `mode` and `quote_only` also change the tool description the model reads.
  */
-interface TakoSearchResponse {
-    cards?: TakoCard[];
-    web_results?: TakoWebResult[];
-    request_id: string;
-    usage?: TakoUsage | null;
+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. */
-interface TakoAnswerResponse {
-    answer: string;
-    cards?: TakoCard[];
-    web_results?: TakoWebResult[];
-    request_id: string;
-    usage?: TakoUsage | null;
-}
+type TakoAnswerResponse = sdk.AnswerResponse;
 /** The raw `POST /api/v1/contents` body. */
-interface TakoContentsResponse {
-    contents?: TakoContentItem[];
-    request_id: string;
-    usage?: TakoUsage | null;
-}
-interface TakoSearchResult {
+type TakoContentsResponse = sdk.ContentsResponse;
+type TakoSearchResult = Omit<TakoSearchResponse, "cards" | "web_results"> & {
     cards: TakoCard[];
     web_results: TakoWebResult[];
-    request_id: string;
-    usage?: TakoUsage | null;
-}
-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[];
-    request_id: string;
-    usage?: TakoUsage | null;
-}
-interface TakoContentsResult {
+};
+type TakoContentsResult = Omit<TakoContentsResponse, "contents"> & {
     contents: TakoContentItem[];
-    request_id: string;
-    usage?: TakoUsage | null;
-}
+};
 
 /** Tako fast-pipeline search: returns Tako cards + web results, no LLM synthesis. */
 declare function takoSearch(config?: TakoRetrievalConfig): Tool<{
@@ -370,7 +129,7 @@ declare function takoSearch(config?: TakoRetrievalConfig): Tool<{
  * 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?: TakoRetrievalConfig): Tool<{
+declare function takoAnswer(config?: TakoAnswerConfig): Tool<{
     query: string;
 }, TakoAnswerResult>;
 
@@ -378,13 +137,16 @@ declare function takoAnswer(config?: TakoRetrievalConfig): Tool<{
  * 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"` (default) — a short-lived presigned download url. Use when handing a
+ * - `"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 TakoAnswerResponse, type TakoAnswerResult, type TakoBaseConfig, type TakoCard, type TakoCardNode, type TakoCardSource, type TakoCardSourceIndex, type TakoCardSourceOptions, 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 TakoGeoLocation, type TakoGraphNodeType, type TakoKnowledgeCardMethodology, type TakoKnowledgeCardRelevance, type TakoKnowledgeCardSource, type TakoMetricDefinition, type TakoResultContent, type TakoRetrievalConfig, type TakoSearchEffort, type TakoSearchResponse, type TakoSearchResult, type TakoSourceIndex, type TakoSourceOptions, type TakoUsage, type TakoUsageCompute, type TakoUsageData, type TakoWebCategory, type TakoWebResult, type TakoWebSourceOptions, 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
@@ -40,76 +35,17 @@ function resolveApiKey(config) {
 function resolveBaseUrl(config) {
   return (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 }
-function buildWebSourceSettings(o) {
-  const body = {};
-  if (o.count !== void 0) body.count = o.count;
-  if (o.includeContents !== void 0) body.include_contents = o.includeContents;
-  if (o.category !== void 0) body.category = o.category;
-  if (o.includeDomains !== void 0) body.include_domains = o.includeDomains;
-  if (o.excludeDomains !== void 0) body.exclude_domains = o.excludeDomains;
-  if (o.snippetMaxChars !== void 0) body.snippet_max_chars = o.snippetMaxChars;
-  if (o.articleContentMaxChars !== void 0) {
-    body.article_content_max_chars = o.articleContentMaxChars;
-  }
-  if (o.publishedAfter !== void 0) body.published_after = o.publishedAfter;
-  if (o.publishedBefore !== void 0) body.published_before = o.publishedBefore;
-  return body;
-}
-function assertValidDataSourceOptions(o) {
-  if (o.strict && !o.nodeIds?.length) {
-    throw new Error(
-      "strict requires a non-empty nodeIds. Add node ids from the /v1/graph endpoints, or set strict to false."
-    );
-  }
-}
-function assertValidRetrievalConfig(config) {
-  const dataSource = config.sources?.data ?? config.sources?.tako;
-  if (dataSource) assertValidDataSourceOptions(dataSource);
-}
-function buildDataSourceSettings(o) {
-  assertValidDataSourceOptions(o);
-  const body = {};
-  if (o.count !== void 0) body.count = o.count;
-  if (o.includeContents !== void 0) body.include_contents = o.includeContents;
-  if (o.mode !== void 0) body.mode = o.mode;
-  if (o.contentFormat !== void 0) body.content_format = o.contentFormat;
-  if (o.nodeIds !== void 0) body.node_ids = o.nodeIds;
-  if (o.strict !== void 0) body.strict = o.strict;
-  return body;
-}
-function buildGeoLocation(o) {
-  return { latitude: o.latitude, longitude: o.longitude };
-}
-function buildOutputSettings(o) {
-  const body = {};
-  if (o.imageDarkMode !== void 0) body.image_dark_mode = o.imageDarkMode;
-  if (o.forceRefresh !== void 0) body.force_refresh = o.forceRefresh;
-  return body;
-}
 function buildSearchRequestBody(config, query) {
-  const body = { query };
-  if (config.effort !== void 0) body.effort = config.effort;
-  if (config.countryCode !== void 0) body.country_code = config.countryCode;
-  if (config.locale !== void 0) body.locale = config.locale;
-  if (config.sources) {
-    const sources = {};
-    const dataSource = config.sources.data ?? config.sources.tako;
-    if (dataSource) sources.data = buildDataSourceSettings(dataSource);
-    if (config.sources.web) sources.web = buildWebSourceSettings(config.sources.web);
-    body.sources = sources;
-  }
-  if (config.location !== void 0) body.location = buildGeoLocation(config.location);
-  if (config.timezone !== void 0) body.timezone = config.timezone;
-  if (config.outputSettings) body.output_settings = buildOutputSettings(config.outputSettings);
-  return body;
+  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 body = { url, mode: config.mode ?? "url" };
-  if (config.contentFormat !== void 0) body.content_format = config.contentFormat;
-  if (config.maxRows !== void 0) body.max_rows = config.maxRows;
-  if (config.maxChars !== void 0) body.max_chars = config.maxChars;
-  if (config.quoteOnly !== void 0) body.quote_only = config.quoteOnly;
-  return body;
+  const { apiKey: _apiKey, baseUrl: _baseUrl, ...request } = config;
+  return { ...request, url };
 }
 function normalizeSearchResult(response) {
   return {
@@ -129,9 +65,29 @@ 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.");
+  }
+  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);
+  }
+}
+
 // src/tools/search.ts
 function takoSearch(config = {}) {
-  assertValidRetrievalConfig(config);
+  const client = lazyTakoClient(config);
   return tool({
     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.
 
@@ -145,15 +101,12 @@ Cards carry captions and charts, not full data. For the numbers behind one, pass
     inputSchema: z.object({
       query: z.string().min(1).max(500).describe("Natural-language description of what you're looking for")
     }),
-    execute: async ({ query }) => normalizeSearchResult(
-      await 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)))
+      );
+    }
   });
 }
 
@@ -161,21 +114,25 @@ Cards carry captions and charts, not full data. For the numbers behind one, pass
 import { tool as tool2 } from "ai";
 import { z as z2 } from "zod";
 function takoAnswer(config = {}) {
-  assertValidRetrievalConfig(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 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".',
+    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 }) => normalizeAnswerResult(
-      await 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)))
+      );
+    }
   });
 }
 
@@ -183,27 +140,24 @@ function takoAnswer(config = {}) {
 import { tool as tool3 } from "ai";
 import { z as z3 } from "zod";
 function takoContents(config = {}) {
-  const mode = config.mode ?? "url";
+  const client = lazyTakoClient(config);
   return tool3({
-    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" + // `quoteOnly` outranks `mode`: the API ignores mode on a quote and returns
+    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.quoteOnly ? "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" : mode === "inline" ? "Returns the content in the response body \u2014 read and compute over the numbers directly.\n\n" : "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") + "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.",
+    (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({
       // 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 }) => normalizeContentsResult(
-      await callTako({
-        baseUrl: resolveBaseUrl(config),
-        path: "/api/v1/contents",
-        apiKey: resolveApiKey(config),
-        body: buildContentsRequestBody(url, config),
-        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": "3.0.0",
+  "version": "4.0.0",
   "description": "Tako knowledge search, answer, and contents tools for the Vercel AI SDK",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,24 +42,25 @@
   "devDependencies": {
     "@ai-sdk/openai": "^4.0.0",
     "@types/node": "^24.10.1",
+    "@types/semver": "^7.8.0",
     "ai": "^7.0.0",
-    "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1",
-    "tako-sdk": "^1.1.10",
+    "semver": "^7.8.5",
     "tsup": "^8.5.0",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
-    "vitest": "^3.0.0",
-    "yaml": "^2.9.0"
+    "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:contract": "vitest run tests/contract",
+    "test:live": "vitest run --config vitest.live.config.ts",
     "test:package": "node scripts/verify-package.mjs",
-    "lint:package": "npx -y publint@latest --strict --pack npm && npx -y @arethetypeswrong/cli@latest --pack . --ignore-rules cjs-resolves-to-esm",
-    "spec:refresh": "curl -fsSL https://docs.tako.com/api-reference/openapi.yaml -o tests/contract/openapi.yaml"
+    "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"
   }
 }