@nightowlsdev/model-openai 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,101 @@
+# @nightowlsdev/model-openai
+
+> Swappable `modelFactory` provider plugin — wire OpenAI models into a Night Owls swarm with one line; `owl install model-openai` does the rest.
+
+This package is a thin adapter between the Night Owls core and OpenAI's API. It exposes a `modelFactory` factory (`openaiModels()`) that maps any OpenAI model id to an AI SDK `LanguageModelV3`, and a declarative `nightOwlsPlugin` manifest that the `@nightowlsdev/cli` uses for scaffolding, `owl install`, and `owl model-openai info`.
+
+Model provider plugins are **mutually exclusive** — install exactly one `@nightowlsdev/model-*` package per swarm. They carry zero `@nightowlsdev/core` or `@mastra/*` dependencies and are safe to tree-shake.
+
+## Install
+
+```sh
+pnpm add @nightowlsdev/model-openai
+```
+
+No required peer dependencies. `@ai-sdk/openai` is a direct dependency and is included.
+
+If you are using the CLI, the recommended installation path is:
+
+```sh
+owl install model-openai
+```
+
+This runs the plugin's `init` handler, sets up the config marker, and prompts for `OPENAI_API_KEY` + `MODEL_ID`.
+
+## Usage
+
+```ts
+import { openaiModels } from "@nightowlsdev/model-openai";
+import { defineSwarm } from "@nightowlsdev/core";
+
+const swarm = defineSwarm({
+  modelFactory: openaiModels(), // reads OPENAI_API_KEY from env
+  models: {
+    allow: [process.env.MODEL_ID ?? "gpt-4o"],
+  },
+  agents: [/* … */],
+});
+```
+
+Pass an explicit key instead of relying on the environment:
+
+```ts
+const swarm = defineSwarm({
+  modelFactory: openaiModels({ apiKey: "sk-…" }),
+  // …
+});
+```
+
+## API
+
+### `openaiModels(opts?) → (modelId: string) => LanguageModelV3`
+
+```ts
+function openaiModels(opts?: { apiKey?: string }): (modelId: string) => unknown;
+```
+
+Returns a `modelFactory` function compatible with `defineSwarm`. Internally calls `createOpenAI` from `@ai-sdk/openai`.
+
+- `opts.apiKey` — optional override; when omitted, `@ai-sdk/openai` reads `OPENAI_API_KEY` from the environment.
+- The returned factory accepts any OpenAI model id string (e.g. `"gpt-4o"`, `"gpt-4o-mini"`, `"o3"`) and returns the corresponding AI SDK model instance.
+
+### `nightOwlsPlugin`
+
+```ts
+export const nightOwlsPlugin: {
+  name: "model-openai";
+  version: string;
+  kind: "model";
+  pkg: "@nightowlsdev/model-openai";
+  description: string;
+  env: Array<{ key: string; example: string; comment: string }>;
+  config: { import: string; snippet: string; marker: "model" };
+  init: (ctx: { cwd: string; log: (m: string) => void }) => void;
+  commands: Array<{ name: string; description: string; run: (ctx: Ctx) => void }>;
+}
+```
+
+The declarative plugin manifest consumed by `@nightowlsdev/cli`. It is **data-only** — it does not import `@nightowlsdev/cli` (no dependency cycle). Key fields:
+
+| Field | Value |
+|---|---|
+| `kind` | `"model"` |
+| `config.marker` | `"model"` — the `// nightowls:model` marker in `nightowls.config.ts` that `owl install` replaces |
+| `config.snippet` | `modelFactory = openaiModels();` |
+| `env[].key` | `OPENAI_API_KEY`, `MODEL_ID` |
+
+## Configuration / Environment
+
+| Variable | Required | Example | Purpose |
+|---|---|---|---|
+| `OPENAI_API_KEY` | Yes (unless passed via `opts.apiKey`) | `sk-…` | OpenAI API key; read by `@ai-sdk/openai` at call time |
+| `MODEL_ID` | Recommended | `gpt-4o` | The model id to place in `models.allow` in `nightowls.config.ts` |
+
+Set both in `.env.local` (or your environment). `MODEL_ID` is not read by this package at runtime — it is a convention used by the config scaffold and `owl model-openai info` to communicate which model id to use.
+
+## Plugin manifest
+
+This package exports `nightOwlsPlugin` with `kind: "model"`. The CLI consumes it in two ways:
+
+- **`owl install model-openai`** — runs `init`, injects `import { openaiModels } from "@nightowlsdev/model-openai"` at the top of `nightowls.config.ts`, and replaces the `// nightowls:model` marker with `modelFactory = openaiModels();`.
+- **`owl model-openai info`** — runs the `"info"` command, which prints the required env vars (`OPENAI_API_KEY`, `MODEL_ID`) and the config snippet without making any network calls.

package/dist/index.cjs

@@ -21,7 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   nightOwlsPlugin: () => nightOwlsPlugin,
-  openaiModels: () => openaiModels
+  openaiEmbeddings: () => openaiEmbeddings,
+  openaiModels: () => openaiModels,
+  pinEmbeddingDimensions: () => pinEmbeddingDimensions
 });
 module.exports = __toCommonJS(index_exports);
 var import_openai = require("@ai-sdk/openai");
@@ -29,6 +31,26 @@ function openaiModels(opts = {}) {
   const provider = (0, import_openai.createOpenAI)(opts.apiKey ? { apiKey: opts.apiKey } : {});
   return (modelId) => provider(modelId);
 }
+function openaiEmbeddings(opts) {
+  const provider = (0, import_openai.createOpenAI)(opts.apiKey ? { apiKey: opts.apiKey } : {});
+  const model = provider.embedding(opts.model);
+  return opts.dimensions === void 0 ? model : pinEmbeddingDimensions(model, "openai", opts.dimensions);
+}
+function pinEmbeddingDimensions(model, providerKey, dimensions) {
+  return new Proxy(model, {
+    get(target, prop, recv) {
+      if (prop !== "doEmbed") return Reflect.get(target, prop, recv);
+      const orig = Reflect.get(target, prop, recv);
+      return (options) => {
+        const po = options?.providerOptions ?? {};
+        return orig.call(target, {
+          ...options,
+          providerOptions: { ...po, [providerKey]: { ...po[providerKey] ?? {}, dimensions } }
+        });
+      };
+    }
+  });
+}
 var nightOwlsPlugin = {
   name: "model-openai",
   version: "0.0.0",
@@ -61,5 +83,7 @@ var nightOwlsPlugin = {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   nightOwlsPlugin,
-  openaiModels
+  openaiEmbeddings,
+  openaiModels,
+  pinEmbeddingDimensions
 });

package/dist/index.d.cts

@@ -9,6 +9,29 @@
 declare function openaiModels(opts?: {
     apiKey?: string;
 }): (modelId: string) => unknown;
+/** Options for {@link openaiEmbeddings}. `model` is the embedding model id (e.g. `text-embedding-3-small`);
+ *  `dimensions` (optional) PINS the output vector size to match the host's pgvector column — when set it is
+ *  injected as a provider option on every embed call, so it takes effect even through Mastra's memory recall. */
+interface OpenAIEmbeddingsOpts {
+    apiKey?: string;
+    model: string;
+    dimensions?: number;
+}
+/**
+ * FR-011 — an EMBEDDING-model factory parallel to {@link openaiModels}, so a RAG/memory consumer gets its
+ * embedder from the SAME provider adapter it already installed (no bespoke `fetch` to the embeddings endpoint).
+ * Fill `MemoryConfig.embedder` with the return value, or pass it to the AI SDK's `embed`/`embedMany`.
+ *
+ * @example
+ *   memory: { embedder: openaiEmbeddings({ model: "text-embedding-3-small", dimensions: 1536 }) }
+ */
+declare function openaiEmbeddings(opts: OpenAIEmbeddingsOpts): unknown;
+/**
+ * Wrap an AI-SDK embedding model so every `doEmbed` call carries `providerOptions.<key>.dimensions`, pinning the
+ * output vector size without depending on the call site to pass it (the host's caller, or Mastra memory, won't).
+ * A `Proxy` preserves the model's getters/prototype (a spread would drop them).
+ */
+declare function pinEmbeddingDimensions(model: unknown, providerKey: string, dimensions: number): unknown;
 /** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
 type Ctx = {
     cwd: string;
@@ -52,4 +75,4 @@ declare const nightOwlsPlugin: {
     }];
 };
 
-export { nightOwlsPlugin, openaiModels };
+export { type OpenAIEmbeddingsOpts, nightOwlsPlugin, openaiEmbeddings, openaiModels, pinEmbeddingDimensions };

package/dist/index.d.ts

@@ -9,6 +9,29 @@
 declare function openaiModels(opts?: {
     apiKey?: string;
 }): (modelId: string) => unknown;
+/** Options for {@link openaiEmbeddings}. `model` is the embedding model id (e.g. `text-embedding-3-small`);
+ *  `dimensions` (optional) PINS the output vector size to match the host's pgvector column — when set it is
+ *  injected as a provider option on every embed call, so it takes effect even through Mastra's memory recall. */
+interface OpenAIEmbeddingsOpts {
+    apiKey?: string;
+    model: string;
+    dimensions?: number;
+}
+/**
+ * FR-011 — an EMBEDDING-model factory parallel to {@link openaiModels}, so a RAG/memory consumer gets its
+ * embedder from the SAME provider adapter it already installed (no bespoke `fetch` to the embeddings endpoint).
+ * Fill `MemoryConfig.embedder` with the return value, or pass it to the AI SDK's `embed`/`embedMany`.
+ *
+ * @example
+ *   memory: { embedder: openaiEmbeddings({ model: "text-embedding-3-small", dimensions: 1536 }) }
+ */
+declare function openaiEmbeddings(opts: OpenAIEmbeddingsOpts): unknown;
+/**
+ * Wrap an AI-SDK embedding model so every `doEmbed` call carries `providerOptions.<key>.dimensions`, pinning the
+ * output vector size without depending on the call site to pass it (the host's caller, or Mastra memory, won't).
+ * A `Proxy` preserves the model's getters/prototype (a spread would drop them).
+ */
+declare function pinEmbeddingDimensions(model: unknown, providerKey: string, dimensions: number): unknown;
 /** Structural context for this adapter's pure command handlers — matches the CLI's PluginCommandContext. */
 type Ctx = {
     cwd: string;
@@ -52,4 +75,4 @@ declare const nightOwlsPlugin: {
     }];
 };
 
-export { nightOwlsPlugin, openaiModels };
+export { type OpenAIEmbeddingsOpts, nightOwlsPlugin, openaiEmbeddings, openaiModels, pinEmbeddingDimensions };

package/dist/index.js

@@ -4,6 +4,26 @@ function openaiModels(opts = {}) {
   const provider = createOpenAI(opts.apiKey ? { apiKey: opts.apiKey } : {});
   return (modelId) => provider(modelId);
 }
+function openaiEmbeddings(opts) {
+  const provider = createOpenAI(opts.apiKey ? { apiKey: opts.apiKey } : {});
+  const model = provider.embedding(opts.model);
+  return opts.dimensions === void 0 ? model : pinEmbeddingDimensions(model, "openai", opts.dimensions);
+}
+function pinEmbeddingDimensions(model, providerKey, dimensions) {
+  return new Proxy(model, {
+    get(target, prop, recv) {
+      if (prop !== "doEmbed") return Reflect.get(target, prop, recv);
+      const orig = Reflect.get(target, prop, recv);
+      return (options) => {
+        const po = options?.providerOptions ?? {};
+        return orig.call(target, {
+          ...options,
+          providerOptions: { ...po, [providerKey]: { ...po[providerKey] ?? {}, dimensions } }
+        });
+      };
+    }
+  });
+}
 var nightOwlsPlugin = {
   name: "model-openai",
   version: "0.0.0",
@@ -35,5 +55,7 @@ var nightOwlsPlugin = {
 };
 export {
   nightOwlsPlugin,
-  openaiModels
+  openaiEmbeddings,
+  openaiModels,
+  pinEmbeddingDimensions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightowlsdev/model-openai",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {