ak-gemini 2.4.1 → 2.6.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+## 2.6.0
+
+> **Upgrading from 2.5.0?** [UPGRADING.md](./UPGRADING.md) walks through only what you
+> need to change, with before/after examples.
+
+Feature request from a downstream consumer (`smarterchild/agent`, Vertex AI),
+paired with ak-claude 0.2.0. **Minor** bump — cached-token billing changes
+reported cost (see "Behavior changes" below).
+
+### Behavior changes (read before upgrading)
+- **Cached tokens are now billed at the discounted cached rate.**
+  `usageMetadata.cachedContentTokenCount` is surfaced as `usage.cachedTokens` and
+  factored into `estimatedCost`. **Gemini INCLUDES cached tokens in
+  `promptTokenCount`**, so they are *subtracted* from the prompt count and
+  re-billed at `cachedInput` — they are a subset, not an addition. (ak-claude is
+  the opposite: Anthropic excludes cache tokens from `input_tokens` and they are
+  added on top. The asymmetry is intentional; do not "unify" it.) Reported cost
+  for cache-heavy calls drops by up to ~10×. Models with no published cached rate
+  bill cached tokens at the full input rate — an overestimate, never an
+  underestimate.
+- **Pro models switch to their >200k-context tier above 200,000 prompt tokens.**
+  `gemini-2.5-pro` and `gemini-3.1-pro-preview` previously billed every call at
+  the ≤200k rate. Long-context calls now report roughly 2× the input cost they
+  did before, which is what Google actually charges.
+- **`gemini-2.5-flash` output pricing corrected from $2.50 to $3.00 per M.**
+  Reported cost for that model rises accordingly.
+- **`gemini-flash-latest` now resolves to `gemini-3.6-flash`** (was
+  `gemini-3.5-flash`) and **`gemini-flash-lite-latest` to `gemini-3.5-flash-lite`**
+  for pricing. Alias resolution is logged at debug — prefer the model id the API
+  echoes in `modelVersion`, which `_estimatedCost` already does.
+- **`getLastUsage()` now reports non-zero `thoughtsTokens` on `Chat`,
+  `ToolAgent`, `CodeAgent`, `RagAgent`, and `Transformer`.** These classes seeded
+  `_cumulativeUsage` without the thinking-token count, so `getLastUsage()`
+  reported `0` (and undercounted cost) even when the response carried thoughts.
+  `result.usage` was already correct.
+
+### Added
+- **`effort: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'`** on every
+  class — the cross-package option name (identical to ak-claude). Maps to
+  `thinkingConfig.thinkingLevel` and wins over an explicit `thinkingLevel` /
+  `thinkingBudget` (the two are mutually exclusive on the wire). `xhigh` and
+  `max` are ak-claude-only levels and clamp to `high`. An unrecognized level
+  throws at construction.
+- **`usage.cachedTokens`** on every `send()`/`chat()`/`generate()` result and on
+  `getLastUsage()`.
+- **Pricing for new models:** `gemini-3.6-flash` ($1.50/$7.50, cached $0.15) and
+  `gemini-3.5-flash-lite` ($0.30/$2.50, cached $0.03).
+- **`cachedInput` rates** on every model where Google publishes one, plus
+  `inputAbove200k` / `outputAbove200k` / `cachedInputAbove200k` on the tiered Pro
+  models.
+- **New exports:** `MODEL_PRICING_AS_OF` (the date the table was last verified
+  against Google's pricing page) and `EFFORT_LEVELS`. `resolvePricing()` now
+  returns `asOf` and `tierThreshold`.
+- `computeCost()` takes two new optional trailing args:
+  `computeCost(modelId, prompt, response, thoughtsTokens?, cachedTokens?)`.
+
+### Notes
+- `null` from `resolvePricing()` / `usage.estimatedCost` means the model's
+  pricing is **unknown** — it does not mean the call was free.
+- Cache **storage** ($1.00/1M tokens/hour on Flash tiers, $4.50 on Pro) is
+  time-based and is **not** modelled by `estimatedCost` — only per-token charges
+  are.
+- Image-output tokens on Nano Banana models ($60/M or $120/M) are still not
+  modelled.
+
+## 2.5.0
+
+Fixes from a downstream consumer's adversarial review. This is a **minor** bump —
+it includes small but real behavior changes (see "Behavior changes" below).
+
+### Behavior changes (read before upgrading)
+- **`Message` structured output:** passing `responseSchema` without
+  `responseMimeType` now auto-defaults `responseMimeType: 'application/json'`
+  (the SDK requires it and does not add it). Previously such a call returned a
+  400 or unparseable prose. Explicit `responseMimeType` is still honored.
+- **`init()` no longer validates connectivity by default.** `Message`,
+  `Embedding`, and `ImageGenerator` previously called `models.list()`
+  unconditionally during `init()`. This is now gated behind `healthCheck: true`
+  (default `false`), matching `BaseGemini`. If you relied on `init()` as a
+  startup credentials gate, pass `healthCheck: true`. `models.list()` is a
+  different IAM surface than `generateContent` and added a per-instance
+  round-trip.
+
+### Added
+- **`usage.estimatedCost`** — every `send()`/`generate()` result and
+  `getLastUsage()` now include an estimated USD cost from `MODEL_PRICING`
+  (`null` when the model is unpriced). Thinking ("thoughts") tokens are billed at
+  the output rate and are now included in cost and exposed as
+  `usage.thoughtsTokens`.
+- **Concurrency-safe per-call usage.** `Message.send()` and
+  `ImageGenerator.generate()` return `result.usage` computed synchronously from
+  that call's own response. `getLastUsage()` still reflects the instance's last
+  call and is unsafe to read across concurrent sends on a shared instance — use
+  `result.usage`.
+- **Pricing helpers exported:** `MODEL_PRICING`, `MODEL_ALIASES`,
+  `resolvePricing()`, `computeCost()`. `resolvePricing` follows `-latest`
+  aliases and peels version-build suffixes (e.g. `gemini-2.5-flash-001` →
+  `gemini-2.5-flash`).
+- **`validateSchema()`** JSON-Schema validator exported (for cross-package
+  symmetry; Gemini enforces schemas natively).
+
+### Fixed
+- `estimateCost()` now uses `resolvePricing()` and returns `null` cost fields for
+  unknown models (was `0`), consistent with `usage.estimatedCost`.
+- `estimatedCost` no longer returns `null` for a priced model when the API echoes
+  a version-suffixed build id in `modelVersion`.
+
+### Dependencies
+- `@google/genai` `^2.10.0` → `^2.12.0` (no breaking changes to the used surface).

package/GUIDE.md

@@ -147,6 +147,8 @@ console.log(result.data);
 
 Key difference from `Chat`: `result.data` contains the parsed JSON object. `result.text` contains the raw string.
 
+> **Note:** `responseSchema` requires `responseMimeType: 'application/json'`. If you pass `responseSchema` without a `responseMimeType`, ak-gemini now auto-defaults it to `'application/json'` (logged at debug). Passing an explicit `responseMimeType` is still honored.
+
 ### When to Use Message
 
 - Classification, tagging, or labeling
@@ -1037,10 +1039,18 @@ const usage = instance.getLastUsage();
 //   attempts: 1,             // 1 = first try, 2+ = retries needed
 //   modelVersion: 'gemini-2.5-flash-001',  // actual model that responded
 //   requestedModel: 'gemini-2.5-flash',    // model you requested
-//   timestamp: 1710000000000
+//   timestamp: 1710000000000,
+//   thoughtsTokens: 0,       // thinking tokens, billed at output rate (in totalTokens + cost)
+//   estimatedCost: 0.00123   // USD from MODEL_PRICING; null if model unpriced
 // }
 ```
 
+> **Thinking tokens:** for thinking-enabled models, `thoughtsTokens` are billed at the output rate and are included in both `totalTokens` and `estimatedCost`. `responseTokens` is candidate (visible) output only.
+
+> **Concurrency:** `getLastUsage()` reflects the **instance's last completed call** and mutates on every `send()` — it is **not** safe to read across concurrent sends on a shared instance. The **stateless** classes (`Message`, `ImageGenerator`) return a per-call **`result.usage`** computed synchronously from that call's own response, which *is* concurrency-safe — use it when sharing one instance across concurrent calls. The stateful classes (`Chat`, `Transformer`, `RagAgent`, `ToolAgent`, `CodeAgent`) maintain history/rounds and are not designed to be shared across concurrent calls; their `result.usage` is derived from instance state.
+
+> **`estimatedCost` / `MODEL_ALIASES` caveat:** `estimatedCost` resolves `-latest` aliases and version-suffixed builds via `MODEL_PRICING`/`MODEL_ALIASES`. Alias→price mappings are pinned as of 2026-07 (e.g. `gemini-flash-latest` → `gemini-3.5-flash`); when Google rotates what a `-latest` alias points to, `estimatedCost` for that alias may be wrong until the table is updated. Pin explicit model ids for billing-grade accuracy.
+
 ### Cost Estimation
 
 Estimate cost *before* sending:

package/README.md

@@ -86,8 +86,15 @@ const msg = new Message({
 
 const result = await msg.send('Alice works at Acme in New York.');
 // result.data → { entities: ['Alice', 'Acme', 'New York'] }
+// result.usage → { promptTokens, responseTokens, thoughtsTokens, totalTokens, estimatedCost, ... }
 ```
 
+> **`responseSchema` requires `responseMimeType: 'application/json'`.** As of 2.5.0, passing `responseSchema` without a `responseMimeType` auto-defaults it to `'application/json'` — you can omit the line above. An explicit `responseMimeType` is still honored.
+
+> **Connectivity check is opt-in.** `Message`, `Embedding`, and `ImageGenerator` do **not** ping the API during `init()` unless you pass `healthCheck: true` (default `false`, as of 2.5.0). The first `send()`/`embed()`/`generate()` surfaces auth/connectivity errors on its own.
+
+> **Per-call usage under concurrency.** Read `result.usage` (computed from that call's own response) rather than `getLastUsage()` when sharing a `Message`/`ImageGenerator` instance across concurrent `send()`s — `getLastUsage()` reflects only the instance's last completed call.
+
 ### ToolAgent — Agent with User-Provided Tools
 
 Provide tool declarations and an executor function. The agent manages the tool-use loop automatically.
@@ -278,9 +285,29 @@ const cost = await instance.estimateCost({ some: 'payload' });
 
 ```javascript
 const usage = instance.getLastUsage();
-// { promptTokens, responseTokens, totalTokens, attempts, modelVersion, requestedModel, timestamp }
+// { promptTokens, responseTokens, thoughtsTokens, cachedTokens, totalTokens,
+//   attempts, modelVersion, requestedModel, timestamp, estimatedCost }
 ```
 
+`estimatedCost` is USD from `MODEL_PRICING`. **`null` means the model's pricing is
+unknown — not that the call was free.**
+
+**`cachedTokens` is a subset of `promptTokens`, not an addition.** Gemini includes
+`cachedContentTokenCount` inside `promptTokenCount`, so `computeCost()` subtracts
+them and re-bills at the discounted `cachedInput` rate. (`ak-claude` is the
+opposite — Anthropic excludes cache tokens from `input_tokens` and they are added
+on top.) Models with no published cached rate bill cached tokens at the full input
+rate: an overestimate, never an underestimate.
+
+Two things are deliberately **not** modelled: cache **storage** (time-based,
+$1.00/1M tokens/hour on Flash tiers and $4.50 on Pro) and image-output tokens on
+the Nano Banana models ($60/M or $120/M).
+
+Pro models are tiered — `gemini-2.5-pro` and `gemini-3.1-pro-preview` switch to a
+higher rate above 200,000 prompt tokens. `resolvePricing()` returns `tierThreshold`
+and `asOf` (the date the table was last verified against Google's pricing page,
+also exported as `MODEL_PRICING_AS_OF`).
+
 ### Few-Shot Seeding
 
 ```javascript
@@ -291,13 +318,30 @@ await instance.seed([
 
 ### Thinking Configuration
 
+Use `effort` — it is the same option name in `ak-claude`, so one config object
+works against both packages:
+
 ```javascript
 new Chat({
-  modelName: 'gemini-2.5-flash',
-  thinkingConfig: { thinkingBudget: 1024 }
+  modelName: 'gemini-3.5-flash',
+  effort: 'high'          // 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
 });
+// wire: thinkingConfig: { thinkingLevel: 'high' }
 ```
 
+`xhigh` and `max` are ak-claude-only levels and clamp to `high` here. An
+unrecognized level throws at construction.
+
+The raw SDK shape still works:
+
+```javascript
+new Chat({ modelName: 'gemini-2.5-flash', thinkingConfig: { thinkingBudget: 1024 } });
+```
+
+`thinkingLevel` and `thinkingBudget` are mutually exclusive on the wire — when
+`effort` is set (or you pass `thinkingLevel` yourself), `thinkingBudget` is
+dropped. `effort` wins over both.
+
 ### Google Search Grounding
 
 Ground responses in real-time web search results. Available on all classes.
@@ -383,7 +427,8 @@ All classes accept `BaseGeminiOptions`:
 | `project` | string | env var | GCP project ID |
 | `location` | string | `'global'` | GCP region |
 | `chatConfig` | object | — | Gemini chat config overrides |
-| `thinkingConfig` | object | — | Thinking features config |
+| `thinkingConfig` | object | — | Thinking features config (`thinkingBudget` or `thinkingLevel`) |
+| `effort` | string | — | `'minimal'`\|`'low'`\|`'medium'`\|`'high'`\|`'xhigh'`\|`'max'`. Maps to `thinkingConfig.thinkingLevel`; wins over it |
 | `maxOutputTokens` | number | `50000` | Max tokens in response (`null` removes limit) |
 | `logLevel` | string | based on NODE_ENV | `'trace'`\|`'debug'`\|`'info'`\|`'warn'`\|`'error'`\|`'none'` |
 | `labels` | object | — | Billing labels (Vertex AI) |
@@ -471,6 +516,13 @@ All tests use real Gemini API calls (no mocks). Rate limiting (429 errors) can c
 
 ---
 
+## Upgrading
+
+**Upgrading from 2.5.0 to 2.6.0?** See [UPGRADING.md](./UPGRADING.md). 2.6.0 adds the
+`effort` option and corrects cost reporting — cached tokens now bill at the discounted
+rate, Pro models are tiered above 200k, and `thoughtsTokens` is no longer dropped from
+`getLastUsage()`. Full detail in [CHANGELOG.md](./CHANGELOG.md).
+
 ## Migration from v1.x
 
 See [MIGRATION.md](./MIGRATION.md) for a detailed guide on upgrading from v1.x to v2.0.

package/UPGRADING.md

@@ -0,0 +1,111 @@
+# Upgrading ak-gemini
+
+Per-version upgrade notes. For the full list of changes see [CHANGELOG.md](./CHANGELOG.md). For the v1.x → v2.0 rewrite, see [MIGRATION.md](./MIGRATION.md).
+
+---
+
+## 2.5.0 → 2.6.0
+
+**Minor bump. No API surface is removed and no call signature breaks.** What changes is what `estimatedCost` reports — in most cases it goes *down*, because cached tokens and context tiers are now modelled correctly.
+
+Companion release to **ak-claude 0.2.0**; the two packages keep matching option names.
+
+### At a glance
+
+| If you… | Then… |
+|---|---|
+| don't use context caching and stay under 200k tokens | numbers are unchanged, except `gemini-2.5-flash` — see #3 |
+| use context caching (`cachedContent` / `useCache()`) | your reported cost drops — cached tokens now bill at the discounted rate, see #1 |
+| send >200k-token prompts to a Pro model | your reported cost rises to the correct tier rate — see #2 |
+| use `gemini-2.5-flash` | output rate corrected $2.50 → $3.00 per M — see #3 |
+| use `gemini-flash-latest` or `gemini-flash-lite-latest` | these aliases now resolve to newer models — see #4 |
+| read `getLastUsage()` on Chat / ToolAgent / CodeAgent / RagAgent / Transformer | `thoughtsTokens` is now non-zero when thinking ran — see #5 |
+| want to control reasoning depth | new `effort` option — see #6 |
+
+---
+
+### 1. Cached tokens are billed at the cached rate
+
+**This is the change most likely to move your numbers.**
+
+Gemini's `promptTokenCount` **includes** `cachedContentTokenCount`. Before 2.6.0, ak-gemini billed the whole prompt count at the full input rate, so cached tokens were charged as if they were fresh — a large overestimate on cache-heavy workloads.
+
+`computeCost()` now subtracts cached tokens from the prompt count and re-bills them at `cachedInput` (roughly a 10× discount):
+
+```js
+// promptTokens: 10_000, of which cachedTokens: 8_000, on gemini-3.5-flash
+// 2.5.0:  10_000 × $1.50/M                        = $0.0150
+// 2.6.0:   2_000 × $1.50/M + 8_000 × $0.15/M      = $0.0042
+```
+
+`usage.cachedTokens` is now exposed on both `getLastUsage()` and per-call `result.usage`.
+
+> **`cachedTokens` is a SUBSET of `promptTokens`, not an addition.** Do not sum them. This is the opposite of **ak-claude**, where Anthropic *excludes* cache tokens from `input_tokens` and they are added on top. If you have code that normalizes usage across both packages, this asymmetry is the thing to get right.
+
+Models with no published `cachedInput` rate fall back to the full input rate — an overestimate, never an underestimate.
+
+**Still not modelled:** cache *storage*, which is time-based ($1.00 per 1M tokens per hour on Flash tiers, $4.50 on Pro). `estimatedCost` covers per-token charges only.
+
+### 2. Context-tier pricing above 200k tokens
+
+Pro models switch to a higher rate above 200,000 prompt tokens. Previously ak-gemini always billed the ≤200k tier, understating cost on long-context calls.
+
+```js
+resolvePricing('gemini-2.5-pro')
+// { input: 1.25, output: 10.00, cachedInput: 0.125,
+//   inputAbove200k: 2.50, outputAbove200k: 15.00, cachedInputAbove200k: 0.25,
+//   tierThreshold: 200000, asOf: '2026-07-28' }
+```
+
+`computeCost()` picks the tier from `promptTokens` automatically. Populated for `gemini-2.5-pro` and `gemini-3.1-pro-preview`.
+
+### 3. `gemini-2.5-flash` output rate corrected
+
+$2.50 → **$3.00** per M output tokens. The old value was wrong against Google's published pricing. If you track cost over time, expect a step change here.
+
+### 4. Alias repointing
+
+| Alias | 2.5.0 resolved to | 2.6.0 resolves to |
+|---|---|---|
+| `gemini-flash-latest` | `gemini-3.5-flash` | `gemini-3.6-flash` |
+| `gemini-flash-lite-latest` | `gemini-3.1-flash-lite` | `gemini-3.5-flash-lite` |
+
+Aliases are a pricing-table convenience and go stale whenever Google rotates what they point at. ak-gemini already prefers the model id the API **echoes** (`response.modelVersion`) over the alias you requested, and now logs each alias resolution at debug level. Pin a concrete model id if you need cost reporting you can audit.
+
+New pricing entries: `gemini-3.6-flash` ($1.50 / $7.50) and `gemini-3.5-flash-lite` ($0.30 / $2.50).
+
+### 5. `thoughtsTokens` now appears in `getLastUsage()`
+
+`Chat`, `ToolAgent`, `CodeAgent`, `RagAgent`, and `Transformer` seeded their cumulative usage without `thoughtsTokens`, so `getLastUsage()` reported `0` and **omitted thinking tokens from `estimatedCost`** even when the response carried them. Per-call `result.usage` was already correct.
+
+If you read cost from `getLastUsage()` on a thinking-enabled model, your reported cost will rise — it was under-reporting before. Thinking tokens bill at the output rate.
+
+### 6. New `effort` option
+
+The cross-package reasoning-depth knob — same option name in ak-claude.
+
+```js
+new Chat({ modelName: 'gemini-3.5-flash', effort: 'high' })
+// → thinkingConfig: { thinkingLevel: 'high' }
+```
+
+Accepts `'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'`. Gemini's wire field only goes up to `high`, so **`xhigh` and `max` clamp to `high`** — they exist so the same config object works against both packages. An unrecognized value **throws at construction**.
+
+`effort` wins over an explicit `thinkingLevel` or `thinkingBudget`; `thinkingLevel` and `thinkingBudget` are mutually exclusive on the wire, so setting `effort` deletes any budget. `thinkingConfig: null` still disables thinking outright and takes precedence over `effort`.
+
+`thinkingConfig: { thinkingBudget: N }` continues to work unchanged.
+
+### New exports
+
+```js
+import {
+  MODEL_PRICING_AS_OF,   // date the pricing table was last verified
+  EFFORT_LEVELS,         // ['minimal','low','medium','high','xhigh','max']
+  resolvePricing,        // now returns `tierThreshold` and `asOf`
+  computeCost            // now takes (model, prompt, response, thoughts?, cached?)
+} from 'ak-gemini';
+```
+
+`computeCost()`'s new `cachedTokens` argument is optional and trailing — existing 3- and 4-argument calls behave as before, except for the tier selection in #2.
+
+> **A `null` from `resolvePricing()` or `estimatedCost` means UNKNOWN, not free.** Unpriced models (Gemma, anything not in the table) return `null`. Don't coerce it to `0` in a cost rollup.