@takoviz/ai-sdk 2.0.1 → 3.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),
@@ -63,7 +63,7 @@ takoSearch({
   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 },
+    data: { count: 5, includeContents: false }, // legacy alias: tako
     web: { count: 5, includeContents: false },
   },
   countryCode: 'US',           // default 'US'
@@ -88,6 +88,55 @@ takoContents({
 
 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.
+
+| 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. |
+
+**`sources.web`**:
+
+| 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 options
+
+| 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. |
+
+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.
+
+**`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.
+
 ## Responses
 
 `takoSearch` resolves to:
@@ -96,12 +145,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.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.
+
+`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.
 
@@ -115,17 +192,25 @@ import type {
   TakoAnswerResult,
   TakoContentsResult,
   TakoCard,
+  TakoCardSource,
   TakoWebResult,
   TakoContentItem,
+  TakoDataset,
+  TakoUsage,
 } 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.
+
+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 2.x](./MIGRATING.md)
 - [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

@@ -2,10 +2,21 @@ import { Tool } from 'ai';
 
 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";
+/** Serialization of tabular (Tako card) data. Web text carries no format. */
+type TakoContentFormat = "csv" | "json_records" | "json_compact";
+/** 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";
+/** Web result category. Only "news" filters today; the others are accepted and inert. */
+type TakoWebCategory = "news" | "sports" | "finance";
 interface TakoBaseConfig {
     /** Tako API key. Falls back to TAKO_API_KEY / TAKO_API_TOKEN env vars. */
     apiKey?: string;
@@ -13,23 +24,86 @@ interface TakoBaseConfig {
     baseUrl?: string;
 }
 interface TakoSourceOptions {
-    /** Max results for this source, 1–20 (server default 5). */
+    /**
+     * 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;
 }
-interface TakoCardSourceOptions extends TakoSourceOptions {
-    /** Defer data retrieval (faster, less detail). Mutually exclusive with includeContents. */
-    deferDataRetrieval?: 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 tako + web. */
+    /** Per-source settings. A source is searched iff its key is present. Omit to search data + web. */
     sources?: {
-        tako?: TakoCardSourceOptions;
-        web?: TakoSourceOptions;
+        /** 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". */
@@ -45,35 +119,162 @@ interface TakoRetrievalConfig extends TakoBaseConfig {
 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 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.
+ */
+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";
+}
+/**
+ * Rate card for a card export, so cost can be computed before fetching:
+ * `baseline_usd + row_cpm_usd * max(0, rows - free_rows) / 1000`.
+ */
+interface TakoExportPricing {
+    baseline_usd: number;
+    row_cpm_usd: number;
+    free_rows: number;
+    max_rows_ceiling: number;
+}
+/** 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;
+}
+/**
+ * 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.
+ *
+ * `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`.
+ */
 interface TakoResultContent {
-    format: TakoContentFormat;
-    cost: number;
+    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 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;
+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;
@@ -82,32 +283,66 @@ interface TakoCard {
     webpage_url?: string | null;
     image_url?: string | null;
     embed_url?: string | null;
-    sources?: TakoKnowledgeCardSource[] | null;
+    sources?: TakoCardSource[] | null;
     methodologies?: TakoKnowledgeCardMethodology[] | null;
-    source_indexes?: (TakoCardSourceIndex | TakoCardSourceIndexSegment)[] | 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 TakoContentItem extends TakoResultContent {
-    source_url: string;
-    url?: string | null;
-    expires_at?: string | null;
+/**
+ * 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}.
+ */
+interface TakoSearchResponse {
+    cards?: TakoCard[];
+    web_results?: TakoWebResult[];
+    request_id: string;
+    usage?: TakoUsage | null;
+}
+/** The raw `POST /api/v1/answer` body. */
+interface TakoAnswerResponse {
+    answer: string;
+    cards?: TakoCard[];
+    web_results?: TakoWebResult[];
+    request_id: string;
+    usage?: TakoUsage | null;
+}
+/** The raw `POST /api/v1/contents` body. */
+interface TakoContentsResponse {
+    contents?: TakoContentItem[];
+    request_id: string;
+    usage?: TakoUsage | null;
 }
 interface TakoSearchResult {
     cards: TakoCard[];
     web_results: TakoWebResult[];
-    contents_total_cost: number;
     request_id: string;
+    usage?: TakoUsage | null;
 }
 interface TakoAnswerResult {
     /** Synthesized text answer. */
@@ -115,12 +350,13 @@ interface TakoAnswerResult {
     /** Backing cards; cards[0] is the lead card. */
     cards: TakoCard[];
     web_results: TakoWebResult[];
-    contents_total_cost: number;
     request_id: string;
+    usage?: TakoUsage | null;
 }
 interface TakoContentsResult {
     contents: TakoContentItem[];
     request_id: string;
+    usage?: TakoUsage | null;
 }
 
 /** Tako fast-pipeline search: returns Tako cards + web results, no LLM synthesis. */
@@ -128,14 +364,27 @@ declare function takoSearch(config?: TakoRetrievalConfig): Tool<{
     query: string;
 }, TakoSearchResult>;
 
-/** Tako answer: fast-pipeline retrieval plus an LLM-synthesized answer grounded in the results. */
+/**
+ * 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?: TakoRetrievalConfig): 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"` (default) — 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.
+ */
 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 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 };

package/dist/index.js

@@ -40,54 +40,120 @@ 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,
-    effort: config.effort ?? "fast",
-    country_code: config.countryCode ?? "US",
-    locale: config.locale ?? "en-US"
-  };
+  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 = {};
-    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;
-    }
+    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) {
-    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;
-  }
+  if (config.outputSettings) body.output_settings = buildOutputSettings(config.outputSettings);
   return body;
 }
+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;
+}
+function normalizeSearchResult(response) {
+  return {
+    ...response,
+    cards: response.cards ?? [],
+    web_results: response.web_results ?? []
+  };
+}
+function normalizeAnswerResult(response) {
+  return {
+    ...response,
+    cards: response.cards ?? [],
+    web_results: response.web_results ?? []
+  };
+}
+function normalizeContentsResult(response) {
+  return { ...response, contents: response.contents ?? [] };
+}
 
 // src/tools/search.ts
 function takoSearch(config = {}) {
+  assertValidRetrievalConfig(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 }) => normalizeSearchResult(
+      await callTako({
+        baseUrl: resolveBaseUrl(config),
+        path: "/api/v3/search",
+        apiKey: resolveApiKey(config),
+        body: buildSearchRequestBody(config, query),
+        operation: "search"
+      })
+    )
   });
 }
 
@@ -95,18 +161,21 @@ function takoSearch(config = {}) {
 import { tool as tool2 } from "ai";
 import { z as z2 } from "zod";
 function takoAnswer(config = {}) {
+  assertValidRetrievalConfig(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".',
     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 }) => normalizeAnswerResult(
+      await callTako({
+        baseUrl: resolveBaseUrl(config),
+        path: "/api/v1/answer",
+        apiKey: resolveApiKey(config),
+        body: buildSearchRequestBody(config, query),
+        operation: "answer"
+      })
+    )
   });
 }
 
@@ -114,18 +183,27 @@ function takoAnswer(config = {}) {
 import { tool as tool3 } from "ai";
 import { z as z3 } from "zod";
 function takoContents(config = {}) {
+  const mode = config.mode ?? "url";
   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" + // `quoteOnly` 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.",
     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 }) => normalizeContentsResult(
+      await callTako({
+        baseUrl: resolveBaseUrl(config),
+        path: "/api/v1/contents",
+        apiKey: resolveApiKey(config),
+        body: buildContentsRequestBody(url, config),
+        operation: "fetch contents"
+      })
+    )
   });
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takoviz/ai-sdk",
-  "version": "2.0.1",
+  "version": "3.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"
   ],
@@ -42,15 +43,23 @@
     "@ai-sdk/openai": "^4.0.0",
     "@types/node": "^24.10.1",
     "ai": "^7.0.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "tako-sdk": "^1.1.10",
     "tsup": "^8.5.0",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "yaml": "^2.9.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:contract": "vitest run tests/contract",
+    "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"
   }
 }