@byline/ai 3.0.2 → 3.1.1

package/README.md

@@ -1,4 +1,70 @@
-# Infonomic AI
+# @byline/ai
 
-Library components for AI
+The AI subsystem for [Byline CMS](https://github.com/Byline-CMS/bylinecms.dev)
+— provider-agnostic text generation and structured editing for the admin
+editor, with built-in editor plugins for the text and Lexical richtext fields.
 
+This package is part of Byline CMS — a developer-friendly, open-source
+headless CMS with versioning, editorial workflow, and content translation as
+first-class concerns.
+
+## What it provides
+
+- **Provider-agnostic execution** — a single `ExecuteInstruction` contract over
+  OpenAI, Google (Gemini), and Anthropic, with non-streaming and streaming
+  variants (`executeInstruction` / `executeInstructionStreaming`).
+- **Structured generation** — `generateStructured` / `generateStructuredStreaming`
+  for schema-constrained output.
+- **Patch generation** — `patch` / `patchStreaming`, which edit an ordered array
+  of Lexical text nodes in place (used by the richtext field's AI drawer).
+- **Editor plugins** — drop-in plugins for the two editor surfaces:
+  `@byline/ai/plugins/text` (`AiPluginText`) and `@byline/ai/plugins/lexical`
+  (`AiPluginLexical`, `AiLexicalExtension`, `TOGGLE_AI_DRAWER_COMMAND`).
+- **Browser-safe config** — a public config provider and provider/model helpers
+  that carry no server SDK dependencies.
+
+## Browser / server split
+
+The root entry is browser-safe; the SDK-backed execution code lives behind a
+separate server entry. Import from the right one:
+
+| Entry | Use from | Surface |
+|---|---|---|
+| `@byline/ai` | Browser **and** server | Types, `AiPublicConfigProvider` / `useAiPublicConfig`, provider/model helpers (`PROVIDERS`, `DEFAULT_MODELS`, `getDefaultModel`, …), `INSTRUCTION_MODES` |
+| `@byline/ai/server` | Server only | `executeInstruction(Streaming)`, `generateStructured(Streaming)`, `patch(Streaming)`, `getAiServerConfig` |
+| `@byline/ai/plugins/text` | Browser | `AiPluginText` |
+| `@byline/ai/plugins/lexical` | Browser | `AiPluginLexical`, `AiLexicalExtension`, `TOGGLE_AI_DRAWER_COMMAND` |
+
+Importing `@byline/ai/server` in the browser will crash — it pulls in the
+Anthropic/OpenAI/Google SDKs and pino. Host adapters mount the execute endpoint
+on the server and the plugins POST `ExecuteInstruction` payloads to it; see the
+host integration in `@byline/host-tanstack-start` (`integrations/byline-ai.tsx`,
+`server-fns/ai/*`).
+
+## Configuration
+
+Server config is read from the environment by `getAiServerConfig()`:
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `AI_DEFAULT_PROVIDER` | `openai` \| `google` \| `anthropic` | `openai` |
+| `OPENAI_API_KEY` / `OPENAI_BASE_URL` | OpenAI credentials | — |
+| `GOOGLE_API_KEY` / `GOOGLE_BASE_URL` | Google (Gemini) credentials | — |
+| `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` | Anthropic credentials | — |
+| `BYLINE_AI_ENDPOINT` | Endpoint the editor plugins POST to | `/admin/api/ai/execute` |
+| `LOG_LEVEL` / `LOG_PRETTY` | Logging | `info` |
+
+The curated per-provider model lists live in `src/config/ai-config.ts`
+(`PROVIDER_MODELS` / `DEFAULT_MODELS`). Run `pnpm list:models` to discover the
+models a provider currently exposes.
+
+## Documentation
+
+For the full architecture overview, the richtext/AI integration, and getting
+started instructions, see the main repository:
+<https://github.com/Byline-CMS/bylinecms.dev>. Relevant docs: `docs/RICHTEXT.md`,
+`docs/FIELDS.md`, and `docs/MCP.md`.
+
+## License
+
+MPL-2.0

package/dist/plugins/lexical/commands.d.ts

@@ -0,0 +1,16 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export declare const TOGGLE_AI_DRAWER_COMMAND: import("lexical").LexicalCommand<unknown>;
+/**
+ * Broadcasts the AI drawer's open/closed state so contributed UI (the
+ * toolbar button) can show an active visual cue. Dispatched by the drawer
+ * plugin whenever `open` changes — including closes triggered from the
+ * drawer's own controls. Observers register a listener and return `false`.
+ */
+export declare const AI_DRAWER_STATE_COMMAND: import("lexical").LexicalCommand<boolean>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/plugins/lexical/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../src/plugins/lexical/commands.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,eAAO,MAAM,wBAAwB,2CAA4C,CAAA;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,2CAAoD,CAAA"}

package/dist/plugins/lexical/commands.js

@@ -0,0 +1,23 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Lexical commands for the AI drawer, split out of `plugin.tsx` so the
+ * extension definition (and any toolbar contribution) can reference them
+ * without statically importing the drawer's React component graph. This
+ * keeps `AiLexicalExtension` light enough to be referenced from an
+ * eagerly-evaluated admin/client config.
+ */
+import { createCommand } from 'lexical';
+export const TOGGLE_AI_DRAWER_COMMAND = createCommand('TOGGLE_AI_DRAWER_COMMAND');
+/**
+ * Broadcasts the AI drawer's open/closed state so contributed UI (the
+ * toolbar button) can show an active visual cue. Dispatched by the drawer
+ * plugin whenever `open` changes — including closes triggered from the
+ * drawer's own controls. Observers register a listener and return `false`.
+ */
+export const AI_DRAWER_STATE_COMMAND = createCommand('AI_DRAWER_STATE_COMMAND');

package/dist/plugins/lexical/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../src/plugins/lexical/extension.tsx"],"names":[],"mappings":"AA8DA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,mHAiB7B,CAAA"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../src/plugins/lexical/extension.tsx"],"names":[],"mappings":"AA0EA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,mHAyB7B,CAAA"}

package/dist/plugins/lexical/extension.js

@@ -7,12 +7,23 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { useEffect, useState } from 'react';
-import { BylineToolbarExtension, useToolbarActiveEditor, } from '@byline/richtext-lexical';
+import { lazy, Suspense, useEffect, useState } from 'react';
+import { BylineToolbarExtension, useToolbarActiveEditor, } from '@byline/richtext-lexical/config';
 import { AiIcon } from '@byline/ui/react';
 import { ReactExtension } from '@lexical/react/ReactExtension';
 import { COMMAND_PRIORITY_LOW, configExtension, declarePeerDependency, defineExtension, } from 'lexical';
-import { AI_DRAWER_STATE_COMMAND, AiPluginLexical, TOGGLE_AI_DRAWER_COMMAND } from './plugin';
+import { AI_DRAWER_STATE_COMMAND, TOGGLE_AI_DRAWER_COMMAND } from './commands';
+/**
+ * The AI drawer is dynamic-imported so that merely *referencing*
+ * `AiLexicalExtension` (e.g. from an eagerly-evaluated admin/client
+ * config) does not pull the drawer's React component graph — and its
+ * Anthropic/OpenAI/Google-adjacent imports — into the importing bundle.
+ * The chunk loads on first editor mount, behind the editor's own lazy
+ * boundary; the inner `Suspense` is a belt-and-braces fallback.
+ */
+const AiPluginLexical = lazy(async () => ({
+    default: (await import('./plugin')).AiPluginLexical,
+}));
 function AiToolbarButton() {
     const editor = useToolbarActiveEditor();
     const [isOpen, setIsOpen] = useState(false);
@@ -42,7 +53,13 @@ function AiToolbarButton() {
  */
 export const AiLexicalExtension = defineExtension({
     name: '@byline/ai/Lexical',
-    dependencies: [configExtension(ReactExtension, { decorators: [_jsx(AiPluginLexical, {}, "d")] })],
+    dependencies: [
+        configExtension(ReactExtension, {
+            decorators: [
+                _jsx(Suspense, { fallback: null, children: _jsx(AiPluginLexical, {}) }, "d"),
+            ],
+        }),
+    ],
     peerDependencies: [
         declarePeerDependency(BylineToolbarExtension.name, {
             items: [

package/dist/plugins/lexical/index.d.ts

@@ -5,6 +5,6 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+export { TOGGLE_AI_DRAWER_COMMAND } from './commands';
 export { AiLexicalExtension } from './extension';
-export { AiPluginLexical, TOGGLE_AI_DRAWER_COMMAND } from './plugin';
 //# sourceMappingURL=index.d.ts.map

package/dist/plugins/lexical/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/lexical/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/lexical/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/plugins/lexical/index.js

@@ -5,5 +5,5 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+export { TOGGLE_AI_DRAWER_COMMAND } from './commands';
 export { AiLexicalExtension } from './extension';
-export { AiPluginLexical, TOGGLE_AI_DRAWER_COMMAND } from './plugin';

package/dist/plugins/lexical/plugin.d.ts

@@ -6,13 +6,5 @@
  * Copyright (c) Infonomic Company Limited
  */
 import * as React from 'react';
-export declare const TOGGLE_AI_DRAWER_COMMAND: import("lexical").LexicalCommand<unknown>;
-/**
- * Broadcasts the AI drawer's open/closed state so contributed UI (the
- * toolbar button) can show an active visual cue. Dispatched by the drawer
- * plugin whenever `open` changes — including closes triggered from the
- * drawer's own controls. Observers register a listener and return `false`.
- */
-export declare const AI_DRAWER_STATE_COMMAND: import("lexical").LexicalCommand<boolean>;
 export declare const AiPluginLexical: React.MemoExoticComponent<() => React.JSX.Element | undefined>;
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/lexical/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/lexical/plugin.tsx"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAqB9B,eAAO,MAAM,wBAAwB,2CAA4C,CAAA;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,2CAAoD,CAAA;AAUxF,eAAO,MAAM,eAAe,kCAAmC,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,SAAS,CAyY1F,CAAA"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/lexical/plugin.tsx"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA6B9B,eAAO,MAAM,eAAe,kCAAmC,KAAK,CAAC,GAAG,CAAC,OAAO,GAAG,SAAS,CAyY1F,CAAA"}

package/dist/plugins/lexical/plugin.js

@@ -13,19 +13,12 @@ import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext
 import { mergeRegister } from '@lexical/utils';
 import { 
 // CLEAR_EDITOR_COMMAND,
-COMMAND_PRIORITY_CRITICAL, COMMAND_PRIORITY_NORMAL, createCommand, SELECTION_CHANGE_COMMAND, } from 'lexical';
+COMMAND_PRIORITY_CRITICAL, COMMAND_PRIORITY_NORMAL, SELECTION_CHANGE_COMMAND, } from 'lexical';
 import { useAiPublicConfig } from '../../config/ai-provider';
 import { AiPluginBase } from '../ai-plugin-base';
+import { AI_DRAWER_STATE_COMMAND, TOGGLE_AI_DRAWER_COMMAND } from './commands';
 import { createEmptyEditorState } from './create-empty-editor-state';
 import { importHtmlToSerializedEditorState } from './import-html';
-export const TOGGLE_AI_DRAWER_COMMAND = createCommand('TOGGLE_AI_DRAWER_COMMAND');
-/**
- * Broadcasts the AI drawer's open/closed state so contributed UI (the
- * toolbar button) can show an active visual cue. Dispatched by the drawer
- * plugin whenever `open` changes — including closes triggered from the
- * drawer's own controls. Observers register a listener and return `false`.
- */
-export const AI_DRAWER_STATE_COMMAND = createCommand('AI_DRAWER_STATE_COMMAND');
 const emptyInstructionState = {
     prompt: '',
     editor: null,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/ai",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -66,9 +66,9 @@
     "react-error-boundary": "^6.1.1",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/richtext-lexical": "3.0.2",
-    "@byline/core": "3.0.2",
-    "@byline/ui": "3.0.2"
+    "@byline/core": "3.1.1",
+    "@byline/ui": "3.1.1",
+    "@byline/richtext-lexical": "3.1.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",