@moldea.ai/adapter-google-genai 3.0.1 → 3.0.2

package/README.md

@@ -8,7 +8,7 @@ The package implements the official `google-genai` runtime adapter for `@moldea.
 
 ## Supported target
 
-Version `3.0.1` supports:
+Version `3.0.2` supports:
 
 - Repository Format version `1`
 - `@moldea.ai/core ^4.0.0`
@@ -63,6 +63,8 @@ Tests are colocated with their owning modules. Canonical conformance fixtures li
 
 ## Documentation
 
+- [Complete binding example](docs/binding-example.md): manifest, canonical instructions, runtime source, and supported schema or routing relationships.
+
 These guides are included in the installed package. Open only the page relevant to your task.
 
 - [Package overview](docs/index.md)

package/docs/binding-example.md

@@ -0,0 +1,152 @@
+---
+title: Binding example
+description: Complete manifest and source files for inspecting google-genai bindings locally.
+order: 5
+---
+
+# Binding example
+
+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.
+
+## How the bindings connect
+
+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.
+
+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.
+
+## Files
+
+<!-- example:start -->
+
+### /moldea/moldea.yaml
+
+```yaml
+version: 1
+agents:
+  support:
+    runtime:
+      id: 'google-genai'
+    bindings:
+      runtimeAgent:
+        path: '/src/agent.ts'
+        symbol: 'supportAgent'
+      instructionLoader:
+        path: '/src/instructions.ts'
+        symbol: 'loadInstruction'
+    tools:
+      find-order:
+        name: 'find_order'
+        description: 'Retrieves one order by its identifier.'
+        implementation:
+          path: '/src/find-order.ts'
+          symbol: 'findOrder'
+        registration:
+          path: '/src/find-order.ts'
+          symbol: 'findOrderDeclaration'
+        inputSchema:
+          path: '/src/contracts.ts'
+          symbol: 'FindOrderInput'
+```
+
+### /moldea/project.md
+
+```markdown
+# Google Gen AI adapter fixture
+```
+
+### /moldea/agents/support/description.md
+
+```markdown
+Support agent.
+```
+
+### /moldea/agents/support/instruction.md
+
+```markdown
+You are the `support` agent.
+
+Answer from supplied support facts. Do not invent order status or account information.
+```
+
+### /package.json
+
+```json
+{
+  "dependencies": {
+    "@google/genai": "^2.17.1"
+  },
+  "name": "binding-example",
+  "private": true,
+  "type": "module"
+}
+```
+
+### /src/agent.ts
+
+```typescript
+import { GoogleGenAI as GenAi } from '@google/genai';
+
+import { findOrderDeclaration as registeredFindOrder } from './find-order.js';
+import { loadInstruction as readInstruction } from './instructions.js';
+
+const client = new GenAi({ apiKey: process.env['GEMINI_API_KEY'] });
+
+export const supportAgent = async () =>
+  client.models.generateContent({
+    model: 'gemini-2.5-flash',
+    contents: 'Help the customer.',
+    config: {
+      systemInstruction: await readInstruction(),
+      tools: [
+        {
+          functionDeclarations: [registeredFindOrder],
+        },
+      ],
+    },
+  });
+```
+
+### /src/contracts.ts
+
+```typescript
+export const FindOrderInput = {
+  additionalProperties: false,
+  properties: { orderId: { type: 'string' } },
+  required: ['orderId'],
+  type: 'object',
+} as const;
+```
+
+### /src/find-order.ts
+
+```typescript
+import { FindOrderInput } from './contracts.js';
+
+/** Looks up an order in the example's fixed catalog. */
+export const findOrder = async (orderId: string) => ({
+  orderId,
+  status: orderId === 'order-1042' ? 'shipped' : 'not_found',
+});
+
+export const findOrderDeclaration = {
+  name: 'find_order',
+  description: 'Retrieves one order by its identifier.',
+  parametersJsonSchema: FindOrderInput,
+} as const;
+```
+
+### /src/instructions.ts
+
+```typescript
+import { readFileSync } from 'node:fs';
+
+/** Reads the canonical support instruction. */
+export const loadInstruction = (): string =>
+  readFileSync(new URL('../moldea/agents/support/instruction.md', import.meta.url), 'utf8');
+```
+
+<!-- example:end -->
+
+## What the check establishes
+
+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.

package/docs/index.md

@@ -19,3 +19,5 @@ const core = createCore({ adapters: [googleGenAiAdapter] });
 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`.
 
 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.
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldea.ai/adapter-google-genai",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Deterministic runtime evidence and diagnostics for direct Google Gen AI SDK integrations.",
   "homepage": "https://github.com/moldea-ai/packages/tree/main/projects/adapter-google-genai#readme",
   "bugs": {