@qmediat.io/gemini-code-context-mcp 1.3.2 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +50 -0
- package/README.md +14 -0
- package/dist/config.d.ts +12 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +15 -1
- package/dist/config.js.map +1 -1
- package/dist/gemini/model-taxonomy.d.ts +94 -0
- package/dist/gemini/model-taxonomy.d.ts.map +1 -0
- package/dist/gemini/model-taxonomy.js +176 -0
- package/dist/gemini/model-taxonomy.js.map +1 -0
- package/dist/gemini/models.d.ts +68 -10
- package/dist/gemini/models.d.ts.map +1 -1
- package/dist/gemini/models.js +137 -71
- package/dist/gemini/models.js.map +1 -1
- package/dist/tools/ask.tool.d.ts +5 -0
- package/dist/tools/ask.tool.d.ts.map +1 -1
- package/dist/tools/ask.tool.js +94 -33
- package/dist/tools/ask.tool.js.map +1 -1
- package/dist/tools/code.tool.d.ts +5 -0
- package/dist/tools/code.tool.d.ts.map +1 -1
- package/dist/tools/code.tool.js +60 -17
- package/dist/tools/code.tool.js.map +1 -1
- package/dist/types.d.ts +13 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [1.4.0] — 2026-04-20
|
|
11
|
+
|
|
12
|
+
**Model taxonomy — allowlist-first category system.** The v1.2.0–v1.3.2 defence against `nano-banana-pro-preview` (image-gen) resolving to `latest-pro-thinking` was a reactive substring blocklist (`NON_TEXT_GEN_MARKERS = ['banana', 'lyria', 'research', ...]`). Every new non-text-gen family Google shipped under a `pro` / `flash` token required a patch release. v1.4.0 flips the model: each model ID is matched against an explicit rule set that assigns one of nine functional categories (`text-reasoning`, `text-fast`, `text-lite`, `image-generation`, `audio-generation`, `video-generation`, `embedding`, `agent`, `unknown`). Tools declare a required category; the resolver refuses to dispatch outside that set. Unknown families land in `unknown` and are excluded from every alias until the taxonomy is extended — forcing a conscious patch release rather than silent admission.
|
|
13
|
+
|
|
14
|
+
**Why this is a minor bump (1.4.0 not 1.3.3)**: the `ResolvedModel` type exported from `src/types.ts` gains two required fields (`category`, `capabilities`). Internal consumers compile cleanly; external TS consumers (none documented) would see the addition as type-surface widening. Runtime behaviour is strictly safer — existing aliases work identically for legitimate use, and the only callers that see new behaviour are those passing an image-gen / audio-gen model ID where a text-gen model was expected (pre-v1.4.0 silently dispatched; now throws `ModelCategoryMismatchError` with an actionable message).
|
|
15
|
+
|
|
16
|
+
### Breaking
|
|
17
|
+
|
|
18
|
+
Fail-fast resolver replaces v1.3.x's silent cross-category fallback. Three scenarios that previously produced (possibly mis-routed) calls now throw a clear error:
|
|
19
|
+
|
|
20
|
+
1. **Literal model ID not in registry** — pre-v1.4.0: silent swap to `latest-pro`. v1.4.0: `Model 'X' is not available for this API key. Pass an alias (…) or a literal ID available on your tier.`
|
|
21
|
+
2. **Alias has no model in its required category** — pre-v1.4.0: cascade `latest-pro-thinking` → `latest-pro` → `latest-flash` → `latest-lite` → first model. v1.4.0: `Alias 'X' could not be resolved — no model in category [...] is available for this API key.`
|
|
22
|
+
3. **Literal model ID in the wrong category for the tool** — pre-v1.4.0: dispatched anyway (e.g. `code({ model: 'nano-banana-pro-preview' })` silently hit an image-gen model at ~10× text pricing). v1.4.0: `ModelCategoryMismatchError: Model 'X' is in category 'image-generation', but this tool requires: text-reasoning.`
|
|
23
|
+
|
|
24
|
+
Callers on non-default tiers where the required-category list was empty were the ones most likely to hit scenario 2 silently pre-v1.4.0. If your workflow depended on the implicit cross-category fall-through, pass an explicit model ID in the correct category or upgrade your Gemini tier (https://aistudio.google.com/apikey).
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
|
|
28
|
+
- **Output-cap three-layer precedence** (replaces the v1.3.x hard-coded self-caps `ASK_MAX_OUTPUT_TOKENS_DEFAULT=8192` / `CODE_MAX_OUTPUT_TOKENS_DEFAULT=32768` that artificially limited responses below the model's advertised capacity):
|
|
29
|
+
- **Default (auto)** — `maxOutputTokens` omitted from the `generateContent` wire. Gemini uses its model-default cap which per [Google docs](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-pro) equals the model's `outputTokenLimit` (65,536 for Gemini 3.x / 2.5 Pro). Short Q&A doesn't reserve full capacity; long responses get full 65k.
|
|
30
|
+
- **MCP-host env override** — `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT=true` pins every call at model's full capacity. Primary use case: code-review workloads producing long OLD/NEW diffs.
|
|
31
|
+
- **Per-call override** — new `maxOutputTokens` field on both `ask` and `code` schemas. Beats both default and env-force. Clamped to model's limit if larger.
|
|
32
|
+
- Budget reservation uses effective cap (explicit OR model limit) as worst-case regardless of which layer applies, so `GEMINI_DAILY_BUDGET_USD` stays a true upper bound.
|
|
33
|
+
- New env var documented in `docs/configuration.md`; full three-layer table + examples in `docs/models.md`.
|
|
34
|
+
- **`src/gemini/model-taxonomy.ts`** — new module with `ModelCategory` type, `CATEGORY_RULES` ordered pattern-allowlist, `categorizeModel(id)`, `extractCapabilityFlags(id, sdkMeta)`, `costTierOf(id)`, `isTextGenCategory(cat)`, and the exported `ModelCategoryMismatchError` class with actionable message pointing at `docs/models.md`.
|
|
35
|
+
- **`latest-vision` alias** — picks the newest vision-capable text model (prefers `text-reasoning`, falls back to `text-fast`). Previously users needed to know a specific Gemini 2.5 / 3 Pro model ID for screenshot analysis.
|
|
36
|
+
- **New response metadata fields** on `ask` / `code` structured content: `modelCategory` (string) and `modelCostTier` (`premium` | `standard` | `budget` | `unknown`). Use these for billing dashboards or to verify that an alias resolved to what you expected.
|
|
37
|
+
- **New docs — [`docs/models.md`](./docs/models.md)** — complete guide: category table with descriptions, alias contract, usage examples (code review, quick Q&A, vision analysis, explicit model IDs), failure-mode walkthroughs (wrong category error, unknown future family error), and the "when to extend the taxonomy" maintainer note.
|
|
38
|
+
- **48 new unit tests** (`test/unit/model-taxonomy.test.ts`) covering every current Gemini model's expected categorisation, precedence rules (the core invariant — `nano-banana-pro-preview` must resolve to `image-generation`, not `text-reasoning`), `unknown` fallback for future families, `costTierOf` + `extractCapabilityFlags` paths, and `ModelCategoryMismatchError` shape.
|
|
39
|
+
- **9 new resolver tests** in `test/unit/models.test.ts` covering v1.4.0 contract: `ResolvedModel` carries `category` + `capabilities`, `requiredCategory` rejects literal model IDs in the wrong category, alias path enforces category too, `latest-vision` picks vision-capable, `latest-lite` binds strictly to budget tier, unknown-category explicit ID throws under required-category gate, + `describeAlias` / `listAliases` public API tests.
|
|
40
|
+
|
|
41
|
+
### Changed
|
|
42
|
+
|
|
43
|
+
- **`ResolvedModel` interface** (`src/types.ts`) gains `category: ModelCategory` and `capabilities: CapabilityFlags` required fields. Populated by `src/gemini/models.ts`'s `resolveModel` via `src/gemini/model-taxonomy.ts`.
|
|
44
|
+
- **`resolveModel(requested, client, opts?)`** (`src/gemini/models.ts`) accepts `opts.requiredCategory: readonly ModelCategory[]` — the set of categories this call-site accepts. Throws `ModelCategoryMismatchError` if the resolved model (alias-picked or literal) falls outside that set. Tools pass this parameter:
|
|
45
|
+
- `ask.tool.ts` → `['text-reasoning', 'text-fast', 'text-lite']` (any text tier)
|
|
46
|
+
- `code.tool.ts` → `['text-reasoning']` (strictest; coding benefits from reasoning tokens and we refuse to dispatch to fast/lite tiers for correctness)
|
|
47
|
+
- **Literal model ID fallback removed** — pre-v1.4.0, passing a literal ID that wasn't in the API-key's registry silently swapped to `latest-pro`, which could resolve to an image-gen model. v1.4.0 throws a clear error instead: `Model 'X' is not available for this API key. Pass an alias (…) or a literal ID available on your tier (…). See docs/models.md.`
|
|
48
|
+
- **Alias fallback across categories removed** — pre-v1.4.0, if `latest-pro-thinking` found nothing, it fell back to `latest-pro` → `latest-flash` → `latest-lite` → first model. This meant a registry with only image-gen pro models would return an image model for a code-review alias. v1.4.0 throws a clear error naming the required category and listing available categories for the API key.
|
|
49
|
+
- **Existing blocklist `NON_TEXT_GEN_MARKERS`** retained as belt-and-suspenders defence — runs AFTER categorisation. If a taxonomy rule erroneously classifies a model as text-gen but its ID matches a blocklist marker, the resolver logs and demotes it to `unknown`. Empirically fired once during testing for `gemini-2.5-flash-native-audio-preview-09-2025` (flash-token + audio-suffix combo); that pattern has since been added to the primary taxonomy rule set, so the belt-and-suspenders should no longer fire under the current model lineup.
|
|
50
|
+
- **New native-audio rule** in the taxonomy: `gemini-*-native-audio-*` → `audio-generation`. Surfaced by the belt-and-suspenders path during Phase 3 integration testing.
|
|
51
|
+
- **`docs/configuration.md`** alias table updated with category column and a link to the new `docs/models.md`.
|
|
52
|
+
- **`README.md`** gains an "Model aliases (v1.4.0+)" block explaining the category safety property.
|
|
53
|
+
|
|
54
|
+
### Reviewer notes (not a code change)
|
|
55
|
+
|
|
56
|
+
- Implemented in five phases (taxonomy → resolver refactor → tool integration → docs → validate/PR), each locked behind user review checkpoint per global `CLAUDE.md` phase-by-phase rule.
|
|
57
|
+
- The allowlist-first design was chosen explicitly over the v1.2.0–v1.3.2 reactive blocklist after the user flagged the core concern: "never let `nano-banana` do my code review". Blocklists catch *known* offenders; allowlists refuse *everything unknown*. Google shipping a new `pro`-token image-gen family that we haven't classified is now a `HARD ERROR` with a clear upgrade path, not a silent pricing surprise.
|
|
58
|
+
- Belt-and-suspenders `NON_TEXT_GEN_MARKERS` blocklist retained even though the taxonomy is primary — shouldn't fire in practice, catches taxonomy bugs before they reach production.
|
|
59
|
+
|
|
10
60
|
## [1.3.2] — 2026-04-20
|
|
11
61
|
|
|
12
62
|
Security-flavoured hotfix closing hint-poisoning attack surface flagged in PR #20 (v1.3.1) multi-round review. **Two review rounds on this hotfix itself** (PR #21 round-1 + round-2) refined the gate design — the initial substring fallback was itself bypassable and got tightened to prototype-based SDK provenance. `/6step` verified all findings closed end-to-end against a real `@google/genai` `ApiError` instance.
|
package/README.md
CHANGED
|
@@ -64,6 +64,20 @@ See [`docs/getting-started.md`](./docs/getting-started.md) for a 3-minute walkth
|
|
|
64
64
|
|
|
65
65
|
All tools accept an optional `workspace` path (defaults to `cwd`), `model` alias or literal ID, and glob overrides.
|
|
66
66
|
|
|
67
|
+
### Model aliases (v1.4.0+)
|
|
68
|
+
|
|
69
|
+
Aliases are **category-safe** — they resolve against a known functional category (text-reasoning, text-fast, text-lite, etc.) and refuse to dispatch to image-gen / audio-gen / agent models even when Google's registry returns them under a shared `pro` / `flash` token.
|
|
70
|
+
|
|
71
|
+
| Alias | Category | Typical use |
|
|
72
|
+
|---|---|---|
|
|
73
|
+
| `latest-pro-thinking` *(default for `code`)* | `text-reasoning` + thinking | Code review, deep analysis |
|
|
74
|
+
| `latest-pro` | `text-reasoning` | Best pro-tier text model |
|
|
75
|
+
| `latest-flash` | `text-fast` | Fast Q&A, cheap |
|
|
76
|
+
| `latest-lite` | `text-lite` | Simplest / cheapest |
|
|
77
|
+
| `latest-vision` | `text-reasoning` ∪ `text-fast` + vision | Screenshot / image analysis |
|
|
78
|
+
|
|
79
|
+
Full contract, category table, and examples: [`docs/models.md`](./docs/models.md).
|
|
80
|
+
|
|
67
81
|
## Installation methods
|
|
68
82
|
|
|
69
83
|
| Method | Config |
|
package/dist/config.d.ts
CHANGED
|
@@ -20,6 +20,18 @@ export interface Config {
|
|
|
20
20
|
maxFileSizeBytes: number;
|
|
21
21
|
/** Opt-in anonymous usage telemetry (count per tool, no payloads). */
|
|
22
22
|
telemetryEnabled: boolean;
|
|
23
|
+
/**
|
|
24
|
+
* When `true`, `ask` and `code` tools send `maxOutputTokens =
|
|
25
|
+
* modelOutputLimit` on every `generateContent` call (instead of omitting
|
|
26
|
+
* the field and relying on Gemini's model-default). Use this in MCP host
|
|
27
|
+
* configs where you want every call to run at the model's full output
|
|
28
|
+
* capacity — primary use case is code review that routinely produces
|
|
29
|
+
* long OLD/NEW diff blocks. Per-call `input.maxOutputTokens` still
|
|
30
|
+
* overrides (caller can cap a specific call lower). Default `false`
|
|
31
|
+
* (auto — Gemini decides response length based on query complexity).
|
|
32
|
+
* Controlled by `GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT` env var.
|
|
33
|
+
*/
|
|
34
|
+
forceMaxOutputTokens: boolean;
|
|
23
35
|
/**
|
|
24
36
|
* Client-side TPM (tokens-per-minute) throttle ceiling, per resolved model.
|
|
25
37
|
* `0` disables the throttle entirely; positive integer caps how many input
|
package/dist/config.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,0BAA0B,CAAC;AAE1E,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,0BAA0B,CAAC;AAE1E,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;OAUG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AA6BD,wBAAgB,UAAU,IAAI,MAAM,CAmCnC"}
|
package/dist/config.js
CHANGED
|
@@ -16,6 +16,19 @@ function readFloatEnv(name, fallback) {
|
|
|
16
16
|
const n = Number.parseFloat(raw);
|
|
17
17
|
return Number.isFinite(n) ? n : fallback;
|
|
18
18
|
}
|
|
19
|
+
/**
|
|
20
|
+
* Parse a boolean env var permissively. Accepts `true`/`1`/`yes`/`on`
|
|
21
|
+
* case-insensitively as `true`; everything else (including unset) is `false`.
|
|
22
|
+
* Strict equality to `'true'` (our pre-v1.4.0 pattern) surprised operators
|
|
23
|
+
* who copied values like `TRUE` / `1` from other docs.
|
|
24
|
+
*/
|
|
25
|
+
function readBoolEnv(name) {
|
|
26
|
+
const raw = process.env[name];
|
|
27
|
+
if (!raw)
|
|
28
|
+
return false;
|
|
29
|
+
const v = raw.trim().toLowerCase();
|
|
30
|
+
return v === 'true' || v === '1' || v === 'yes' || v === 'on';
|
|
31
|
+
}
|
|
19
32
|
export function loadConfig() {
|
|
20
33
|
const auth = resolveAuth();
|
|
21
34
|
// Default alias resolves to the newest Pro-class model that advertises
|
|
@@ -39,8 +52,9 @@ export function loadConfig() {
|
|
|
39
52
|
cacheMinTokens: readIntEnv('GEMINI_CODE_CONTEXT_CACHE_MIN_TOKENS', 1024),
|
|
40
53
|
maxFilesPerWorkspace: readIntEnv('GEMINI_CODE_CONTEXT_MAX_FILES', 2000),
|
|
41
54
|
maxFileSizeBytes: readIntEnv('GEMINI_CODE_CONTEXT_MAX_FILE_SIZE', 1_000_000),
|
|
42
|
-
telemetryEnabled:
|
|
55
|
+
telemetryEnabled: readBoolEnv('GEMINI_CODE_CONTEXT_TELEMETRY'),
|
|
43
56
|
tpmThrottleLimit,
|
|
57
|
+
forceMaxOutputTokens: readBoolEnv('GEMINI_CODE_CONTEXT_FORCE_MAX_OUTPUT'),
|
|
44
58
|
};
|
|
45
59
|
}
|
|
46
60
|
//# sourceMappingURL=config.js.map
|
package/dist/config.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAqB,WAAW,EAAE,MAAM,0BAA0B,CAAC;
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAqB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AA8C1E,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3C,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,QAAgB;IAClD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC9C,MAAM,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,IAAY;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnC,OAAO,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;IAE3B,uEAAuE;IACvE,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,YAAY,GAChB,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAE9F,MAAM,WAAW,GAAG,YAAY,CAC9B,yBAAyB,EACzB,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC,iBAAiB,CAChD,CAAC;IAEF,uEAAuE;IACvE,sEAAsE;IACtE,oEAAoE;IACpE,yEAAyE;IACzE,6CAA6C;IAC7C,MAAM,cAAc,GAAG,UAAU,CAAC,wCAAwC,EAAE,MAAM,CAAC,CAAC;IACpF,MAAM,gBAAgB,GAAG,cAAc,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC;IAEvE,OAAO;QACL,IAAI;QACJ,YAAY;QACZ,cAAc,EAAE,WAAW;QAC3B,eAAe,EAAE,UAAU,CAAC,uCAAuC,EAAE,IAAI,CAAC;QAC1E,cAAc,EAAE,UAAU,CAAC,sCAAsC,EAAE,IAAI,CAAC;QACxE,oBAAoB,EAAE,UAAU,CAAC,+BAA+B,EAAE,IAAI,CAAC;QACvE,gBAAgB,EAAE,UAAU,CAAC,mCAAmC,EAAE,SAAS,CAAC;QAC5E,gBAAgB,EAAE,WAAW,CAAC,+BAA+B,CAAC;QAC9D,gBAAgB;QAChB,oBAAoB,EAAE,WAAW,CAAC,sCAAsC,CAAC;KAC1E,CAAC;AACJ,CAAC"}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Model taxonomy — maps Gemini model IDs to functional categories and
|
|
3
|
+
* capability flags, so the resolver can refuse to dispatch (e.g.) a code
|
|
4
|
+
* review to an image-generation model that happens to share the `pro` token
|
|
5
|
+
* with text-gen models.
|
|
6
|
+
*
|
|
7
|
+
* Design principle: **allowlist-first**. Each category has an explicit list
|
|
8
|
+
* of regex patterns. Unrecognised model IDs fall back to `unknown` — the
|
|
9
|
+
* resolver then refuses to bind them to any alias. This is the inverse of
|
|
10
|
+
* the v1.2.0 approach (blocklist of substrings like `banana`, `lyria`,
|
|
11
|
+
* `research`), which required reactive maintenance whenever Google shipped
|
|
12
|
+
* a new non-text-gen family under a `pro`/`flash` token. Allowlist forces
|
|
13
|
+
* a conscious addition of new families rather than silently admitting them.
|
|
14
|
+
*
|
|
15
|
+
* When Google ships a new model family:
|
|
16
|
+
* 1. Update `CATEGORY_RULES` with the canonical pattern → category entry.
|
|
17
|
+
* 2. Update `docs/models.md` with the new row.
|
|
18
|
+
* 3. Ship a patch release — users who haven't upgraded get the `unknown`
|
|
19
|
+
* path (aliases fail with actionable error, explicit IDs still work
|
|
20
|
+
* via direct-pass).
|
|
21
|
+
*
|
|
22
|
+
* The blocklist from v1.2.0 (`NON_TEXT_GEN_MARKERS`) is retained in
|
|
23
|
+
* `models.ts` as belt-and-suspenders defence-in-depth — runs AFTER
|
|
24
|
+
* categorisation to catch any bugs that would let a mis-categorised model
|
|
25
|
+
* through. Shouldn't fire in practice.
|
|
26
|
+
*/
|
|
27
|
+
/**
|
|
28
|
+
* Functional category a model belongs to. Tools bind to required categories
|
|
29
|
+
* (e.g. `code` needs `text-reasoning`); the resolver refuses to return
|
|
30
|
+
* models outside the required set. Unknown category = no alias picks it.
|
|
31
|
+
*/
|
|
32
|
+
export type ModelCategory = 'text-reasoning' | 'text-fast' | 'text-lite' | 'image-generation' | 'audio-generation' | 'video-generation' | 'embedding' | 'agent' | 'unknown';
|
|
33
|
+
/**
|
|
34
|
+
* Orthogonal capability flags. Multiple can apply to a single model. Used
|
|
35
|
+
* by the resolver to filter WITHIN a category (e.g. `latest-pro-thinking`
|
|
36
|
+
* needs `text-reasoning` + `supportsThinking: true`).
|
|
37
|
+
*/
|
|
38
|
+
export interface CapabilityFlags {
|
|
39
|
+
readonly supportsThinking: boolean;
|
|
40
|
+
readonly supportsVision: boolean;
|
|
41
|
+
readonly supportsCodeExecution: boolean;
|
|
42
|
+
/** `premium` (pro-tier), `standard` (flash), `budget` (lite). */
|
|
43
|
+
readonly costTier: 'premium' | 'standard' | 'budget' | 'unknown';
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Classify a model by ID. Returns `unknown` for any ID that doesn't match
|
|
47
|
+
* an explicit rule — the resolver then refuses to bind this model to any
|
|
48
|
+
* text-* alias, forcing either a patch release (to extend the rules) or
|
|
49
|
+
* an explicit model ID pass-through from the caller.
|
|
50
|
+
*/
|
|
51
|
+
export declare function categorizeModel(modelId: string): ModelCategory;
|
|
52
|
+
/**
|
|
53
|
+
* Derive the cost tier from the model ID via the same rule set. When no
|
|
54
|
+
* rule matches, tier is `unknown` — the resolver treats this as
|
|
55
|
+
* ineligible for tiered aliases (`latest-pro`, `latest-flash`, `latest-lite`).
|
|
56
|
+
*/
|
|
57
|
+
export declare function costTierOf(modelId: string): CapabilityFlags['costTier'];
|
|
58
|
+
/**
|
|
59
|
+
* Extract capability flags from the model ID plus any metadata already
|
|
60
|
+
* available (supportsThinking is surfaced by `@google/genai`'s `models.list`,
|
|
61
|
+
* vision / code-execution are inferred from ID patterns since the SDK
|
|
62
|
+
* doesn't advertise them consistently).
|
|
63
|
+
*/
|
|
64
|
+
export declare function extractCapabilityFlags(modelId: string, sdkMetadata: {
|
|
65
|
+
readonly supportsThinking: boolean;
|
|
66
|
+
}): CapabilityFlags;
|
|
67
|
+
/**
|
|
68
|
+
* True iff `category` is one of the three text-gen tiers — the categories
|
|
69
|
+
* that `ask` / `code` tools accept via their `requiredCategory` option.
|
|
70
|
+
* Exposed for external diagnostics / tooling (`docs/models.md` alias table
|
|
71
|
+
* derivations, integration tests); the resolver itself does an explicit
|
|
72
|
+
* `requiredCategory.includes(...)` check per call rather than routing
|
|
73
|
+
* through this helper, since `requiredCategory` can legitimately be a
|
|
74
|
+
* narrower subset (`code` → `['text-reasoning']` only).
|
|
75
|
+
*/
|
|
76
|
+
export declare function isTextGenCategory(category: ModelCategory): boolean;
|
|
77
|
+
/**
|
|
78
|
+
* Error thrown when a resolver call requests a category that the resolved
|
|
79
|
+
* model does NOT satisfy. Actionable message: tells the caller what the
|
|
80
|
+
* resolved model's category actually is and which categories the tool
|
|
81
|
+
* accepts, so they can either pick a different model or file an issue if
|
|
82
|
+
* they believe the taxonomy is wrong.
|
|
83
|
+
*/
|
|
84
|
+
export declare class ModelCategoryMismatchError extends Error {
|
|
85
|
+
readonly modelId: string;
|
|
86
|
+
readonly actualCategory: ModelCategory;
|
|
87
|
+
readonly requiredCategory: readonly ModelCategory[];
|
|
88
|
+
constructor(options: {
|
|
89
|
+
modelId: string;
|
|
90
|
+
actualCategory: ModelCategory;
|
|
91
|
+
requiredCategory: readonly ModelCategory[];
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
//# sourceMappingURL=model-taxonomy.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"model-taxonomy.d.ts","sourceRoot":"","sources":["../../src/gemini/model-taxonomy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,WAAW,GACX,WAAW,GACX,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,WAAW,GACX,OAAO,GACP,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;CAClE;AAoFD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,CAKvE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE;IAAE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,GAClD,eAAe,CAuBjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAElE;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,aAAa,EAAE,CAAC;gBAExC,OAAO,EAAE;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,aAAa,CAAC;QAC9B,gBAAgB,EAAE,SAAS,aAAa,EAAE,CAAC;KAC5C;CAWF"}
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Model taxonomy — maps Gemini model IDs to functional categories and
|
|
3
|
+
* capability flags, so the resolver can refuse to dispatch (e.g.) a code
|
|
4
|
+
* review to an image-generation model that happens to share the `pro` token
|
|
5
|
+
* with text-gen models.
|
|
6
|
+
*
|
|
7
|
+
* Design principle: **allowlist-first**. Each category has an explicit list
|
|
8
|
+
* of regex patterns. Unrecognised model IDs fall back to `unknown` — the
|
|
9
|
+
* resolver then refuses to bind them to any alias. This is the inverse of
|
|
10
|
+
* the v1.2.0 approach (blocklist of substrings like `banana`, `lyria`,
|
|
11
|
+
* `research`), which required reactive maintenance whenever Google shipped
|
|
12
|
+
* a new non-text-gen family under a `pro`/`flash` token. Allowlist forces
|
|
13
|
+
* a conscious addition of new families rather than silently admitting them.
|
|
14
|
+
*
|
|
15
|
+
* When Google ships a new model family:
|
|
16
|
+
* 1. Update `CATEGORY_RULES` with the canonical pattern → category entry.
|
|
17
|
+
* 2. Update `docs/models.md` with the new row.
|
|
18
|
+
* 3. Ship a patch release — users who haven't upgraded get the `unknown`
|
|
19
|
+
* path (aliases fail with actionable error, explicit IDs still work
|
|
20
|
+
* via direct-pass).
|
|
21
|
+
*
|
|
22
|
+
* The blocklist from v1.2.0 (`NON_TEXT_GEN_MARKERS`) is retained in
|
|
23
|
+
* `models.ts` as belt-and-suspenders defence-in-depth — runs AFTER
|
|
24
|
+
* categorisation to catch any bugs that would let a mis-categorised model
|
|
25
|
+
* through. Shouldn't fire in practice.
|
|
26
|
+
*/
|
|
27
|
+
const CATEGORY_RULES = [
|
|
28
|
+
// === Image generation — MUST come before pro/flash text rules ===
|
|
29
|
+
// `nano-banana-*` is Google's image-gen family (pro/flash tiers), IDs
|
|
30
|
+
// like `nano-banana-pro-preview`. Shares the `pro` token with text models
|
|
31
|
+
// but bills at the image tier (~10× text rates).
|
|
32
|
+
{ pattern: /^nano-banana/i, category: 'image-generation', costTier: 'premium' },
|
|
33
|
+
// `*-image` suffix (e.g. `gemini-3-pro-image`) identifies Gemini's native
|
|
34
|
+
// image-output variants.
|
|
35
|
+
{ pattern: /-image(?:-|$)/i, category: 'image-generation', costTier: 'premium' },
|
|
36
|
+
// Google's Imagen family — dedicated image generation.
|
|
37
|
+
{ pattern: /^imagen-/i, category: 'image-generation', costTier: 'premium' },
|
|
38
|
+
// === Audio generation ===
|
|
39
|
+
// Lyria = Google's music generation family (`lyria-3-pro-preview` etc.).
|
|
40
|
+
{ pattern: /^lyria-/i, category: 'audio-generation', costTier: 'premium' },
|
|
41
|
+
// TTS variants — any model with `-tts` suffix or `text-to-speech` in ID.
|
|
42
|
+
// Token-boundary anchoring prevents `-tts-like-foo` false positives.
|
|
43
|
+
{ pattern: /(?:^|-)tts(?:-|$)/i, category: 'audio-generation', costTier: 'standard' },
|
|
44
|
+
{ pattern: /(?:^|-)text-to-speech(?:-|$)/i, category: 'audio-generation', costTier: 'standard' },
|
|
45
|
+
// Native-audio variants (`gemini-2.5-flash-native-audio-preview-*`) —
|
|
46
|
+
// dialog-native audio generation. Shares `flash` token with text-gen
|
|
47
|
+
// models; must classify before the flash rule.
|
|
48
|
+
{ pattern: /(?:^|-)native-audio(?:-|$)/i, category: 'audio-generation', costTier: 'standard' },
|
|
49
|
+
// === Video generation ===
|
|
50
|
+
// Veo = Google's video generation family (`veo-3`, `veo-3.1` etc.).
|
|
51
|
+
{ pattern: /^veo-/i, category: 'video-generation', costTier: 'premium' },
|
|
52
|
+
// === Multimodal Live API (bidirectional streaming) ===
|
|
53
|
+
// `gemini-*-live-*` (e.g. `gemini-2.0-flash-live-001`) uses the
|
|
54
|
+
// `bidiGenerateContent` WebRTC/streaming API, NOT `generateContent`.
|
|
55
|
+
// Dispatching a text prompt here returns 400 or an unexpected response
|
|
56
|
+
// shape. Must classify before the flash/pro text rules to avoid
|
|
57
|
+
// admission as text-fast. `agent` category signals "not drop-in
|
|
58
|
+
// replaceable with a text model" (flagged by GPT PR #22 review).
|
|
59
|
+
{ pattern: /(?:^|-)live(?:-|$)/i, category: 'agent', costTier: 'standard' },
|
|
60
|
+
// === Embeddings ===
|
|
61
|
+
// Token-boundary anchoring: matches `text-embedding-004`,
|
|
62
|
+
// `gemini-embedding-001` etc., rejects hypothetical `foo-embedding-like-helper`.
|
|
63
|
+
{ pattern: /(?:^|-)embedding(?:-|$)/i, category: 'embedding', costTier: 'budget' },
|
|
64
|
+
{ pattern: /^text-embedding/i, category: 'embedding', costTier: 'budget' },
|
|
65
|
+
// === Agents (not drop-in replaceable) ===
|
|
66
|
+
// Deep Research — a specialised research agent, not a conversational model.
|
|
67
|
+
{ pattern: /(?:^|-)deep-research(?:-|$)/i, category: 'agent', costTier: 'premium' },
|
|
68
|
+
{ pattern: /(?:^|-)research(?:-|$)/i, category: 'agent', costTier: 'premium' },
|
|
69
|
+
// `customtools` variants require a `tools` param on every call; mis-used
|
|
70
|
+
// as a conversational model returns errors.
|
|
71
|
+
{ pattern: /(?:^|-)customtools(?:-|$)/i, category: 'agent', costTier: 'premium' },
|
|
72
|
+
// === Text tiers — AFTER all specialisations above ===
|
|
73
|
+
// Lite (budget / smallest). Matches `gemini-3-flash-lite`, `gemini-flash-lite`,
|
|
74
|
+
// `flash-lite`. The single `-lite` rule is a superset of the previously
|
|
75
|
+
// also-listed `flash-lite` rule — the latter was unreachable dead code
|
|
76
|
+
// (Grok PR #22 review finding F); removed.
|
|
77
|
+
{ pattern: /-lite(?:-|$)/i, category: 'text-lite', costTier: 'budget' },
|
|
78
|
+
// Flash (standard speed tier).
|
|
79
|
+
{ pattern: /^gemini-.*-flash/i, category: 'text-fast', costTier: 'standard' },
|
|
80
|
+
{ pattern: /-flash(?:-|$)/i, category: 'text-fast', costTier: 'standard' },
|
|
81
|
+
// Pro (reasoning / premium tier). Only reaches here if no specialisation
|
|
82
|
+
// above claimed the model. The `^gemini-pro` rule previously at the end
|
|
83
|
+
// of this list was unreachable because `/-pro(?:-|$)/i` already matches
|
|
84
|
+
// `gemini-pro` (Grok PR #22 review finding K); removed.
|
|
85
|
+
{ pattern: /^gemini-.*-pro/i, category: 'text-reasoning', costTier: 'premium' },
|
|
86
|
+
{ pattern: /-pro(?:-|$)/i, category: 'text-reasoning', costTier: 'premium' },
|
|
87
|
+
];
|
|
88
|
+
/**
|
|
89
|
+
* Classify a model by ID. Returns `unknown` for any ID that doesn't match
|
|
90
|
+
* an explicit rule — the resolver then refuses to bind this model to any
|
|
91
|
+
* text-* alias, forcing either a patch release (to extend the rules) or
|
|
92
|
+
* an explicit model ID pass-through from the caller.
|
|
93
|
+
*/
|
|
94
|
+
export function categorizeModel(modelId) {
|
|
95
|
+
if (typeof modelId !== 'string' || modelId.length === 0)
|
|
96
|
+
return 'unknown';
|
|
97
|
+
for (const rule of CATEGORY_RULES) {
|
|
98
|
+
if (rule.pattern.test(modelId))
|
|
99
|
+
return rule.category;
|
|
100
|
+
}
|
|
101
|
+
return 'unknown';
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Derive the cost tier from the model ID via the same rule set. When no
|
|
105
|
+
* rule matches, tier is `unknown` — the resolver treats this as
|
|
106
|
+
* ineligible for tiered aliases (`latest-pro`, `latest-flash`, `latest-lite`).
|
|
107
|
+
*/
|
|
108
|
+
export function costTierOf(modelId) {
|
|
109
|
+
for (const rule of CATEGORY_RULES) {
|
|
110
|
+
if (rule.pattern.test(modelId))
|
|
111
|
+
return rule.costTier;
|
|
112
|
+
}
|
|
113
|
+
return 'unknown';
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Extract capability flags from the model ID plus any metadata already
|
|
117
|
+
* available (supportsThinking is surfaced by `@google/genai`'s `models.list`,
|
|
118
|
+
* vision / code-execution are inferred from ID patterns since the SDK
|
|
119
|
+
* doesn't advertise them consistently).
|
|
120
|
+
*/
|
|
121
|
+
export function extractCapabilityFlags(modelId, sdkMetadata) {
|
|
122
|
+
// Single categorisation — CATEGORY_RULES runs a regex loop on every call,
|
|
123
|
+
// and capability derivation previously invoked `categorizeModel` four
|
|
124
|
+
// times per call. Classify once, then derive flags from the local
|
|
125
|
+
// `category` variable (Copilot PR #22 review).
|
|
126
|
+
const category = categorizeModel(modelId);
|
|
127
|
+
return {
|
|
128
|
+
supportsThinking: sdkMetadata.supportsThinking,
|
|
129
|
+
// Most current Gemini text models accept image input (multimodal by
|
|
130
|
+
// default). Only *-lite variants and embedding models don't. Heuristic
|
|
131
|
+
// matches Google's documented vision support table as of 2026-04.
|
|
132
|
+
supportsVision: category !== 'embedding' &&
|
|
133
|
+
category !== 'audio-generation' &&
|
|
134
|
+
category !== 'video-generation' &&
|
|
135
|
+
!/-lite(?:-|$)/i.test(modelId),
|
|
136
|
+
// Code execution is an explicit tool flag on generateContent; all
|
|
137
|
+
// current Gemini 2.5+/3.x text models support it. Exclude image /
|
|
138
|
+
// audio / video variants and embeddings.
|
|
139
|
+
supportsCodeExecution: category === 'text-reasoning' || category === 'text-fast' || category === 'text-lite',
|
|
140
|
+
costTier: costTierOf(modelId),
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* True iff `category` is one of the three text-gen tiers — the categories
|
|
145
|
+
* that `ask` / `code` tools accept via their `requiredCategory` option.
|
|
146
|
+
* Exposed for external diagnostics / tooling (`docs/models.md` alias table
|
|
147
|
+
* derivations, integration tests); the resolver itself does an explicit
|
|
148
|
+
* `requiredCategory.includes(...)` check per call rather than routing
|
|
149
|
+
* through this helper, since `requiredCategory` can legitimately be a
|
|
150
|
+
* narrower subset (`code` → `['text-reasoning']` only).
|
|
151
|
+
*/
|
|
152
|
+
export function isTextGenCategory(category) {
|
|
153
|
+
return category === 'text-reasoning' || category === 'text-fast' || category === 'text-lite';
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Error thrown when a resolver call requests a category that the resolved
|
|
157
|
+
* model does NOT satisfy. Actionable message: tells the caller what the
|
|
158
|
+
* resolved model's category actually is and which categories the tool
|
|
159
|
+
* accepts, so they can either pick a different model or file an issue if
|
|
160
|
+
* they believe the taxonomy is wrong.
|
|
161
|
+
*/
|
|
162
|
+
export class ModelCategoryMismatchError extends Error {
|
|
163
|
+
modelId;
|
|
164
|
+
actualCategory;
|
|
165
|
+
requiredCategory;
|
|
166
|
+
constructor(options) {
|
|
167
|
+
const required = options.requiredCategory.join(' | ');
|
|
168
|
+
super(`Model '${options.modelId}' is in category '${options.actualCategory}', but this tool requires: ${required}. Pass a model with a compatible category (e.g. 'latest-pro' or a literal model ID from docs/models.md). If you believe '${options.modelId}' is mis-categorised, file an issue at https://github.com/qmediat/gemini-code-context-mcp/issues.`);
|
|
169
|
+
this.name = 'ModelCategoryMismatchError';
|
|
170
|
+
this.modelId = options.modelId;
|
|
171
|
+
this.actualCategory = options.actualCategory;
|
|
172
|
+
this.requiredCategory = options.requiredCategory;
|
|
173
|
+
Object.setPrototypeOf(this, ModelCategoryMismatchError.prototype);
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
//# sourceMappingURL=model-taxonomy.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"model-taxonomy.js","sourceRoot":"","sources":["../../src/gemini/model-taxonomy.ts"],"names":[],"mappings":"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"}
|
package/dist/gemini/models.d.ts
CHANGED
|
@@ -1,23 +1,81 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Alias resolution for model selection.
|
|
3
3
|
*
|
|
4
|
-
* Users pass either an alias (`latest-pro`, `latest-flash`, `latest-pro-thinking
|
|
5
|
-
* or a literal model ID (`gemini-3-pro-preview`).
|
|
6
|
-
* model for the current API key
|
|
7
|
-
*
|
|
4
|
+
* Users pass either an alias (`latest-pro`, `latest-flash`, `latest-pro-thinking`,
|
|
5
|
+
* `latest-lite`, `latest-vision`) or a literal model ID (`gemini-3-pro-preview`).
|
|
6
|
+
* We resolve to the best available model for the current API key.
|
|
7
|
+
*
|
|
8
|
+
* v1.4.0: category-based filtering. Each alias declares the set of
|
|
9
|
+
* taxonomy categories it accepts. The resolver picks only from models
|
|
10
|
+
* whose category is in the accepted set — a pro-tier image-gen model
|
|
11
|
+
* (e.g. `nano-banana-pro-preview`) is NO LONGER eligible for
|
|
12
|
+
* `latest-pro-thinking` even if it shares the `pro` token with text-gen
|
|
13
|
+
* models. Literal model IDs ALSO go through a category check against the
|
|
14
|
+
* tool's required category — passing `model: "nano-banana-pro-preview"`
|
|
15
|
+
* to `code` throws `ModelCategoryMismatchError` with an actionable message.
|
|
16
|
+
*
|
|
17
|
+
* See `src/gemini/model-taxonomy.ts` for the category rule set and
|
|
18
|
+
* `docs/models.md` for the user-facing alias → category contract.
|
|
8
19
|
*/
|
|
9
20
|
import type { GoogleGenAI } from '@google/genai';
|
|
10
21
|
import type { ResolvedModel } from '../types.js';
|
|
11
|
-
import { type
|
|
22
|
+
import { type CapabilityFlags, type ModelCategory } from './model-taxonomy.js';
|
|
12
23
|
declare const ALIASES: {
|
|
13
|
-
readonly 'latest-pro':
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
24
|
+
readonly 'latest-pro': {
|
|
25
|
+
readonly acceptedCategories: readonly ["text-reasoning"];
|
|
26
|
+
readonly description: "latest pro-tier text-reasoning model";
|
|
27
|
+
};
|
|
28
|
+
readonly 'latest-pro-thinking': {
|
|
29
|
+
readonly acceptedCategories: readonly ["text-reasoning"];
|
|
30
|
+
readonly capabilityFilter: (flags: CapabilityFlags) => boolean;
|
|
31
|
+
readonly description: "latest pro-tier text-reasoning model with thinking support";
|
|
32
|
+
};
|
|
33
|
+
readonly 'latest-flash': {
|
|
34
|
+
readonly acceptedCategories: readonly ["text-fast"];
|
|
35
|
+
readonly description: "latest flash-tier (fast text-gen) model";
|
|
36
|
+
};
|
|
37
|
+
readonly 'latest-lite': {
|
|
38
|
+
readonly acceptedCategories: readonly ["text-lite"];
|
|
39
|
+
readonly description: "latest lite-tier (budget text-gen) model";
|
|
40
|
+
};
|
|
41
|
+
readonly 'latest-vision': {
|
|
42
|
+
readonly acceptedCategories: readonly ["text-reasoning", "text-fast"];
|
|
43
|
+
readonly capabilityFilter: (flags: CapabilityFlags) => boolean;
|
|
44
|
+
readonly description: "latest vision-capable text-gen model (prefers pro tier)";
|
|
45
|
+
};
|
|
17
46
|
};
|
|
18
47
|
export type Alias = keyof typeof ALIASES;
|
|
19
48
|
export declare function isAlias(value: string): value is Alias;
|
|
20
|
-
|
|
49
|
+
/**
|
|
50
|
+
* Options for `resolveModel`. Tools pass `requiredCategory` to assert the
|
|
51
|
+
* tool's category contract — the resolver throws `ModelCategoryMismatchError`
|
|
52
|
+
* if the resolved model doesn't satisfy it (even when the user passed a
|
|
53
|
+
* literal model ID). Omit to skip the category check (e.g. internal utility
|
|
54
|
+
* callers).
|
|
55
|
+
*/
|
|
56
|
+
export interface ResolveModelOptions {
|
|
57
|
+
/**
|
|
58
|
+
* Tool's accepted category set. The resolved model's `category` MUST be
|
|
59
|
+
* in this list. When unset, any category is accepted (back-compat with
|
|
60
|
+
* callers that don't enforce a contract).
|
|
61
|
+
*/
|
|
62
|
+
readonly requiredCategory?: readonly ModelCategory[];
|
|
63
|
+
}
|
|
64
|
+
export declare function resolveModel(requested: string, client: GoogleGenAI, options?: ResolveModelOptions): Promise<ResolvedModel>;
|
|
21
65
|
export declare function listAliases(): readonly Alias[];
|
|
66
|
+
/**
|
|
67
|
+
* Alias contract for documentation / diagnostics. Stable public API —
|
|
68
|
+
* kept in parity with `docs/models.md`. Returning a fresh copy per call so
|
|
69
|
+
* consumers can't mutate module state — even though the source array is
|
|
70
|
+
* `as const` (`readonly` at type level), a TypeScript cast would let a
|
|
71
|
+
* consumer mutate the live ALIASES table and corrupt future resolver calls.
|
|
72
|
+
* Spread-copy `[...spec.acceptedCategories]` makes the boundary explicit.
|
|
73
|
+
*/
|
|
74
|
+
export declare function describeAlias(alias: Alias): {
|
|
75
|
+
readonly acceptedCategories: readonly ModelCategory[];
|
|
76
|
+
readonly description: string;
|
|
77
|
+
readonly requiresThinking: boolean;
|
|
78
|
+
readonly requiresVision: boolean;
|
|
79
|
+
};
|
|
22
80
|
export {};
|
|
23
81
|
//# sourceMappingURL=models.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/gemini/models.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/gemini/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAInB,MAAM,qBAAqB,CAAC;AAkD7B,QAAA,MAAM,OAAO;;;;;;;2CAOiB,eAAe;;;;;;;;;;;;;2CAaf,eAAe;;;CAGC,CAAC;AAE/C,MAAM,MAAM,KAAK,GAAG,MAAM,OAAO,OAAO,CAAC;AAEzC,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,KAAK,CAErD;AAmCD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACtD;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,aAAa,CAAC,CAyDxB;AAaD,wBAAgB,WAAW,IAAI,SAAS,KAAK,EAAE,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,aAAa,EAAE,CAAC;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC,CAQA"}
|