@plasius/ai 1.1.4 → 1.1.6

package/dist-cjs/platform/video-provider-platform.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVideoProviderPlatform = createVideoProviderPlatform;
+const node_perf_hooks_1 = require("node:perf_hooks");
+function createCompletionBase(type, model, requestor, durationMs) {
+    return {
+        partitionKey: requestor,
+        id: crypto.randomUUID(),
+        type,
+        model,
+        createdAt: new Date().toISOString(),
+        durationMs,
+        usage: {},
+    };
+}
+async function waitForCompletion(adapter, videoId, apiKey, maxRetries, delayMs) {
+    for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        const result = await adapter.getVideoResult(videoId, {
+            apiKey,
+            traceId: crypto.randomUUID(),
+        });
+        if (result.state === "completed" && result.videoUrl) {
+            return result.videoUrl;
+        }
+        if (result.state === "failed") {
+            throw new Error("Video generation failed in provider adapter.");
+        }
+    }
+    throw new Error("Timed out waiting for provider video completion.");
+}
+async function createVideoProviderPlatform(userId, props) {
+    const apiKey = props.apiKey.trim();
+    if (!apiKey) {
+        throw new Error("apiKey is required for createVideoProviderPlatform.");
+    }
+    const maxRetries = props.polling?.maxRetries ?? 20;
+    const delayMs = props.polling?.delayMs ?? 3000;
+    const chatWithAI = (_userId, _input, _context, _model) => {
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const synthesizeSpeech = (_userId, _input, _voice, _context, _model) => {
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const transcribeSpeech = (_userId, _input, _context, _model) => {
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const generateImage = (_userId, _input, _context, _model) => {
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const produceVideo = async (requestorId, prompt, image, _context, model) => {
+        const startedAt = node_perf_hooks_1.performance.now();
+        const uploaded = await props.adapter.uploadImage(image, {
+            apiKey,
+            traceId: crypto.randomUUID(),
+        });
+        const generated = await props.adapter.generateVideo({
+            imageId: uploaded.imageId,
+            prompt,
+            ...props.defaultVideoRequest,
+        }, {
+            apiKey,
+            traceId: crypto.randomUUID(),
+        });
+        const videoUrl = await waitForCompletion(props.adapter, generated.videoId, apiKey, maxRetries, delayMs);
+        const durationMs = node_perf_hooks_1.performance.now() - startedAt;
+        const base = createCompletionBase("video", model, requestorId, durationMs);
+        return {
+            ...base,
+            url: new URL(videoUrl),
+        };
+    };
+    const generateModel = (_userId, _input, _context, _model) => {
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const checkBalance = async (requestorId) => {
+        const startedAt = node_perf_hooks_1.performance.now();
+        const providerBalance = props.adapter.getBalance
+            ? await props.adapter.getBalance({
+                apiKey,
+                traceId: crypto.randomUUID(),
+            })
+            : {
+                monthlyCredit: 0,
+                packageCredit: 0,
+            };
+        const durationMs = node_perf_hooks_1.performance.now() - startedAt;
+        const base = createCompletionBase("balanceCompletion", "", requestorId, durationMs);
+        return {
+            ...base,
+            balance: providerBalance.monthlyCredit + providerBalance.packageCredit,
+        };
+    };
+    const currentBalance = (await checkBalance(userId)).balance;
+    return {
+        chatWithAI,
+        synthesizeSpeech,
+        transcribeSpeech,
+        generateImage,
+        produceVideo,
+        generateModel,
+        checkBalance,
+        currentBalance,
+    };
+}

package/docs/api-reference.md

@@ -12,6 +12,7 @@ Routing capability enum:
 - `Image`
 - `Video`
 - `Balance`
+- `Model`
 
 ## Core Interfaces
 
@@ -24,6 +25,7 @@ Contract for runtime adapters:
 - `transcribeSpeech(userId, input, context, model)`
 - `generateImage(userId, input, context, model)`
 - `produceVideo(userId, input, image, context, model)`
+- `generateModel(userId, input, context, model)`
 - `checkBalance(userId)`
 - `currentBalance`
 
@@ -51,8 +53,64 @@ Specialized variants:
 - `ImageCompletion`
 - `SpeechCompletion`
 - `VideoCompletion`
+- `ModelCompletion`
 - `BalanceCompletion`
 
+## Adapter Composition
+
+### `AICapabilityAdapter`
+
+Provider adapter contract with capability declarations and optional operation handlers:
+
+- `id`
+- `capabilities`
+- `chatWithAI(request)?`
+- `synthesizeSpeech(request)?`
+- `transcribeSpeech(request)?`
+- `generateImage(request)?`
+- `produceVideo(request)?`
+- `generateModel(request)?`
+- `checkBalance(request)?`
+
+### `createAdapterPlatform(userId, props)`
+
+Builds an `AIPlatform` by routing capability calls to registered adapters and injecting developer-supplied API keys from `props.apiKeys`.
+
+### `HttpClientPolicy`
+
+Shared HTTP resilience policy used by built-in adapters:
+
+- `maxAttempts?`
+- `timeoutMs?`
+- `baseDelayMs?`
+- `maxDelayMs?`
+- `jitterRatio?`
+- `respectRetryAfter?`
+- `retryableMethods?`
+- `retryableStatusCodes?`
+
+### `createOpenAIAdapter(options?)`
+
+Creates a built-in OpenAI adapter implementing:
+
+- `chatWithAI`
+- `synthesizeSpeech`
+- `transcribeSpeech`
+- `generateImage`
+- `generateModel`
+
+`options.httpPolicy` applies retry/timeout behavior to all OpenAI adapter HTTP requests.
+
+### `createGeminiAdapter(options?)`
+
+Creates a built-in Gemini adapter implementing:
+
+- `chatWithAI`
+- `generateImage`
+- `generateModel`
+
+`options.httpPolicy` applies retry/timeout behavior to all Gemini adapter HTTP requests.
+
 ## Exported Schemas
 
 - `completionSchema`
@@ -61,4 +119,5 @@ Specialized variants:
 - `imageCompletionSchema`
 - `speechCompletionSchema`
 - `videoCompletionSchema`
+- `modelCompletionSchema`
 - `balanceCompletionSchema`

package/docs/architecture.md

@@ -4,8 +4,11 @@
 
 - **Capability model**: `AICapability` describes the logical feature set.
 - **Platform contract**: `AIPlatform` defines the async operations required by a runtime adapter.
-- **Completion contracts**: typed completion outputs normalize chat/text/image/speech/video/balance results.
+- **Completion contracts**: typed completion outputs normalize chat/text/image/speech/video/model/balance results.
 - **Schema layer**: schema definitions ensure consistent metadata and persistence shape across runtimes.
+- **Adapter composition**: `createAdapterPlatform` routes capabilities across multiple adapters and injects API keys supplied by the package consumer.
+- **Built-in providers**: OpenAI and Gemini adapters are included for out-of-the-box capability wiring.
+- **Resilient transport**: adapters use a shared HTTP resilience policy (timeouts, exponential backoff + jitter, and `Retry-After` handling).
 
 ## Design Intention
 
@@ -14,6 +17,7 @@ This package is not tied to a single provider runtime. Host applications should:
 1. Implement or wrap an `AIPlatform` adapter.
 2. Keep provider credentials and network execution outside this package boundary.
 3. Emit normalized completion objects based on the exported contract types.
+4. Register per-provider API keys through `AdapterPlatformProps.apiKeys`.
 
 ## Current Boundaries
 

package/docs/providers.md

@@ -5,22 +5,40 @@ specific provider implementation.
 
 ## Recommended Integration Pattern
 
-1. Build provider adapters in your host app or a dedicated integration package.
-2. Implement `AIPlatform` for each provider.
+1. Use built-in adapters (`createOpenAIAdapter`, `createGeminiAdapter`) or build provider adapters in your host app.
+2. Compose adapters with `createAdapterPlatform(...)` and an `apiKeys` map keyed by adapter id.
 3. Keep provider secrets in runtime environment variables, not in UI bundles.
 4. Normalize results into exported completion models.
 
+## Built-In Adapters
+
+- `createOpenAIAdapter(options?)`
+  - Default adapter id: `openai`
+  - Capabilities: chat, speech synthesis, transcription, image generation, model generation
+- `createGeminiAdapter(options?)`
+  - Default adapter id: `gemini`
+  - Capabilities: chat, image generation, model generation
+
+## Network Citizenship Defaults
+
+Built-in adapters and the generic HTTP video adapter apply resilient request behavior by default:
+
+- Timeout per request (`30s` default).
+- Exponential backoff with jitter for transient failures.
+- Retry on common transient statuses (`408`, `409`, `425`, `429`, `500`, `502`, `503`, `504`).
+- Honor `Retry-After` when present.
+
+Override these values using `httpPolicy` in adapter options.
+
 ## Adapter Checklist
 
 - Map provider-specific response IDs to `Completion.id`.
 - Populate `durationMs` from measured execution time.
 - Set `partitionKey` to your stable user/session key.
 - Attach provider usage/cost metadata to `usage`.
+- Use stable adapter ids and provide matching API keys in `AdapterPlatformProps.apiKeys`.
 - Return strongly typed completion variants for each capability.
 
 ## Stability Notes
 
-- `src/platform/openai.ts` and `src/platform/pixelverse.ts` are implementation
-  work areas and should be treated as provisional until explicit public export
-  and API freeze.
-- Prefer composition from host apps until adapter APIs are finalized.
+- Prefer `createOpenAIAdapter` and `createGeminiAdapter` for out-of-the-box provider integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/ai",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Plasius AI functions providing chatbot, text-to-speech, speech-to-text, and AI-generated images and videos",
   "keywords": [
     "chatbot",
@@ -31,7 +31,9 @@
     "build:cjs": "tsc -p tsconfig.json --module commonjs --moduleResolution node --outDir dist-cjs --tsBuildInfoFile dist-cjs/tsconfig.tsbuildinfo",
     "lint": "eslint .",
     "prepare": "npm run build",
-    "demo:run": "npm run build && node demo/example.mjs"
+    "demo:run": "npm run build && node demo/example.mjs",
+    "pack:check": "node scripts/verify-public-package.cjs",
+    "prepublishOnly": "npm run build && npm run pack:check"
   },
   "author": "Plasius LTD <development@plasius.co.uk>",
   "license": "MIT",
@@ -42,7 +44,6 @@
     "@plasius/schema": "^1.2.1"
   },
   "peerDependencies": {
-    "openai": "^5.23.2",
     "react": "^19.1.0"
   },
   "devDependencies": {
@@ -56,9 +57,8 @@
     "ajv": "^6.12.6",
     "eslint": "^10.0.1",
     "npm-run-all": "^1.1.3",
-    "openai": "^5.23.2",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
     "react-router-dom": "^7.13.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",

package/src/components/pixelverse/balance.tsx

@@ -1,61 +1,48 @@
 import { useEffect, useState } from "react";
-import { v4 as uuidv4 } from "uuid";
+import type { ProviderBalance, VideoProviderAdapter } from "../../platform/video-provider-adapter.js";
 import styles from "./balance.module.css";
 
-interface BalanceResponse {
-  account_id: number;
-  credit_monthly: number;
-  credit_package: number;
+export interface BalanceProps {
+  apiKey: string;
+  adapter: VideoProviderAdapter;
+  refreshMs?: number;
 }
 
-interface BalanceApiResponse {
-  Resp?: BalanceResponse;
-}
-
-export default function Balance({ apiKey }: { apiKey: string }) {
-  const [balance, setBalance] = useState<BalanceResponse | null>(null);
+export default function Balance({ apiKey, adapter, refreshMs = 600000 }: BalanceProps) {
+  const [balance, setBalance] = useState<ProviderBalance | null>(null);
 
   const fetchBalance = async (): Promise<void> => {
+    if (!adapter.getBalance) {
+      setBalance({ monthlyCredit: 0, packageCredit: 0 });
+      return;
+    }
+
     try {
-      const response = await fetch("/pixelapi/openapi/v2/account/balance", {
-        method: "GET",
-        headers: {
-          "API-KEY": apiKey,
-          "AI-trace-ID": uuidv4(),
-          Accept: "application/json",
-          "Content-Type": "application/json",
-        },
-        referrerPolicy: "no-referrer",
+      const value = await adapter.getBalance({
+        apiKey,
+        traceId: crypto.randomUUID(),
       });
-
-      if (!response.ok) {
-        console.error("Failed to fetch balance:", response.status, response.statusText);
-        return;
-      }
-
-      const data = (await response.json()) as unknown as BalanceApiResponse;
-      if (data?.Resp) {
-        setBalance(data.Resp);
-      }
+      setBalance(value);
     } catch (err) {
       console.error("fetchBalance() error", err);
     }
   };
 
   useEffect(() => {
-    void fetchBalance(); // initial load
+    void fetchBalance();
     const intervalId = setInterval(() => {
       void fetchBalance();
-    }, 600000);
+    }, refreshMs);
+
     return () => clearInterval(intervalId);
-  }, [apiKey]);
+  }, [apiKey, adapter, refreshMs]);
 
   return (
     <div className={styles.balance_container}>
       {balance ? (
         <div>
-          <p>Monthly Credit: {balance.credit_monthly}</p>
-          <p>Package Credit: {balance.credit_package}</p>
+          <p>Monthly Credit: {balance.monthlyCredit}</p>
+          <p>Package Credit: {balance.packageCredit}</p>
         </div>
       ) : (
         <p>Loading balance...</p>

package/src/components/pixelverse/index.ts

@@ -1,2 +1,2 @@
 export * from "./balance.js";
-export * from "./pixelverseeditor.js";
+export * from "./video-generation-editor.js";

package/src/components/pixelverse/video-generation-editor.tsx

@@ -0,0 +1,164 @@
+import React, { useState } from "react";
+import Balance from "./balance.js";
+import type {
+  VideoGenerationRequest,
+  VideoProviderAdapter,
+} from "../../platform/video-provider-adapter.js";
+
+export interface VideoGenerationEditorProps {
+  apiKey: string;
+  adapter: VideoProviderAdapter;
+  onVideoGenerated?: (videoUrl: string) => void;
+  initialRequest?: Partial<Omit<VideoGenerationRequest, "imageId">>;
+}
+
+const defaultRequest: Omit<VideoGenerationRequest, "imageId"> = {
+  prompt: "",
+  model: "standard",
+  motionMode: "normal",
+  quality: "720p",
+  durationSeconds: 5,
+  watermark: false,
+};
+
+function toRequest(
+  overrides?: Partial<Omit<VideoGenerationRequest, "imageId">>
+): Omit<VideoGenerationRequest, "imageId"> {
+  return {
+    ...defaultRequest,
+    ...overrides,
+  };
+}
+
+async function waitForVideoCompletion(
+  adapter: VideoProviderAdapter,
+  videoId: number,
+  apiKey: string,
+  maxRetries = 20,
+  delayMs = 3000
+): Promise<string> {
+  for (let attempt = 0; attempt < maxRetries; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    const result = await adapter.getVideoResult(videoId, {
+      apiKey,
+      traceId: crypto.randomUUID(),
+    });
+
+    if (result.state === "completed" && result.videoUrl) {
+      return result.videoUrl;
+    }
+
+    if (result.state === "failed") {
+      throw new Error("Video generation failed.");
+    }
+  }
+
+  throw new Error("Timed out waiting for video generation result.");
+}
+
+export function VideoGenerationEditor({
+  apiKey,
+  adapter,
+  onVideoGenerated,
+  initialRequest,
+}: VideoGenerationEditorProps) {
+  const [videoUrl, setVideoUrl] = useState("");
+  const [selectedFile, setSelectedFile] = useState<File | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [videoReady, setVideoReady] = useState(false);
+  const [request, setRequest] = useState<Omit<VideoGenerationRequest, "imageId">>(
+    toRequest(initialRequest)
+  );
+
+  const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0] ?? null;
+    setSelectedFile(file);
+  };
+
+  const handleRegenerate = () => {
+    void handleUploadProcess();
+  };
+
+  const handleUploadProcess = async () => {
+    if (!selectedFile) {
+      return;
+    }
+
+    setLoading(true);
+    setVideoReady(false);
+
+    try {
+      const uploaded = await adapter.uploadImage(selectedFile, {
+        apiKey,
+        traceId: crypto.randomUUID(),
+      });
+
+      const generated = await adapter.generateVideo(
+        {
+          ...request,
+          imageId: uploaded.imageId,
+        },
+        {
+          apiKey,
+          traceId: crypto.randomUUID(),
+        }
+      );
+
+      const generatedUrl = await waitForVideoCompletion(adapter, generated.videoId, apiKey);
+      setVideoUrl(generatedUrl);
+      setVideoReady(true);
+      onVideoGenerated?.(generatedUrl);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div>
+      <Balance apiKey={apiKey} adapter={adapter} />
+      {!videoReady && !selectedFile && (
+        <div>
+          <p>Drag/Drop or Click HERE to upload</p>
+          <input
+            title="Upload Image"
+            type="file"
+            accept=".jpg,.jpeg,.png,.webp"
+            onChange={handleFileChange}
+          />
+        </div>
+      )}
+
+      {!videoReady ? (
+        <div>
+          <label>
+            Prompt
+            <textarea
+              value={request.prompt}
+              onChange={(event) =>
+                setRequest((previous) => ({
+                  ...previous,
+                  prompt: event.target.value,
+                }))
+              }
+            />
+          </label>
+        </div>
+      ) : null}
+
+      {loading && <div>Loading...</div>}
+
+      {!videoReady && selectedFile && !loading && (
+        <button onClick={handleUploadProcess}>Start Upload</button>
+      )}
+
+      {videoReady && (
+        <div>
+          <video src={videoUrl} controls />
+          <button onClick={handleRegenerate}>Regenerate</button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default VideoGenerationEditor;