AI Integration

PWFabric provides first-class AI integration for intelligent surface creation, content generation, and adaptive experiences.

Status: Preview. The AI Composer ships in the web studio today; the standalone @pwfabric/ai SDK is planned.

AI capabilities

Capability	Status	What it does
AI Composer (Studio)	Preview	Streaming PhiCo composer in the web studio with four conversation modes (structure, styling, behavior, data).
Block Composition	Preview	Generates correct block types and props from natural language. Understands every block type and its schema.
Surface Generation API	Preview	Programmatic surface generation via `/api/ai/composer/stream` (SSE) — callable from your own application.
Adaptive Rendering	Coming	Surfaces that adapt their presentation based on user behavior and preferences.

AI Composer (Web Studio)

The AI Composer is the streaming PhiCo system built into the PWFabric web studio. A single backend pipeline (/api/ai/composer/stream) powers four conversation modes in the UI — each mode shapes prompts toward a specific surface concern but talks to the same composer.

Conversation modes

Mode	Focus
✨ Composer	Structure & block composition
🎨 Style	Theme tokens & visual design
⚡ Capabilities	Behavior & interactions
📊 Data	Data sources & bindings

Custom modes can be added via /api/ai/agents.

Key features

Streaming responses (SSE)
Per-mode conversation threads
Surface mutation undo/redo
Metrics tracking per mode
Custom mode support

API endpoints

POST /api/ai/composer/stream   # SSE streaming (ADR-100)
GET  /api/ai/metrics            # Per-agent usage metrics
GET  /api/ai/agents             # List custom agents
POST /api/ai/agents             # Create custom agent

`@pwfabric/world/intelligence`

The Intelligence module is part of @pwfabric/world — the entity model layer. It provides AI-powered surface generation and block suggestion capabilities.

import { Intelligence } from '@pwfabric/world/intelligence'
 
// Generate surface blocks from a prompt
const blocks = await Intelligence.generate({
  prompt: 'A landing page for a SaaS product with pricing',
  context: { worldId: 'wld_123' },
})

Standalone AI SDK (planned)

A standalone @pwfabric/ai package is planned for programmatic AI access outside of the web studio. Until it ships, use @pwfabric/world/intelligence or the /api/ai/composer/stream endpoint.

// Planned: @pwfabric/ai standalone package
import { createAI } from '@pwfabric/ai'
 
const ai = createAI({
  apiKey: process.env.PWFABRIC_AI_KEY,
})
 
// Generate a surface from a description
const surface = await ai.generate({
  prompt: 'A landing page for a SaaS product with pricing',
  style: 'modern',
})
 
// Get block suggestions
const suggestions = await ai.suggest({
  surface: currentSurface,
  position: 'after-hero',
})

API reference

Method	Endpoint	Purpose
`POST`	`/api/ai/composer/stream`	Stream a PhiCo conversation (SSE, ADR-100). The only composer endpoint — there is no non-streaming variant.
`POST`	`/api/ai/complete`	Synchronous completion for short prompts.
`GET`	`/api/ai/metrics`	Per-agent usage metrics for the current day
`GET`	`/api/ai/agents`	List custom AI agents configured for the World
`POST`	`/api/ai/agents`	Create a new custom AI agent

Best practices

Be specific. Detailed prompts produce better results. Include target audience, style preferences, and required sections.
Iterate incrementally. Start with a basic generation, then refine with follow-up prompts. The AI retains context within a thread.
Review generated code. AI assists, it does not replace judgment. Always review before publishing.
Provide examples. Reference surfaces or screenshots help the AI match existing styles and patterns.

World physics Overview