@plasius/ai

AI capability contracts and completion schemas for Plasius applications.

Scope

This package currently provides:

• capability contracts (AICapability, AIPlatform)
• completion model interfaces (ChatCompletion, ImageCompletion, ModelCompletion, etc.)
• schema definitions for completion entities
• adapter contracts/factories for multi-provider routing with developer-supplied API keys

Provider wiring and runtime adapters are documented in docs/providers.md.

Install

npm install @plasius/ai

Module formats

This package publishes dual ESM and CJS artifacts. When CJS output is emitted under dist-cjs/*.js with type: module, dist-cjs/package.json is generated with { "type": "commonjs" } to ensure Node require(...) compatibility.

Usage

import {
  AICapability,
  type AIPlatform,
  completionSchema,
  chatCompletionSchema,
} from "@plasius/ai";

const capabilities = [AICapability.Chat, AICapability.Image];
void capabilities;
void completionSchema;
void chatCompletionSchema;

// Host apps provide the concrete runtime implementation.
const platform: AIPlatform = {
  chatWithAI: async () => ({
    id: crypto.randomUUID(),
    partitionKey: "user-1",
    type: "chat",
    model: "gpt-4.1-mini",
    durationMs: 42,
    createdAt: new Date().toISOString(),
    message: "Hello world",
    outputUser: "assistant",
  }),
  synthesizeSpeech: async () => {
    throw new Error("Not implemented");
  },
  transcribeSpeech: async () => {
    throw new Error("Not implemented");
  },
  generateImage: async () => {
    throw new Error("Not implemented");
  },
  produceVideo: async () => {
    throw new Error("Not implemented");
  },
  generateModel: async () => {
    throw new Error("Not implemented");
  },
  checkBalance: async () => ({
    id: crypto.randomUUID(),
    partitionKey: "user-1",
    type: "balance",
    model: "",
    durationMs: 0,
    createdAt: new Date().toISOString(),
    balance: 0,
  }),
  currentBalance: 0,
};

void platform;

API Surface

• AICapability: enum describing logical capability routing.
• AIPlatform: interface your runtime adapter must implement.
• Generic multi-capability adapter contracts and helpers:
  • AICapabilityAdapter
  • AdapterPlatformProps
  • HttpClientPolicy
  • createAdapterPlatform
  • createOpenAIAdapter
  • createGeminiAdapter
  • createGrokAdapter
  • createMetaAIAdapter
  • createPixelverseAdapter
• Generic video-provider adapter contracts and helpers:
  • VideoProviderAdapter
  • VideoGenerationRequest
  • createHttpVideoProviderAdapter
  • createVideoProviderPlatform
• Completion + typed completion variants:
  • ChatCompletion
  • TextCompletion
  • ImageCompletion
  • SpeechCompletion
  • VideoCompletion
  • ModelCompletion
  • BalanceCompletion
• Schemas:
  • completionSchema
  • chatCompletionSchema
  • textCompletionSchema
  • imageCompletionSchema
  • speechCompletionSchema
  • videoCompletionSchema
  • modelCompletionSchema
  • balanceCompletionSchema

Documentation

• Architecture: docs/architecture.md
• API reference: docs/api-reference.md
• Provider guidance: docs/providers.md

Known Limitations

• src/lib/* currently contains placeholder files and is not part of the public API.
• Provider-specific runtime adapters are still under stabilization and should be wrapped by host applications.
• The package focuses on contracts/schemas first; runtime behavior is expected to be composed by consumers.

Multi-Capability Adapter Composition

import {
  AICapability,
  createAdapterPlatform,
  createGeminiAdapter,
  createGrokAdapter,
  createMetaAIAdapter,
  createOpenAIAdapter,
  createPixelverseAdapter,
} from "@plasius/ai";

const openAIAdapter = createOpenAIAdapter({
  id: "openai",
  httpPolicy: {
    maxAttempts: 3,
    timeoutMs: 30000,
    baseDelayMs: 250,
    maxDelayMs: 4000,
    jitterRatio: 0.2,
  },
  defaultModels: {
    chat: "gpt-4.1-mini",
    speech: "gpt-4o-mini-tts",
    transcription: "gpt-4o-mini-transcribe",
    image: "gpt-image-1",
    model: "gpt-4.1-mini",
  },
});

const geminiAdapter = createGeminiAdapter({
  id: "gemini",
  httpPolicy: {
    maxAttempts: 3,
    timeoutMs: 30000,
  },
  defaultModels: {
    chat: "gemini-2.0-flash",
    image: "imagen-3.0-generate-002",
    model: "gemini-2.0-flash",
  },
});

const grokAdapter = createGrokAdapter();
const metaAdapter = createMetaAIAdapter();
const pixelverseAdapter = createPixelverseAdapter();

const platform = await createAdapterPlatform("user-1", {
  adapters: [openAIAdapter, geminiAdapter, grokAdapter, metaAdapter, pixelverseAdapter],
  apiKeys: {
    openai: process.env.OPENAI_API_KEY ?? "",
    gemini: process.env.GEMINI_API_KEY ?? "",
    grok: process.env.XAI_API_KEY ?? "",
    "meta-ai": process.env.META_AI_API_KEY ?? "",
    pixelverse: process.env.PIXELVERSE_API_KEY ?? "",
  },
  defaultAdapterByCapability: {
    [AICapability.Chat]: "grok",
    [AICapability.Speech]: "openai",
    [AICapability.Image]: "gemini",
    [AICapability.Model]: "gemini",
    [AICapability.Video]: "pixelverse",
    [AICapability.Balance]: "pixelverse",
  },
});

void platform;

Generic Video Adapter Composition

import {
  createHttpVideoProviderAdapter,
  createVideoProviderPlatform,
} from "@plasius/ai";

const videoAdapter = createHttpVideoProviderAdapter({
  uploadImagePath: "/provider/image/upload",
  generateVideoPath: "/provider/video/generate",
  getVideoResultPath: (videoId) => `/provider/video/result/${videoId}`,
  getBalancePath: "/provider/account/balance",
});

const platform = await createVideoProviderPlatform("user-1", {
  apiKey: process.env.PROVIDER_API_KEY ?? "",
  adapter: videoAdapter,
});

void platform;

Development

npm install
npm run build
npm test
npm run test:coverage
npm run demo:run

Demo Sanity Check

npm run demo:run

Publishing

This package is published via GitHub CD only.

1. Configure repository environment production with secret NPM_TOKEN.
2. Run .github/workflows/cd.yml via Actions -> CD (Publish to npm) -> Run workflow.
3. Select the version bump (patch, minor, major, or none) and optional pre-release id.

Build Outputs

• ESM: dist/
• CJS: dist-cjs/
• Types: dist/*.d.ts

License

MIT