How AI Plugins Work Inside Z-CMS

Why AI should be a platform capability

CMS users increasingly expect AI writing, summarization, translation, SEO metadata, product descriptions, classification, semantic search and assistants. Calling one model directly from the Core is easy, but it creates provider lock-in, unmanaged API keys, unclear data transfer and uncontrolled cost.

Z-CMS treats AI as a governed platform capability that plugins access through a common SDK.

AI Gateway architecture

AI Plugin
   ↓
Z-CMS AI SDK
   ↓
AI Gateway
   ↓
Policy Engine
   ↓
Provider Adapter
   ↓
AI Provider

The gateway selects the provider and model, checks quota, applies privacy policy, records usage, handles retries and validates output.

Provider abstraction

interface AIProvider {
  generateText(request: GenerateTextRequest): Promise<GenerateTextResponse>;
  generateEmbedding(request: EmbeddingRequest): Promise<EmbeddingResponse>;
}

Adapters can support public cloud services, Azure-hosted models, Ollama, local Llama deployments or an enterprise on-premise model. Plugins continue calling cms.ai regardless of the provider.

Tenant-level policy and credentials

Tenant A → Public cloud model → Monthly budget $100
Tenant B → Azure-hosted model → Japan region
Tenant C → On-premise model → No external transfer

Credentials remain in a secret store and are never exposed to plugin isolates.

AI permissions

{
  "permissions": [
    "ai:text:generate",
    "content:read"
  ]
}

Embedding generation, file analysis and other capabilities require separate permissions. Every call is enforced at runtime.

Purpose-driven requests

const result = await cms.ai.generateText({
  purpose: "translate-content",
  input: article.content,
  metadata: { targetLanguage: "ja" }
});

Purpose allows the gateway to select a model, prompt template, output limit and policy appropriate to the task. A short SEO description may use a fast model and a 300-token ceiling, while long-form generation uses a different policy.

Prompt registry and structured output

const result = await cms.ai.runPrompt(
  "seo.generateMetaDescription",
  { title: article.title, content: article.content }
);

Managed prompt templates are versioned and can be overridden by an enterprise tenant. For machine-consumed results, Z-CMS favors structured output validated against a schema.

const metadata = await cms.ai.generateObject({
  purpose: "seo-analysis",
  schema: SeoAnalysisSchema,
  input: article.content
});

Quota and cost control

Usage is attributed to tenant, plugin, user, feature, provider and model. Administrators can set warning and hard limits.

{
  "tenantId": "tenant-a",
  "pluginId": "plugin-ai-writer",
  "model": "text-model",
  "inputTokens": 1200,
  "outputTokens": 400,
  "estimatedCost": 0.012
}

Privacy classification and PII handling

Public → External AI allowed
Internal → Approved providers only
Confidential → Enterprise provider only
Restricted → Local model only

Before external transfer, the gateway can redact emails, phone numbers, customer identifiers, credentials and other sensitive values. A fallback provider is never used when it violates the tenant’s data policy.

Human approval and background jobs

Low-risk metadata may be applied automatically, while generated articles are normally created as drafts for editorial approval. Long translations and document analysis run as queued jobs rather than blocking a request.

Editor requests translation
   ↓
Job queued with tenant context
   ↓
Worker calls AI Gateway
   ↓
Draft translation stored
   ↓
Editor notified

Semantic search and RAG

Plugins can request embeddings through the gateway and store vectors in a tenant-aware search layer. Retrieval applies tenant and permission filters before content is added to a model context.

Question
   ↓
Retrieve permitted tenant documents
   ↓
Build context
   ↓
Generate answer
   ↓
Return answer with sources

Isolation, fallback and caching

AI plugins still run inside V8 Isolates. They cannot read API keys, bypass quota or call an undeclared network endpoint. Deterministic requests may be cached using tenant, plugin, purpose, model, prompt version and content hash.

Developer experience

const description = await cms.ai.generateText({
  purpose: "product-description",
  input: {
    name: product.name,
    features: product.features
  }
});

The plugin developer does not need to implement provider SDKs, retries, rate limits, credentials, billing, audit, output validation or privacy controls.

Conclusion

Z-CMS AI plugins use a provider-neutral gateway with explicit permissions, tenant policy, quotas, privacy controls, structured output, background execution and auditability. The same plugin can operate with public cloud AI, private enterprise AI or an on-premise model without changing its business logic.

GitHub: https://github.com/zscontributor/z-cms
Website: https://z-cms.org