@moldea.ai/adapter-google-genai 3.0.0 → 3.0.2
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/README.md +12 -1
- package/docs/binding-example.md +152 -0
- package/docs/evidence-and-diagnostics.md +30 -0
- package/docs/index.md +23 -0
- package/docs/limitations.md +21 -0
- package/docs/verified-target.md +28 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ The package implements the official `google-genai` runtime adapter for `@moldea.
|
|
|
8
8
|
|
|
9
9
|
## Supported target
|
|
10
10
|
|
|
11
|
-
Version `3.0.
|
|
11
|
+
Version `3.0.2` supports:
|
|
12
12
|
|
|
13
13
|
- Repository Format version `1`
|
|
14
14
|
- `@moldea.ai/core ^4.0.0`
|
|
@@ -60,3 +60,14 @@ pnpm --filter @moldea.ai/adapter-google-genai build
|
|
|
60
60
|
```
|
|
61
61
|
|
|
62
62
|
Tests are colocated with their owning modules. Canonical conformance fixtures live under `/fixtures/adapter-google-genai`.
|
|
63
|
+
|
|
64
|
+
## Documentation
|
|
65
|
+
|
|
66
|
+
- [Complete binding example](docs/binding-example.md): manifest, canonical instructions, runtime source, and supported schema or routing relationships.
|
|
67
|
+
|
|
68
|
+
These guides are included in the installed package. Open only the page relevant to your task.
|
|
69
|
+
|
|
70
|
+
- [Package overview](docs/index.md)
|
|
71
|
+
- [Verified target](docs/verified-target.md)
|
|
72
|
+
- [Evidence and diagnostics](docs/evidence-and-diagnostics.md)
|
|
73
|
+
- [Limitations](docs/limitations.md)
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Binding example
|
|
3
|
+
description: Complete manifest and source files for inspecting google-genai bindings locally.
|
|
4
|
+
order: 5
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Binding example
|
|
8
|
+
|
|
9
|
+
Read this example before searching adapter implementation for binding syntax. It is a complete **static inspection** file set, not a deployment starter or a live provider test. The files are checked together through this adapter and Core without installing or executing the target SDK. Keep application setup, credentials, provider model access, tool execution, and deployment configuration separate.
|
|
10
|
+
|
|
11
|
+
## How the bindings connect
|
|
12
|
+
|
|
13
|
+
The exported `supportAgent` function binds `generateContent`. `config.systemInstruction` calls the canonical loader; `config.tools[].functionDeclarations[]` contains the registered declaration. Use `parametersJsonSchema`, not `parameters`. This target does not inspect agent output schemas, tool output schemas, or handoffs. Function-call execution remains application-owned.
|
|
14
|
+
|
|
15
|
+
Paths below are repository-root-relative logical paths. Keep the canonical instructions as the policy source. General manifest semantics belong to the [Repository Format specification](https://packages.moldea.ai/repository-format/). Use the other local guides for the full supported boundary and limitations; this example does not expand them.
|
|
16
|
+
|
|
17
|
+
## Files
|
|
18
|
+
|
|
19
|
+
<!-- example:start -->
|
|
20
|
+
|
|
21
|
+
### /moldea/moldea.yaml
|
|
22
|
+
|
|
23
|
+
```yaml
|
|
24
|
+
version: 1
|
|
25
|
+
agents:
|
|
26
|
+
support:
|
|
27
|
+
runtime:
|
|
28
|
+
id: 'google-genai'
|
|
29
|
+
bindings:
|
|
30
|
+
runtimeAgent:
|
|
31
|
+
path: '/src/agent.ts'
|
|
32
|
+
symbol: 'supportAgent'
|
|
33
|
+
instructionLoader:
|
|
34
|
+
path: '/src/instructions.ts'
|
|
35
|
+
symbol: 'loadInstruction'
|
|
36
|
+
tools:
|
|
37
|
+
find-order:
|
|
38
|
+
name: 'find_order'
|
|
39
|
+
description: 'Retrieves one order by its identifier.'
|
|
40
|
+
implementation:
|
|
41
|
+
path: '/src/find-order.ts'
|
|
42
|
+
symbol: 'findOrder'
|
|
43
|
+
registration:
|
|
44
|
+
path: '/src/find-order.ts'
|
|
45
|
+
symbol: 'findOrderDeclaration'
|
|
46
|
+
inputSchema:
|
|
47
|
+
path: '/src/contracts.ts'
|
|
48
|
+
symbol: 'FindOrderInput'
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### /moldea/project.md
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
# Google Gen AI adapter fixture
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### /moldea/agents/support/description.md
|
|
58
|
+
|
|
59
|
+
```markdown
|
|
60
|
+
Support agent.
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### /moldea/agents/support/instruction.md
|
|
64
|
+
|
|
65
|
+
```markdown
|
|
66
|
+
You are the `support` agent.
|
|
67
|
+
|
|
68
|
+
Answer from supplied support facts. Do not invent order status or account information.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### /package.json
|
|
72
|
+
|
|
73
|
+
```json
|
|
74
|
+
{
|
|
75
|
+
"dependencies": {
|
|
76
|
+
"@google/genai": "^2.17.1"
|
|
77
|
+
},
|
|
78
|
+
"name": "binding-example",
|
|
79
|
+
"private": true,
|
|
80
|
+
"type": "module"
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### /src/agent.ts
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
import { GoogleGenAI as GenAi } from '@google/genai';
|
|
88
|
+
|
|
89
|
+
import { findOrderDeclaration as registeredFindOrder } from './find-order.js';
|
|
90
|
+
import { loadInstruction as readInstruction } from './instructions.js';
|
|
91
|
+
|
|
92
|
+
const client = new GenAi({ apiKey: process.env['GEMINI_API_KEY'] });
|
|
93
|
+
|
|
94
|
+
export const supportAgent = async () =>
|
|
95
|
+
client.models.generateContent({
|
|
96
|
+
model: 'gemini-2.5-flash',
|
|
97
|
+
contents: 'Help the customer.',
|
|
98
|
+
config: {
|
|
99
|
+
systemInstruction: await readInstruction(),
|
|
100
|
+
tools: [
|
|
101
|
+
{
|
|
102
|
+
functionDeclarations: [registeredFindOrder],
|
|
103
|
+
},
|
|
104
|
+
],
|
|
105
|
+
},
|
|
106
|
+
});
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### /src/contracts.ts
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
export const FindOrderInput = {
|
|
113
|
+
additionalProperties: false,
|
|
114
|
+
properties: { orderId: { type: 'string' } },
|
|
115
|
+
required: ['orderId'],
|
|
116
|
+
type: 'object',
|
|
117
|
+
} as const;
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### /src/find-order.ts
|
|
121
|
+
|
|
122
|
+
```typescript
|
|
123
|
+
import { FindOrderInput } from './contracts.js';
|
|
124
|
+
|
|
125
|
+
/** Looks up an order in the example's fixed catalog. */
|
|
126
|
+
export const findOrder = async (orderId: string) => ({
|
|
127
|
+
orderId,
|
|
128
|
+
status: orderId === 'order-1042' ? 'shipped' : 'not_found',
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
export const findOrderDeclaration = {
|
|
132
|
+
name: 'find_order',
|
|
133
|
+
description: 'Retrieves one order by its identifier.',
|
|
134
|
+
parametersJsonSchema: FindOrderInput,
|
|
135
|
+
} as const;
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### /src/instructions.ts
|
|
139
|
+
|
|
140
|
+
```typescript
|
|
141
|
+
import { readFileSync } from 'node:fs';
|
|
142
|
+
|
|
143
|
+
/** Reads the canonical support instruction. */
|
|
144
|
+
export const loadInstruction = (): string =>
|
|
145
|
+
readFileSync(new URL('../moldea/agents/support/instruction.md', import.meta.url), 'utf8');
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
<!-- example:end -->
|
|
149
|
+
|
|
150
|
+
## What the check establishes
|
|
151
|
+
|
|
152
|
+
The integration check reads these exact file blocks, requires positive adapter evidence for the documented relationships, and rejects a broken runtime binding. It does not prove that instructions are followed, that every SDK version accepts these forms, or that the application is ready for production. Continue using the installed adapter diagnostics for your actual source.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Evidence and diagnostics
|
|
3
|
+
description: Evidence kinds, stable diagnostics, conservative ambiguity, and cascade suppression.
|
|
4
|
+
order: 20
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Evidence and diagnostics
|
|
8
|
+
|
|
9
|
+
The target may emit `runtime-package`, `language`, `runtime-pattern`, `instruction-loader`, `tool-registration`, and `schema` evidence. Records identify only safe scalar metadata and logical source references.
|
|
10
|
+
|
|
11
|
+
## Diagnostic catalog
|
|
12
|
+
|
|
13
|
+
| Code | Stable message |
|
|
14
|
+
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| `GOOGLE_GENAI_PACKAGE_MANIFEST_INVALID` | The owning package manifest is invalid for Google Gen AI dependency detection. |
|
|
16
|
+
| `GOOGLE_GENAI_SDK_VERSION_UNSUPPORTED` | The observed Google Gen AI SDK dependency range is disjoint from the supported range. |
|
|
17
|
+
| `GOOGLE_GENAI_SOURCE_TEXT_INVALID` | The referenced Google Gen AI source file is not valid normalized text. |
|
|
18
|
+
| `GOOGLE_GENAI_SOURCE_SYNTAX_INVALID` | The referenced Google Gen AI source file contains invalid TypeScript syntax. |
|
|
19
|
+
| `GOOGLE_GENAI_RUNTIME_AGENT_SYMBOL_NOT_FOUND` | The declared runtime-agent symbol was not found. |
|
|
20
|
+
| `GOOGLE_GENAI_INSTRUCTION_LOADER_SYMBOL_NOT_FOUND` | The declared instruction-loader symbol was not found. |
|
|
21
|
+
| `GOOGLE_GENAI_TOOL_REGISTRATION_SYMBOL_NOT_FOUND` | The declared tool-registration symbol was not found. |
|
|
22
|
+
| `GOOGLE_GENAI_TOOL_INPUT_SCHEMA_SYMBOL_NOT_FOUND` | The declared tool input-schema symbol was not found. |
|
|
23
|
+
| `GOOGLE_GENAI_INSTRUCTION_LOADER_NOT_WIRED` | The declared instruction loader is not wired to the detected Google Gen AI generate-content configuration. |
|
|
24
|
+
| `GOOGLE_GENAI_TOOL_REGISTRATION_NOT_WIRED` | The declared tool registration is not wired to the detected Google Gen AI function-declaration collection. |
|
|
25
|
+
| `GOOGLE_GENAI_TOOL_NAME_MISMATCH` | The declared tool name does not match the detected Google Gen AI function name. |
|
|
26
|
+
| `GOOGLE_GENAI_TOOL_NAME_INVALID` | The detected Google Gen AI function name violates the supported SDK declaration limit. |
|
|
27
|
+
| `GOOGLE_GENAI_TOOL_INPUT_SCHEMA_NOT_WIRED` | The declared tool input schema is not wired to the detected function declaration's parameters JSON schema. |
|
|
28
|
+
| `GOOGLE_GENAI_FUNCTION_DECLARATION_LIMIT_EXCEEDED` | The detected Google Gen AI function-declaration collection exceeds the supported SDK declaration limit. |
|
|
29
|
+
|
|
30
|
+
Invalid text or syntax suppresses derived symbol and relationship diagnostics for that source. Missing symbols suppress their derived wiring diagnostics. Unsupported or dynamic requests, configurations, collections, containers, registrations, or schema values suppress negative relationship diagnostics when they could contain the declared relationship. Independently proved package, name, and collection-limit diagnostics remain observable.
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Google Gen AI runtime adapter
|
|
3
|
+
navigationTitle: Overview
|
|
4
|
+
description: Deterministic evidence and diagnostics for the verified direct Google Gen AI models.generateContent target.
|
|
5
|
+
order: 0
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Google Gen AI runtime adapter
|
|
9
|
+
|
|
10
|
+
`@moldea.ai/adapter-google-genai` implements the official `google-genai` runtime adapter for Core. It statically inspects explicitly bound TypeScript source through Core's source-neutral repository reader.
|
|
11
|
+
|
|
12
|
+
```typescript
|
|
13
|
+
import { googleGenAiAdapter } from '@moldea.ai/adapter-google-genai';
|
|
14
|
+
import { createCore } from '@moldea.ai/core';
|
|
15
|
+
|
|
16
|
+
const core = createCore({ adapters: [googleGenAiAdapter] });
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The package is available with one technical target covering TypeScript ESM using direct `models.generateContent` calls with npm `@google/genai >=2.17.1`, Repository Format version `1`, and Core `^4.0.0`.
|
|
20
|
+
|
|
21
|
+
The adapter never imports or calls the Google Gen AI SDK, executes no repository code, requires no credentials, and makes no network request. Its only public export is the immutable `googleGenAiAdapter` singleton.
|
|
22
|
+
|
|
23
|
+
Start with the [complete binding example](https://packages.moldea.ai/adapters/google-genai/binding-example/) when connecting runtime source to canonical instructions, schemas, tools, or routing metadata. The same example ships locally as `docs/binding-example.md` in the installed package.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Boundaries and limitations
|
|
3
|
+
description: Unsupported APIs, source forms, provider behavior, and the deterministic security boundary.
|
|
4
|
+
order: 30
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Boundaries and limitations
|
|
8
|
+
|
|
9
|
+
The current target does not claim support for:
|
|
10
|
+
|
|
11
|
+
- JavaScript, Python, CommonJS, or non-ESM source
|
|
12
|
+
- legacy `@google/generative-ai`
|
|
13
|
+
- `generateContentStream`, chats, live sessions, or the Interactions API
|
|
14
|
+
- callable tools, MCP conversion, automatic function execution, or provider/server tool relationships
|
|
15
|
+
- configuration or clients returned by factories
|
|
16
|
+
- arbitrary compiler resolution, path aliases, package exports, directory indexes, or re-export graphs
|
|
17
|
+
- alternative `FunctionDeclaration.parameters` schemas
|
|
18
|
+
- response-schema, tool-output-schema, or agent input/output-schema evidence
|
|
19
|
+
- backend, project, location, API version, authentication mode, model, contents, response, retry, or transport validation
|
|
20
|
+
|
|
21
|
+
Package detection uses nearest manifests rather than lockfiles or installed modules. Static dependency ranges are observations, not proof of an installed build. Each invocation sees one declared agent and bounded logical repository operations, not a complete agent collection or project body index. The adapter never executes source, reads host files or environment variables, initializes tools, or contacts Google services.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Verified target
|
|
3
|
+
description: Exact package, language, generate-content, instruction, function-declaration, schema, and provider-limit behavior.
|
|
4
|
+
order: 10
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Verified target
|
|
8
|
+
|
|
9
|
+
The canonical Runtime Compatibility Matrix defines technical target `typescript-models-generate-content-2`.
|
|
10
|
+
|
|
11
|
+
## Runtime boundary
|
|
12
|
+
|
|
13
|
+
- TypeScript ESM `.ts`, `.tsx`, and `.mts` files
|
|
14
|
+
- named runtime value imports of `GoogleGenAI` from `@google/genai`
|
|
15
|
+
- the nearest owning manifest declaring `@google/genai >=2.17.1`
|
|
16
|
+
- a module-local `const` client constructed directly with `new GoogleGenAI(...)`
|
|
17
|
+
- a directly exported runtime-agent function containing exact non-computed `client.models.generateContent({ ... })` calls
|
|
18
|
+
- one exact object-literal request argument
|
|
19
|
+
|
|
20
|
+
`config` is resolved only as a direct object literal. `systemInstruction` and `tools` are classified independently inside it. Positive evidence is existential across supported calls; a negative wiring diagnostic requires every candidate to prove the relationship absent with no dynamic or unsupported candidate that could contain it.
|
|
21
|
+
|
|
22
|
+
## Function declarations
|
|
23
|
+
|
|
24
|
+
The tool path is `config.tools[].functionDeclarations[]`. Inline literals and immutable module-local `const` arrays and objects are supported. Arrays with holes or spreads, mutation, aliases, escapes, dynamic candidates, computed properties, and unknown container fields keep the affected relationship unresolved.
|
|
25
|
+
|
|
26
|
+
A supported declaration has a static `name`, optional static `description`, optional `parametersJsonSchema`, and optional uninterpreted `behavior`, `response`, and `responseJsonSchema`. The alternative `parameters` field is unsupported. Only a directly exported bound `const` object can establish manifest tool-registration and schema evidence; inline and unexported declarations still participate in closure and count checks.
|
|
27
|
+
|
|
28
|
+
Names must match `^[A-Za-z_][A-Za-z0-9_.:-]*$` and contain 1–128 Unicode scalar values. Every closed `functionDeclarations` collection permits at most 512 occurrences.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@moldea.ai/adapter-google-genai",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.2",
|
|
4
4
|
"description": "Deterministic runtime evidence and diagnostics for direct Google Gen AI SDK integrations.",
|
|
5
5
|
"homepage": "https://github.com/moldea-ai/packages/tree/main/projects/adapter-google-genai#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
"files": [
|
|
19
19
|
"cover.png",
|
|
20
20
|
"dist",
|
|
21
|
+
"docs",
|
|
21
22
|
"LICENSE",
|
|
22
23
|
"README.md"
|
|
23
24
|
],
|