@plasius/ai 1.0.3

package/dist-cjs/platform/index.d.ts

@@ -0,0 +1,76 @@
+import type { FieldBuilder } from "@plasius/schema";
+export declare const completionSchema: import("@plasius/schema").Schema<{
+    id: FieldBuilder<string, string>;
+    type: FieldBuilder<string, string>;
+    model: FieldBuilder<string, string>;
+    durationMs: FieldBuilder<number, number>;
+    createdAt: FieldBuilder<string, string>;
+    partitionKey: FieldBuilder<string, string>;
+    usage: FieldBuilder<Record<string, number>, Record<string, FieldBuilder<number, number>>>;
+}>;
+export interface Completion {
+    id: string;
+    partitionKey: string;
+    type: string;
+    model: string;
+    durationMs: number;
+    createdAt: string;
+    usage?: Record<string, number>;
+}
+export declare const chatCompletionSchema: import("@plasius/schema").Schema<{
+    message: FieldBuilder<string, string>;
+    outputUser: FieldBuilder<string, string>;
+}>;
+export interface ChatCompletion extends Completion {
+    message: string;
+    outputUser: string;
+}
+export declare const textCompletionSchema: import("@plasius/schema").Schema<{
+    message: FieldBuilder<string, string>;
+}>;
+export interface TextCompletion extends Completion {
+    message: string;
+}
+export declare const imageCompletionSchema: import("@plasius/schema").Schema<{
+    url: FieldBuilder<URL, string>;
+}>;
+export interface ImageCompletion extends Completion {
+    url: URL;
+}
+export declare const speechCompletionSchema: import("@plasius/schema").Schema<{
+    url: FieldBuilder<URL, string>;
+}>;
+export interface SpeechCompletion extends Completion {
+    url: URL;
+}
+export declare const videoCompletionSchema: import("@plasius/schema").Schema<{
+    url: FieldBuilder<URL, string>;
+}>;
+export interface VideoCompletion extends Completion {
+    url: URL;
+}
+export declare const balanceCompletionSchema: import("@plasius/schema").Schema<{
+    balance: FieldBuilder<number, number>;
+}>;
+export interface BalanceCompletion extends Completion {
+    balance: number;
+}
+export declare enum AICapability {
+    Chat = 0,
+    Text = 1,
+    Speech = 2,
+    Image = 3,
+    Video = 4,
+    Balance = 5
+}
+export interface AIPlatform {
+    canHandle?: (userId: string, capabilities: AICapability[]) => Promise<boolean>;
+    chatWithAI: (userId: string, input: string, context: string, model: string) => Promise<ChatCompletion>;
+    synthesizeSpeech: (userId: string, input: string, voice: string, context: string, model: string) => Promise<SpeechCompletion>;
+    transcribeSpeech: (userId: string, input: Buffer, context: string, model: string) => Promise<TextCompletion>;
+    generateImage: (userId: string, input: string, context: string, model: string) => Promise<ImageCompletion>;
+    produceVideo: (userId: string, imput: string, image: URL, context: string, model: string) => Promise<VideoCompletion>;
+    checkBalance: (userId: string) => Promise<BalanceCompletion>;
+    currentBalance: number;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist-cjs/platform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/platform/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,iBAAiB,CAAC;AAEjE,eAAO,MAAM,gBAAgB;;;;;;;;EA0C5B,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,eAAO,MAAM,oBAAoB;;;EAmBhC,CAAC;AAEF,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,oBAAoB;;EAehC,CAAC;AAEF,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,qBAAqB;;EAgBjC,CAAC;AAEF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,GAAG,EAAE,GAAG,CAAC;CACV;AAED,eAAO,MAAM,sBAAsB;;EAgBlC,CAAC;AAEF,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,GAAG,EAAE,GAAG,CAAC;CACV;AAED,eAAO,MAAM,qBAAqB;;EAgBjC,CAAC;AAEF,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,GAAG,EAAE,GAAG,CAAC;CACV;AAED,eAAO,MAAM,uBAAuB;;EAYnC,CAAC;AAEF,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oBAAY,YAAY;IACtB,IAAI,IAAA;IACJ,IAAI,IAAA;IACJ,MAAM,IAAA;IACN,KAAK,IAAA;IACL,KAAK,IAAA;IACL,OAAO,IAAA;CACR;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,CACV,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,YAAY,EAAE,KACzB,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,UAAU,EAAE,CACV,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,gBAAgB,EAAE,CAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B,gBAAgB,EAAE,CAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,aAAa,EAAE,CACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9B,YAAY,EAAE,CACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7D,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist-cjs/platform/index.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AICapability = exports.balanceCompletionSchema = exports.videoCompletionSchema = exports.speechCompletionSchema = exports.imageCompletionSchema = exports.textCompletionSchema = exports.chatCompletionSchema = exports.completionSchema = void 0;
+const schema_1 = require("@plasius/schema");
+exports.completionSchema = (0, schema_1.createSchema)({
+    id: schema_1.field
+        .string()
+        .description("A unique ID for this completion")
+        .version("1.0"),
+    type: schema_1.field
+        .string()
+        .description("The type of completion (e.g. 'chat', 'text', 'speech')")
+        .version("1.0"),
+    model: schema_1.field
+        .string()
+        .description("The model used to generate this completion")
+        .version("1.0"),
+    durationMs: schema_1.field
+        .number()
+        .description("How long the AI task took in milliseconds")
+        .version("1.0"),
+    createdAt: schema_1.field
+        .string()
+        .description("ISO timestamp when the completion was created")
+        .version("1.0"),
+    partitionKey: schema_1.field
+        .string()
+        .description("User or system identifier that made the request")
+        .version("1.0"),
+    usage: schema_1.field
+        .object({})
+        .description("Optional usage metrics like token count or cost")
+        .version("1.0")
+        .optional()
+        .as(),
+}, "completion", {
+    version: "1.0",
+    piiEnforcement: "none",
+    table: "completions",
+    schemaValidator: () => {
+        return true;
+    },
+});
+exports.chatCompletionSchema = (0, schema_1.createSchema)({
+    message: schema_1.field
+        .string()
+        .description("The response from the AI")
+        .version("1.0"),
+    outputUser: schema_1.field
+        .string()
+        .description("The 'actor' who is chatting")
+        .version("1.0"),
+}, "chatCompletion", {
+    version: "1.0",
+    table: "completions",
+    schemaValidator: () => {
+        return true;
+    },
+});
+exports.textCompletionSchema = (0, schema_1.createSchema)({
+    message: schema_1.field
+        .string()
+        .description("The response from the AI")
+        .version("1.0"),
+}, "textCompletion", {
+    version: "1.0",
+    table: "completions",
+    schemaValidator: () => {
+        return true;
+    },
+});
+exports.imageCompletionSchema = (0, schema_1.createSchema)({
+    url: schema_1.field
+        .string()
+        .description("The response from the AI")
+        .version("1.0")
+        .as(),
+}, "imageCompletion", {
+    version: "1.0",
+    table: "completions",
+    schemaValidator: () => {
+        return true;
+    },
+});
+exports.speechCompletionSchema = (0, schema_1.createSchema)({
+    url: schema_1.field
+        .string()
+        .description("The response from the AI")
+        .version("1.0")
+        .as(),
+}, "speechCompletion", {
+    version: "1.0",
+    table: "completions",
+    schemaValidator: () => {
+        return true;
+    },
+});
+exports.videoCompletionSchema = (0, schema_1.createSchema)({
+    url: schema_1.field
+        .string()
+        .description("The response from the AI")
+        .version("1.0")
+        .as(),
+}, "videoCompletion", {
+    version: "1.0",
+    table: "completions",
+    schemaValidator: () => {
+        return true;
+    },
+});
+exports.balanceCompletionSchema = (0, schema_1.createSchema)({
+    balance: schema_1.field.number().description("Current balance").version("1.0"),
+}, "balanceCompletion", {
+    version: "1.0",
+    table: "completions",
+    schemaValidator: () => {
+        return true;
+    },
+});
+var AICapability;
+(function (AICapability) {
+    AICapability[AICapability["Chat"] = 0] = "Chat";
+    AICapability[AICapability["Text"] = 1] = "Text";
+    AICapability[AICapability["Speech"] = 2] = "Speech";
+    AICapability[AICapability["Image"] = 3] = "Image";
+    AICapability[AICapability["Video"] = 4] = "Video";
+    AICapability[AICapability["Balance"] = 5] = "Balance";
+})(AICapability || (exports.AICapability = AICapability = {}));

package/dist-cjs/platform/openai.d.ts

@@ -0,0 +1,8 @@
+import type { AIPlatform } from "./index.js";
+export interface OpenAIPlatformProps {
+    openaiAPIKey: string;
+    openaiProjectKey: string;
+    openaiOrgID: string;
+}
+export declare function OpenAIPlatform(userId: string, props: OpenAIPlatformProps): Promise<AIPlatform>;
+//# sourceMappingURL=openai.d.ts.map

package/dist-cjs/platform/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/platform/openai.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EAQX,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,UAAU,CAAC,CAoGrB"}

package/dist-cjs/platform/openai.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIPlatform = OpenAIPlatform;
+const openai_1 = __importDefault(require("openai"));
+const react_1 = require("react");
+async function OpenAIPlatform(userId, props) {
+    const openai = new openai_1.default({
+        apiKey: props.openaiAPIKey,
+        project: props.openaiProjectKey,
+        organization: props.openaiOrgID,
+        dangerouslyAllowBrowser: false,
+    });
+    void openai;
+    function baseCompletionData(type, model, requestor, duration) {
+        return {
+            partitionKey: requestor,
+            id: crypto.randomUUID(),
+            type,
+            model,
+            createdAt: new Date().toISOString(),
+            durationMs: duration,
+            usage: {},
+        };
+    }
+    const chatWithAI = (userId, input, context, model) => {
+        void [input, context, model];
+        const base = baseCompletionData("chat", "model", userId, 0);
+        return Promise.resolve({ ...base, message: "Something", outputUser: "" });
+    };
+    const synthesizeSpeech = (userId, input, voice, context, model) => {
+        void [input, voice, context, model];
+        const base = baseCompletionData("chat", "model", userId, 0);
+        return Promise.resolve({ ...base, url: new URL("Something") });
+    };
+    const transcribeSpeech = (userId, input, context, model) => {
+        void [input, context, model];
+        const base = baseCompletionData("chat", "model", userId, 0);
+        return Promise.resolve({ ...base, message: "Something" });
+    };
+    const generateImage = (userId, input, context, model) => {
+        void [input, context, model];
+        const base = baseCompletionData("chat", "model", userId, 0);
+        return Promise.resolve({ ...base, url: new URL("Something") });
+    };
+    const produceVideo = (userId, imput, image, context, model) => {
+        void [imput, image, context, model];
+        const base = baseCompletionData("chat", "model", userId, 0);
+        return Promise.resolve({ ...base, url: new URL("Something") });
+    };
+    const checkBalance = (userId) => {
+        const base = baseCompletionData("balanceCompletion", "", userId, 0);
+        return Promise.resolve({ ...base, balance: 0.0 });
+    };
+    const [currentBalance] = (0, react_1.useState)((await checkBalance(userId)).balance);
+    return {
+        chatWithAI,
+        synthesizeSpeech,
+        transcribeSpeech,
+        generateImage,
+        produceVideo,
+        checkBalance,
+        currentBalance,
+    };
+}

package/dist-cjs/platform/pixelverse.d.ts

@@ -0,0 +1,6 @@
+import type { AIPlatform } from "./index.js";
+export interface PixelVersePlatformProps {
+    pixelVerseAPIKey: string;
+}
+export declare function PixelVersePlatform(userId: string, props: PixelVersePlatformProps): Promise<AIPlatform>;
+//# sourceMappingURL=pixelverse.d.ts.map

package/dist-cjs/platform/pixelverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixelverse.d.ts","sourceRoot":"","sources":["../../src/platform/pixelverse.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,UAAU,EAQX,MAAM,YAAY,CAAC;AAmBpB,MAAM,WAAW,uBAAuB;IACtC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,UAAU,CAAC,CA8QrB"}

package/dist-cjs/platform/pixelverse.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PixelVersePlatform = PixelVersePlatform;
+const uuid_1 = require("uuid");
+const perf_hooks_1 = require("perf_hooks");
+const react_1 = require("react");
+async function PixelVersePlatform(userId, props) {
+    async function uploadImage(image, apiKey) {
+        const headers = new Headers();
+        headers.append("API-KEY", apiKey);
+        headers.append("Ai-trace-id", (0, uuid_1.v4)());
+        headers.append("Access-Control-Allow-Origin", "*");
+        const formData = new FormData();
+        if (image instanceof File) {
+            formData.append("image", image, "");
+        }
+        else {
+            const blob = await fetch(image.toString()).then((r) => r.blob());
+            formData.append("image", blob, "image-from-url");
+        }
+        // pixelapi is proxied through the vite.config.ts file
+        // to avoid CORS issues and to allow for local development
+        const response = await fetch("/pixelapi/openapi/v2/image/upload", {
+            method: "POST",
+            headers,
+            body: formData,
+            redirect: "follow",
+        });
+        const data = (await response.json());
+        return data;
+    }
+    async function generateVideo(imgId, prompt, apiKey, seed, template_id, negative_prompt) {
+        const headers = new Headers();
+        headers.append("API-KEY", apiKey);
+        headers.append("Ai-trace-id", (0, uuid_1.v4)());
+        headers.append("Content-Type", "application/json");
+        headers.append("Access-Control-Allow-Origin", "*");
+        headers.append("Accept", "application/json");
+        const values = {
+            duration: 5,
+            img_id: imgId,
+            model: "v3.5",
+            motion_mode: "normal",
+            prompt: prompt,
+            quality: "720p",
+            water_mark: false,
+        };
+        if (seed) {
+            values.seed = seed;
+        }
+        if (template_id) {
+            values.template_id = template_id;
+        }
+        if (negative_prompt) {
+            values.negative_prompt = negative_prompt;
+        }
+        const body = JSON.stringify(values);
+        // pixelapi is proxied through the vite.config.ts file
+        // to avoid CORS issues and to allow for local development
+        const response = await fetch("/pixelapi/openapi/v2/video/img/generate", {
+            method: "POST",
+            headers: headers,
+            referrerPolicy: "no-referrer",
+            body,
+        });
+        const data = (await response.json());
+        return data;
+    }
+    async function checkVideoStatus(id, apiKey) {
+        const headers = new Headers();
+        headers.append("API-KEY", apiKey);
+        headers.append("Ai-trace-id", (0, uuid_1.v4)());
+        headers.append("Access-Control-Allow-Origin", "*");
+        headers.append("Accept", "application/json");
+        // pixelapi is proxied through the vite.config.ts file
+        // to avoid CORS issues and to allow for local development
+        const response = await fetch(`/pixelapi/openapi/v2/video/result/${id}`, {
+            method: "GET",
+            headers,
+            referrerPolicy: "no-referrer",
+        });
+        const data = (await response.json());
+        return data;
+    }
+    function baseCompletionData(type, model, requestor, duration) {
+        return {
+            partitionKey: requestor,
+            id: crypto.randomUUID(),
+            type,
+            model,
+            createdAt: new Date().toISOString(),
+            durationMs: duration,
+            usage: {},
+        };
+    }
+    const chatWithAI = (_userId, _input, _context, _model) => {
+        void [_userId, _input, _context, _model];
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const synthesizeSpeech = (_userId, _input, _voice, _context, _model) => {
+        void [_userId, _input, _voice, _context, _model];
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const transcribeSpeech = (_userId, _input, _context, _model) => {
+        void [_userId, _input, _context, _model];
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const generateImage = (_userId, _input, _context, _model) => {
+        void [_userId, _input, _context, _model];
+        return Promise.reject(new Error("Not implemented"));
+    };
+    const produceVideo = (userId, input, image, context, model) => {
+        const start = perf_hooks_1.performance.now();
+        return uploadImage(image, props.pixelVerseAPIKey)
+            .then((uploadResult) => {
+            const imageId = uploadResult?.Resp?.id;
+            if (!imageId)
+                throw new Error("Invalid image upload response.");
+            return generateVideo(imageId, input, props.pixelVerseAPIKey);
+        })
+            .then((generated) => {
+            const videoId = generated?.Resp?.id;
+            if (!videoId)
+                throw new Error("Video generation did not return a valid ID.");
+            return waitForVideoCompletion(videoId, props.pixelVerseAPIKey);
+        })
+            .then((videoUrl) => {
+            const duration = perf_hooks_1.performance.now() - start;
+            const base = baseCompletionData("video", model, userId, duration);
+            return {
+                ...base,
+                url: new URL(videoUrl),
+            };
+        })
+            .catch((err) => {
+            // Optional: log or re-throw error for upstream handling
+            throw new Error(`produceVideo failed: ${err.message}`);
+        });
+    };
+    async function waitForVideoCompletion(videoId, apiKey, maxRetries = 20, delayMs = 3000) {
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            await new Promise((res) => setTimeout(res, delayMs));
+            try {
+                const videoCheck = await checkVideoStatus(videoId, apiKey);
+                if (videoCheck?.Resp?.status === 1) {
+                    const url = videoCheck?.Resp?.url;
+                    if (!url)
+                        throw new Error("Video marked complete but no URL returned.");
+                    return url;
+                }
+            }
+            catch (err) {
+                console.warn(`Attempt ${attempt + 1} failed: ${err.message}`);
+            }
+        }
+        throw new Error("Timed out waiting for video to complete.");
+    }
+    const checkBalance = (userId) => {
+        const start = perf_hooks_1.performance.now();
+        const headers = new Headers();
+        headers.append("API-KEY", props.pixelVerseAPIKey);
+        headers.append("AI-trace-ID", (0, uuid_1.v4)());
+        headers.append("Access-Control-Allow-Origin", "*");
+        headers.append("Accept", "application/json");
+        headers.append("Content-Type", "application/json");
+        return fetch("/pixelapi/openapi/v2/account/balance", {
+            method: "GET",
+            headers,
+            referrerPolicy: "no-referrer",
+        })
+            .then(async (res) => (await res.json()))
+            .then((data) => {
+            if (!data?.Resp) {
+                throw new Error("Invalid balance response");
+            }
+            const duration = perf_hooks_1.performance.now() - start;
+            const base = baseCompletionData("balanceCompletion", "", userId, duration);
+            const monthly = data.Resp.credit_monthly ?? 0;
+            const pkg = data.Resp.credit_package ?? 0;
+            return {
+                ...base,
+                balance: monthly + pkg,
+            };
+        })
+            .catch((err) => {
+            throw new Error(`checkBalance failed: ${err.message}`);
+        });
+    };
+    const [currentBalance] = (0, react_1.useState)((await checkBalance(userId)).balance ?? 0);
+    return {
+        chatWithAI,
+        synthesizeSpeech,
+        transcribeSpeech,
+        generateImage,
+        produceVideo,
+        checkBalance,
+        currentBalance,
+    };
+}

package/docs/adrs/adr-0001-ai-package-scope.md

@@ -0,0 +1,21 @@
+# ADR-0001: Standalone @plasius/ai Package Scope
+
+- Date: 2026-02-11
+- Status: Accepted
+
+## Context
+
+This package was previously maintained as a workspace-only module inside
+`plasius-ltd-site`. External consumers and remote builds require it to be
+installable from npm without monorepo-local links.
+
+## Decision
+
+Move `@plasius/ai` to a standalone root package with independent build,
+test, governance, CI, and publish workflows.
+
+## Consequences
+
+- The package can be versioned and released independently.
+- `plasius-ltd-site` and other repositories can depend on npm-published versions.
+- Build and lint rules must no longer rely on monorepo-relative tsconfig paths.

package/docs/adrs/adr-0002-public-repo-governance.md

@@ -0,0 +1,24 @@
+# ADR-0002: Public Repository Governance Baseline
+
+- Date: 2026-02-11
+- Status: Accepted
+
+## Context
+
+Public npm distribution requires transparent contributor and security policy
+artifacts and consistent release automation.
+
+## Decision
+
+Include these baseline governance assets:
+
+- `CODE_OF_CONDUCT.md`
+- `CONTRIBUTORS.md`
+- `SECURITY.md`
+- `legal/` CLA documents
+- CI/CD GitHub Actions workflows
+
+## Consequences
+
+- Public contributors and consumers can follow a predictable governance process.
+- Release quality gates (build, test, coverage, publish) are standardized.

package/docs/adrs/adr-0003-contracts-first-documentation.md

@@ -0,0 +1,25 @@
+# ADR-0003: Contracts-First Documentation Baseline
+
+- Date: 2026-02-11
+- Status: Accepted
+
+## Context
+
+As `@plasius/ai` moves to public npm usage, consumers need clear guidance on
+what is stable API versus what is provisional runtime code. Previous
+documentation did not clearly separate these concerns.
+
+## Decision
+
+Document `@plasius/ai` around the current stable contract surface:
+
+- Publish architecture guidance for contracts-first usage.
+- Provide explicit API reference for `AICapability`, `AIPlatform`, completion
+  models, and schemas.
+- Add provider guidance for host-app adapter composition.
+- Record known limitations and provisional runtime areas in README/docs.
+
+## Consequences
+
+- Integrators can safely adopt stable exports without relying on unfinished internals.
+- Migration to future provider packages can happen with less ambiguity.

package/docs/adrs/adr-template.md

@@ -0,0 +1,35 @@
+# Architectural Decision Record (ADR)
+
+## Title
+
+> Concise, descriptive title of the decision.
+
+## Status
+
+- Proposed | Accepted | Rejected | Superseded | Deprecated
+- Date: YYYY-MM-DD
+- Version: 1.0
+
+## Context
+
+Describe the problem, constraints, and relevant background.
+
+## Decision
+
+Clear statement of the selected approach.
+
+## Alternatives Considered
+
+- Option A
+- Option B
+- Option C
+
+## Consequences
+
+- Positive outcomes
+- Negative outcomes / trade-offs
+- Follow-up work
+
+## References
+
+- https://adr.github.io/

package/docs/api-reference.md

@@ -0,0 +1,64 @@
+# API Reference
+
+## Enums
+
+### `AICapability`
+
+Routing capability enum:
+
+- `Chat`
+- `Text`
+- `Speech`
+- `Image`
+- `Video`
+- `Balance`
+
+## Core Interfaces
+
+### `AIPlatform`
+
+Contract for runtime adapters:
+
+- `chatWithAI(userId, input, context, model)`
+- `synthesizeSpeech(userId, input, voice, context, model)`
+- `transcribeSpeech(userId, input, context, model)`
+- `generateImage(userId, input, context, model)`
+- `produceVideo(userId, input, image, context, model)`
+- `checkBalance(userId)`
+- `currentBalance`
+
+Optional:
+
+- `canHandle(userId, capabilities)`
+
+## Completion Models
+
+Base type:
+
+- `Completion`
+  - `id`
+  - `partitionKey`
+  - `type`
+  - `model`
+  - `durationMs`
+  - `createdAt`
+  - `usage?`
+
+Specialized variants:
+
+- `ChatCompletion`
+- `TextCompletion`
+- `ImageCompletion`
+- `SpeechCompletion`
+- `VideoCompletion`
+- `BalanceCompletion`
+
+## Exported Schemas
+
+- `completionSchema`
+- `chatCompletionSchema`
+- `textCompletionSchema`
+- `imageCompletionSchema`
+- `speechCompletionSchema`
+- `videoCompletionSchema`
+- `balanceCompletionSchema`