feat: prompt-pipeline library and formatters

packages/prompt-formatter-claude/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@kagura/prompt-formatter-claude",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Claude API formatter for @kagura/prompt-pipeline",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@kagura/prompt-pipeline": "workspace:*",
+    "tsdown": "0.21.7",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "@kagura/prompt-pipeline": "workspace:*"
+  }
+}

packages/prompt-formatter-claude/src/index.ts

@@ -0,0 +1,50 @@
+import type { Formatter, PromptResult } from '@kagura/prompt-pipeline';
+
+interface ClaudeTextContent {
+  text: string;
+  type: 'text';
+}
+
+interface ClaudeImageContent {
+  source: { type: 'base64'; media_type: string; data: string };
+  type: 'image';
+}
+
+type ClaudeContentBlock = ClaudeTextContent | ClaudeImageContent;
+
+interface ClaudeMessage {
+  content: string | ClaudeContentBlock[];
+  role: 'user' | 'assistant';
+}
+
+export interface ClaudePayload {
+  messages: ClaudeMessage[];
+  system: string;
+}
+
+export const claudeFormatter: Formatter<ClaudePayload> = {
+  name: 'claude',
+  format(result: PromptResult): ClaudePayload {
+    const messages: ClaudeMessage[] = result.messages.map((m) => {
+      if (m.images?.length) {
+        return {
+          role: m.role,
+          content: [
+            { type: 'text' as const, text: m.content },
+            ...m.images.map((img) => ({
+              type: 'image' as const,
+              source: {
+                type: 'base64' as const,
+                media_type: img.mimeType,
+                data: img.base64Data,
+              },
+            })),
+          ],
+        };
+      }
+      return { role: m.role, content: m.content };
+    });
+
+    return { system: result.system, messages };
+  },
+};

packages/prompt-formatter-claude/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "exclude": ["dist", "node_modules"],
+  "include": ["src/**/*.ts"]
+}

packages/prompt-formatter-claude/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: 'src/index.ts',
+  outDir: 'dist',
+  format: 'esm',
+  clean: true,
+  dts: true,
+  tsconfig: 'tsconfig.json',
+});

packages/prompt-formatter-openai/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@kagura/prompt-formatter-openai",
+  "version": "0.1.0",
+  "private": true,
+  "description": "OpenAI API formatter for @kagura/prompt-pipeline",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@kagura/prompt-pipeline": "workspace:*",
+    "tsdown": "0.21.7",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "@kagura/prompt-pipeline": "workspace:*"
+  }
+}

packages/prompt-formatter-openai/src/index.ts

@@ -0,0 +1,27 @@
+import type { Formatter, PromptResult } from '@kagura/prompt-pipeline';
+
+interface OpenAIMessage {
+  content: string;
+  role: 'system' | 'user' | 'assistant';
+}
+
+export interface OpenAIPayload {
+  messages: OpenAIMessage[];
+}
+
+export const openaiFormatter: Formatter<OpenAIPayload> = {
+  name: 'openai',
+  format(result: PromptResult): OpenAIPayload {
+    const messages: OpenAIMessage[] = [];
+
+    if (result.system) {
+      messages.push({ role: 'system', content: result.system });
+    }
+
+    for (const m of result.messages) {
+      messages.push({ role: m.role, content: m.content });
+    }
+
+    return { messages };
+  },
+};

packages/prompt-formatter-openai/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "exclude": ["dist", "node_modules"],
+  "include": ["src/**/*.ts"]
+}

packages/prompt-formatter-openai/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: 'src/index.ts',
+  outDir: 'dist',
+  format: 'esm',
+  clean: true,
+  dts: true,
+  tsconfig: 'tsconfig.json',
+});

packages/prompt-pipeline/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@kagura/prompt-pipeline",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Slot-based prompt assembly pipeline with Zod-validated dependency injection",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsdown": "0.21.7",
+    "typescript": "^6.0.2",
+    "zod": "4.3.6"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  }
+}

packages/prompt-pipeline/src/assembler.ts

@@ -0,0 +1,81 @@
+import type { SlotWriterInternal } from './slot-writer.js';
+import type {
+  ImageAsset,
+  Message,
+  PromptResult,
+  ResolvedMessage,
+  Slot,
+  TraceEntry,
+} from './types.js';
+
+function mergeSlotPair(
+  bodyWriter: SlotWriterInternal | undefined,
+  contextWriter: SlotWriterInternal | undefined,
+): ResolvedMessage | null {
+  const bodyText = bodyWriter?.getText() ?? '';
+  const contextText = contextWriter?.getText() ?? '';
+  if (!bodyText && !contextText) return null;
+
+  const parts: string[] = [];
+  if (bodyText) parts.push(bodyText);
+  if (contextText) parts.push(contextText);
+
+  const images: ImageAsset[] = [
+    ...(bodyWriter?.getImages() ?? []),
+    ...(contextWriter?.getImages() ?? []),
+  ];
+
+  const msg: ResolvedMessage = { role: 'user', content: parts.join('\n') };
+  if (images.length > 0) msg.images = images;
+  return msg;
+}
+
+function segmentsToMessages(writer: SlotWriterInternal | undefined): ResolvedMessage[] {
+  if (!writer) return [];
+  const images = writer.getImages();
+  return writer.getSegments().map((text, i) => {
+    const msg: ResolvedMessage = { role: 'user', content: text };
+    if (i === 0 && images.length > 0) msg.images = images;
+    return msg;
+  });
+}
+
+export function assembleResult(
+  writers: Map<Slot, SlotWriterInternal>,
+  threadHistory: Message[],
+  trace: TraceEntry[],
+): PromptResult {
+  const systemWriter = writers.get('system');
+  const system = systemWriter?.getText() ?? '';
+
+  const afterSystemMessages = segmentsToMessages(writers.get('afterSystem'));
+  const afterSystem = writers.get('afterSystem')?.getSegments() ?? [];
+
+  const firstMessage = mergeSlotPair(
+    writers.get('firstUserMessage'),
+    writers.get('firstUserMessageContext'),
+  );
+
+  const historyMessages: ResolvedMessage[] = threadHistory.map((m) => {
+    const msg: ResolvedMessage = { role: m.role, content: m.content };
+    if (m.images?.length) msg.images = m.images;
+    return msg;
+  });
+
+  const lastMessage = mergeSlotPair(
+    writers.get('lastUserMessage'),
+    writers.get('lastUserMessageContext'),
+  );
+
+  const afterUserMessages = segmentsToMessages(writers.get('afterUser'));
+
+  const messages: ResolvedMessage[] = [
+    ...afterSystemMessages,
+    ...(firstMessage ? [firstMessage] : []),
+    ...historyMessages,
+    ...(lastMessage ? [lastMessage] : []),
+    ...afterUserMessages,
+  ];
+
+  return { system, afterSystem, messages, trace };
+}

packages/prompt-pipeline/src/errors.ts

@@ -0,0 +1,13 @@
+export class PipelineConfigError extends Error {
+  override readonly name = 'PipelineConfigError';
+}
+
+export class PluginInjectError extends Error {
+  override readonly name = 'PluginInjectError';
+  readonly pluginName: string;
+
+  constructor(pluginName: string, message: string) {
+    super(`Plugin "${pluginName}": ${message}`);
+    this.pluginName = pluginName;
+  }
+}

packages/prompt-pipeline/src/index.ts

@@ -0,0 +1,14 @@
+export { PipelineConfigError, PluginInjectError } from './errors.js';
+export { createPipeline } from './pipeline.js';
+export { definePlugin } from './plugin.js';
+export type {
+  Formatter,
+  ImageAsset,
+  Message,
+  PluginDef,
+  PromptResult,
+  ResolvedMessage,
+  Slot,
+  SlotWriter,
+  TraceEntry,
+} from './types.js';