npm.io
1.1.29 • Published 6d ago

@plasius/ai

Licence
MIT
Version
1.1.29
Deps
5
Size
406 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

@plasius/ai

npm version Build Status coverage License Code of Conduct Security Policy Changelog

AI capability contracts, completion schemas, and agentic foundation contracts for Plasius applications.

Scope

This package currently provides:

  • capability contracts (AICapability, AIPlatform)
  • agentic foundation contracts for request envelopes, task kinds, rollout metadata, provider/model catalogs, and metering
  • 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.
  • Agentic foundation contracts and helpers:
    • AI_FEATURE_FLAGS
    • AI_AGENTIC_FOUNDATION_ROLLOUT
    • createAITaskKind
    • createAIRequestEnvelope
    • resolveAIRolloutDecision
    • AIProviderDescriptor
    • AIModelCatalogEntry
    • AIUsageMetrics
    • AICostEstimate
    • AIConfidenceScore
  • 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
    • VideoProviderPlatform
    • createVideoProviderPlatform
      • Contract key: platform.repo-hardening-sweep.enabled
  • Pixelverse component translation helpers:
    • pixelverseEnGbTranslations
    • pixelverseTranslationKeys
    • translatePixelverseText
  • Completion + typed completion variants:
    • ChatCompletion
    • TextCompletion
    • ImageCompletion
    • SpeechCompletion
    • VideoCompletion
    • ModelCompletion
    • BalanceCompletion
  • Schemas:
    • completionSchema
    • chatCompletionSchema
    • textCompletionSchema
    • imageCompletionSchema
    • speechCompletionSchema
    • videoCompletionSchema
    • modelCompletionSchema
    • balanceCompletionSchema

Completion schemas validate persisted records, including the internal partitionKey used to associate requests with a user or system actor. When returning completion payloads to clients, prefer completionSchema.serialize(...) so internal fields stay out of the default response shape.

Documentation

Known Limitations

  • The supported package surface is the root module export from src/index.ts; internal src/** files remain implementation details unless they are explicitly re-exported.
  • 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 or downstream @plasius/ai-* packages.
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;
Client-safe completion payloads
import { completionSchema } from "@plasius/ai";

const persistedCompletion = {
  id: "completion-1",
  type: "chat",
  model: "gpt-4.1-mini",
  durationMs: 42,
  createdAt: new Date().toISOString(),
  partitionKey: "user-1",
};

const publicPayload = completionSchema.serialize(persistedCompletion);
// partitionKey is omitted by default.

void publicPayload;
Agentic foundation contracts
import {
  AI_FEATURE_FLAGS,
  createAIRequestEnvelope,
  createAITaskKind,
  resolveAIRolloutDecision,
} from "@plasius/ai";

const rollout = resolveAIRolloutDecision(
  {
    featureFlag: AI_FEATURE_FLAGS.agenticFoundation,
    evaluator: "remote-flag-service",
    defaultEnabled: false,
    fallbackMode: "fail-closed",
  },
  {
    [AI_FEATURE_FLAGS.agenticFoundation]: true,
  }
);

const envelope = createAIRequestEnvelope({
  requestId: "req-1",
  taskKind: createAITaskKind({
    domain: "routing",
    action: "select",
  }),
  actor: {
    actorId: "user-1",
    actorType: "user",
  },
  input: {
    prompt: "Choose the cheapest safe model.",
  },
});

void rollout;
void envelope;
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;
Pixelverse UI Translations

Pixelverse editor components keep their display text in the package-owned en-GB dictionary and resolve defaults through @plasius/translations. Host applications can pass a translate function to VideoGenerationEditor or Balance when they need a different locale while preserving the package fallbacks.

import type { PixelverseTranslate } from "@plasius/ai";

const translate: PixelverseTranslate = (key, args) => i18n.t(key, args);

<VideoGenerationEditor
  apiKey={apiKey}
  adapter={videoAdapter}
  translate={translate}
/>;

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

Keywords

chatbottext-to-speechspeech-to-textAI-generated imagesAI-generated videosPlasius AI