@genesislcap/ai-assistant 15.34.0 → 15.35.0

package/docs/genesis.md

@@ -0,0 +1,180 @@
+# Genesis Bridge
+
+## Overview
+
+`@genesislcap/ai-assistant/genesis` connects the assistant to a Genesis app: it registers the
+model providers from the platform tier table, turns the app's resources into chat tools, and
+hands back one agent to bind to `<foundation-ai-assistant>`. It is what a generated app's mount
+code calls; the app supplies configuration, never a model id, endpoint or key.
+
+The API is `@beta`. This release covers **reads** — each `REQ_` resource becomes a read tool.
+`EVENT_` resources are validated and their tool names reserved, but they are not exposed as tools
+yet: writes need a review step in front of them and land separately.
+
+---
+
+## Mounting
+
+```ts
+import { registerGenesisAssistant } from '@genesislcap/ai-assistant/genesis';
+import config from './generated/ai-config.json';
+import * as extensions from './extensions';
+
+const { agents, blockedReason } = registerGenesisAssistant({ config, extensions });
+
+const assistant = document.querySelector('foundation-ai-assistant');
+assistant.agents = agents;
+if (blockedReason) assistant.setBlocked(true, blockedReason);
+```
+
+`registerGenesisAssistant` is synchronous and **never throws**. Anything that stops the assistant
+from running comes back as `blockedReason` (and is logged as an error) with an empty `agents`
+list, so a bad config or a tool-name clash costs the app its assistant, never its start-up:
+
+- AI is switched off for the build (`feature.ai` flag) or in the config (`enabled: false`);
+- the config is invalid (see below);
+- an extension tool reuses a name derived from a resource — reads and writes alike, so a later
+  release that exposes writes cannot collide with a tool the app already ships;
+- an extension tool is declared twice or has no handler;
+- the providers cannot be registered (for example `vendors` leaves out the configured vendor).
+
+A blocked registration registers no providers.
+
+### Options
+
+| Option         | Default                          | Notes                                                                                                                  |
+| -------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `config`       | —                                | The app's `GenesisAiConfig`.                                                                                           |
+| `container`    | the DOM DI container             | Where the tier providers are registered.                                                                               |
+| `endpointBase` | `<PUBLIC_PATH>/gwf/ai-service`   | The app's own AI proxy; `/<vendor>/chat` is appended. A preview build passes its own.                                  |
+| `vendors`      | `[config.vendor]`                | Vendors the user may switch between. One by default: a proxy holding one key cannot answer for another vendor.        |
+| `connect`      | the app's `Connect`, from DI     | Resolved when a tool first runs, not at registration.                                                                  |
+| `extensions`   | none                             | `{ toolDefinitions, toolHandlers, systemPrompt }` — the app's hand-written tools, added after the generated ones.      |
+
+The agent runs on the registry's default provider, which is the configured tier. Its system prompt
+is the configured prompt, then a fixed rule that tool results are app data and never
+instructions, then the extensions' prompt.
+
+---
+
+## Configuration
+
+```json
+{
+  "enabled": true,
+  "vendor": "gemini",
+  "tier": "high",
+  "systemPrompt": "You help traders find and understand their trades.",
+  "resources": [
+    { "name": "REQ_TRADE", "kind": "request", "context": "Trades booked in the app.", "maxRows": 200 },
+    { "name": "EVENT_TRADE_INSERT", "kind": "event", "op": "insert", "context": "Book a trade." }
+  ]
+}
+```
+
+| Field          | Rule                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------- |
+| `vendor`       | A tier-table vendor. Defaults to `gemini`.                                                  |
+| `tier`         | `low`, `high` or `reasoning`. Defaults to `high`.                                           |
+| `name`         | `REQ_<NAME>` or `EVENT_<NAME>`, unique; the tool name is the lowercased name (≤ 64 chars). |
+| `kind`         | Must match the prefix: `request` for `REQ_`, `event` for `EVENT_`.                          |
+| `context`      | Required. Becomes the tool description, so write it for the model.                          |
+| `op`           | Events only: `insert`, `modify`, `delete` or `custom`.                                      |
+| `maxRows`      | Requests only: a whole number from 1 to 1000. Defaults to 50.                               |
+
+---
+
+## Read tools
+
+A `REQ_TRADE` resource becomes the tool `req_trade` with two optional parameters:
+
+- `filters` — a list of `{field, op, value}`, all of which must match.
+- `max_rows` — clamped to the resource's `maxRows`; the resource default when omitted.
+
+### Filtering is criteria, and the model never writes one
+
+Filters become a single `CRITERIA_MATCH` expression, composed by the bridge. The model supplies
+structure only, because criteria are parsed as Groovy on the server and the platform concatenates
+an app's own row-level restriction into the same string (`"($userCriteria) && ($criteriaTemplate)"`).
+A criteria string built from model output could `||` its way past that restriction. **Do not add a
+free-text criteria parameter.**
+
+- The fields a resource can be filtered on come from the platform's metadata reply, which is
+  fetched under the resource's **unprefixed** name (`REQ_TRADE` is read as `REQ_TRADE`, but its
+  metadata is published as `TRADE`). `CRITERIA_FIELDS` is used when the resource publishes one;
+  a request server usually does not, and its criteria are evaluated against the row, so its
+  `REPLY_FIELD`s are what can be filtered on. Types and any `VALID_VALUES` come from the same
+  reply. A resource that describes no fields gets a tool with no `filters` parameter.
+- `op` is one of `equals`, `not_equals`, `contains`, `greater_than`, `greater_or_equal`,
+  `less_than`, `less_or_equal`, `is_blank`, `is_not_blank`. Which ones apply depends on the field's
+  type; the tool tells the model what a field holds, including an enum's values.
+- Values are escaped and written per type — strings quoted, numbers and booleans as literals,
+  dates as `Expr.dateIs*` calls on a `yyyyMMdd` bound. The grammar and escaping match grid-pro's
+  `filter.utils.ts`, the platform's other structured-filter caller.
+- A filter the bridge cannot build **refuses the whole read** (`error: 'invalid_filter'`) and says
+  what the resource does accept. It is never dropped silently and never sent in part: rows read
+  without a filter would answer a different question from the one the model asked.
+
+`REQUEST` is always sent empty, so a read works the same on a `criteriaOnlyRequest` request server
+and on one that declares request fields.
+
+There is no paging. A request resource honours `OFFSET` only when it is declared with
+`criteriaOnlyRequest`, which the bridge cannot see; on any other resource every "next page" is the
+first page again, and the model would count the same rows twice. A read is one capped page, and
+the way to the rest is a narrower read.
+
+A read never throws. Every result carries `source: 'app-database'` and `untrusted: true`:
+
+```ts
+// success
+{ source, untrusted, resource, rows, truncated, note? }
+// failure
+{ source, untrusted, resource,
+  error: 'not_connected' | 'invalid_filter' | 'rejected' | 'request_failed', message }
+```
+
+`truncated` is the server's `MORE_ROWS` when it sends one; otherwise the rule the platform's own
+request datasource uses (an advancing `NEXT_OFFSET` or a full page means there may be more). A
+truncated result carries a `note` telling the model these rows are not the full set, and what it
+can do: narrow with filters when the tool has any, raise `max_rows` when it is below the cap.
+
+`createGenesisResourceTools(resources, { connect })` builds the same tools without registering
+anything, for an app that assembles its own agent.
+
+---
+
+## Why a separate entry point
+
+The bridge imports `@genesislcap/foundation-comms`. This package declares no `sideEffects`, so
+everything reachable from its root ends up in every consumer's bundle — including hosts that are
+not Genesis apps. Keeping the bridge on its own entry point keeps it out of theirs; a test walks
+the root's import graph to hold that line.
+
+### Why `foundation-comms` is an optional peer at `workspace:^`
+
+`foundation-comms` is a **peer dependency** so the bridge uses the app's own `Connect`. It is
+installed either way (`foundation-ui` depends on it); the peer is about which copy.
+
+**What a second copy costs is silence.** A DI token is identity-based, so a second copy of comms
+carries a different one: the bridge would resolve a `Connect` that is not the app's, the tools
+would talk to a connection nobody logged into, and nothing anywhere would say so. There is no
+error to catch and no symptom to grep for — only tools that answer as though the app had no data.
+
+**Declaring beats deduping.** A regular dependency would usually be hoisted to one copy, and
+usually is not a guarantee: it rests on the consumer's resolver flattening the tree, which a
+version skew, a nested install or a different package manager can undo without anyone touching
+this package. A peer states the requirement instead of hoping it is met, and the install fails
+loudly when it is not.
+
+It is **optional** because only `./genesis` uses it: a host that never imports the bridge should
+not be asked to install comms.
+
+The range is a **caret, not `workspace:*`**. `workspace:*` publishes as an exact version, and an
+exact peer means any patch-level difference between the app's copy and this package's is an
+ERESOLVE at install time — a hard failure over a difference that cannot matter. `workspace:^`
+publishes as `^<version>`, which is what the requirement actually is.
+
+Two things are new here and were chosen rather than defaulted into: this is the first
+`workspace:^` in the monorepo, and the first internal package declared as a peer. Whatever lands
+here is what the next package copies, which is the reason the argument is written down rather
+than left in the `package.json` line.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "15.34.0",
+  "version": "15.35.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -32,6 +32,10 @@
       "import": "./dist/chat-driver.mjs",
       "require": "./dist/chat-driver.cjs"
     },
+    "./genesis": {
+      "types": "./dist/dts/genesis/index.d.ts",
+      "default": "./dist/esm/genesis/index.js"
+    },
     "./package.json": "./package.json",
     "./react": {
       "types": "./dist/dts/react.d.ts",
@@ -46,6 +50,9 @@
       ],
       "chat-driver": [
         "./dist/dts/chat-driver-node.d.ts"
+      ],
+      "genesis": [
+        "./dist/dts/genesis/index.d.ts"
       ]
     }
   },
@@ -75,29 +82,38 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.34.0",
-    "@genesislcap/genx": "15.34.0",
-    "@genesislcap/rollup-builder": "15.34.0",
-    "@genesislcap/ts-builder": "15.34.0",
-    "@genesislcap/uvu-playwright-builder": "15.34.0",
-    "@genesislcap/vite-builder": "15.34.0",
-    "@genesislcap/webpack-builder": "15.34.0",
+    "@genesislcap/foundation-comms": "15.35.0",
+    "@genesislcap/foundation-testing": "15.35.0",
+    "@genesislcap/genx": "15.35.0",
+    "@genesislcap/rollup-builder": "15.35.0",
+    "@genesislcap/ts-builder": "15.35.0",
+    "@genesislcap/uvu-playwright-builder": "15.35.0",
+    "@genesislcap/vite-builder": "15.35.0",
+    "@genesislcap/webpack-builder": "15.35.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.34.0",
-    "@genesislcap/foundation-logger": "15.34.0",
-    "@genesislcap/foundation-notifications": "15.34.0",
-    "@genesislcap/foundation-redux": "15.34.0",
-    "@genesislcap/foundation-ui": "15.34.0",
-    "@genesislcap/foundation-utils": "15.34.0",
-    "@genesislcap/rapid-design-system": "15.34.0",
-    "@genesislcap/web-core": "15.34.0",
+    "@genesislcap/foundation-ai": "15.35.0",
+    "@genesislcap/foundation-logger": "15.35.0",
+    "@genesislcap/foundation-notifications": "15.35.0",
+    "@genesislcap/foundation-redux": "15.35.0",
+    "@genesislcap/foundation-ui": "15.35.0",
+    "@genesislcap/foundation-utils": "15.35.0",
+    "@genesislcap/rapid-design-system": "15.35.0",
+    "@genesislcap/web-core": "15.35.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
+  "peerDependencies": {
+    "@genesislcap/foundation-comms": "^15.35.0"
+  },
+  "peerDependenciesMeta": {
+    "@genesislcap/foundation-comms": {
+      "optional": true
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/genesislcap/foundation-ui.git",