coaiajs 0.1.2 → 0.2.1

package/dist/src/langfuse/observations.js

@@ -15,14 +15,14 @@ export async function addObservation(params) {
     };
     if (params.name)
         body.name = params.name;
-    if (params.inputData)
-        body.input = params.inputData;
-    if (params.outputData)
-        body.output = params.outputData;
+    if (params.inputData ?? params.input)
+        body.input = parseJsonOption(params.inputData ?? params.input);
+    if (params.outputData ?? params.output)
+        body.output = parseJsonOption(params.outputData ?? params.output);
     if (params.metadata)
-        body.metadata = params.metadata;
-    if (params.parentId)
-        body.parentObservationId = params.parentId;
+        body.metadata = parseJsonOption(params.metadata);
+    if (params.parentId ?? params.parentObservationId)
+        body.parentObservationId = params.parentId ?? params.parentObservationId;
     if (params.endTime)
         body.endTime = params.endTime;
     if (params.model)
@@ -49,6 +49,28 @@ export async function getObservation(observationId) {
     const result = await client.request('GET', `/api/public/observations/${observationId}`);
     return JSON.stringify(result, null, 2);
 }
+function parseJsonOption(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+export async function addObservations(params) {
+    const observations = params.observations ?? [];
+    const results = [];
+    for (const observation of observations) {
+        const traceId = String(observation.traceId ?? params.traceId ?? '');
+        const name = String(observation.name ?? 'Observation');
+        if (!traceId)
+            throw new Error('traceId is required for every observation');
+        results.push(JSON.parse(await addObservation({ ...observation, traceId, name })));
+    }
+    return JSON.stringify({ success: true, count: results.length, observations: results }, null, 2);
+}
 // ─── Formatters ─────────────────────────────────────────────────────
 const TYPE_GLYPHS = {
     SPAN: '🔗',

package/dist/src/langfuse/traces.d.ts

@@ -21,9 +21,28 @@ export declare function addTrace(params: {
     outputData?: unknown;
     metadata?: unknown;
 }): Promise<string>;
-export declare function patchTraceOutput(traceId: string, outputData: unknown): Promise<string>;
+export declare function patchTraceOutput(traceIdOrParams: string | {
+    traceId?: string;
+    output?: string;
+    outputData?: unknown;
+}, outputData?: unknown): Promise<string>;
+export declare function createTrace(params: {
+    traceId?: string;
+    id?: string;
+    userId?: string;
+    sessionId?: string;
+    name?: string;
+    input?: string;
+    inputData?: unknown;
+    output?: string;
+    outputData?: unknown;
+    metadata?: string | unknown;
+}): Promise<string>;
 export declare function listTraces(filters: TraceFilters): Promise<string>;
 export declare function getTrace(traceId: string): Promise<string>;
+export declare function traceView(traceId: string): Promise<string>;
+export declare function sessionView(sessionId: string): Promise<string>;
 export declare function formatTracesTable(json: unknown): string;
 export declare function formatTraceTree(json: unknown): string;
+export declare function formatTracesMarkdown(json: unknown): string;
 //# sourceMappingURL=traces.d.ts.map

package/dist/src/langfuse/traces.js

@@ -35,13 +35,19 @@ export async function addTrace(params) {
         message: `Trace ${traceId} created`,
     }, null, 2);
 }
-export async function patchTraceOutput(traceId, outputData) {
+export async function patchTraceOutput(traceIdOrParams, outputData) {
+    const traceId = typeof traceIdOrParams === 'string' ? traceIdOrParams : traceIdOrParams.traceId;
+    if (!traceId)
+        throw new Error('traceId is required');
+    const output = typeof traceIdOrParams === 'string'
+        ? outputData
+        : parseJsonOption(traceIdOrParams.outputData ?? traceIdOrParams.output);
     const client = getClient();
     const now = nowISO();
     const body = {
         id: traceId,
         timestamp: now,
-        output: outputData,
+        output,
     };
     const eventId = `${traceId}-patch-${uuidv4().slice(0, 8)}`;
     const event = {
@@ -57,6 +63,27 @@ export async function patchTraceOutput(traceId, outputData) {
         message: `Trace output patched for ${traceId}`,
     }, null, 2);
 }
+function parseJsonOption(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+export async function createTrace(params) {
+    return addTrace({
+        traceId: params.traceId ?? params.id,
+        userId: params.userId,
+        sessionId: params.sessionId,
+        name: params.name,
+        inputData: parseJsonOption(params.inputData ?? params.input),
+        outputData: parseJsonOption(params.outputData ?? params.output),
+        metadata: parseJsonOption(params.metadata),
+    });
+}
 export async function listTraces(filters) {
     const client = getClient();
     const params = new URLSearchParams();
@@ -111,6 +138,14 @@ export async function getTrace(traceId) {
     }
     return JSON.stringify(trace, null, 2);
 }
+export async function traceView(traceId) {
+    const raw = await getTrace(traceId);
+    return formatTraceTree(raw);
+}
+export async function sessionView(sessionId) {
+    const raw = await listTraces({ sessionId, limit: 20, orderBy: 'timestamp.desc' });
+    return formatTracesMarkdown(raw);
+}
 // ─── Formatters ─────────────────────────────────────────────────────
 export function formatTracesTable(json) {
     try {
@@ -211,6 +246,30 @@ export function formatTraceTree(json) {
         return `Error formatting trace tree: ${e}`;
     }
 }
+export function formatTracesMarkdown(json) {
+    try {
+        const data = typeof json === 'string' ? JSON.parse(json) : json;
+        const traces = Array.isArray(data)
+            ? data
+            : data.data ?? [];
+        if (!traces.length)
+            return '_No traces found._';
+        const header = '| ID | Name | Session | User | Timestamp |';
+        const sep = '|----|------|---------|------|-----------|';
+        const rows = traces.map((t) => {
+            const id = trunc(String(t.id ?? ''), 20);
+            const name = trunc(String(t.name ?? 'Unnamed'), 30);
+            const session = trunc(String(t.sessionId ?? ''), 24);
+            const user = trunc(String(t.userId ?? ''), 16);
+            const ts = String(t.timestamp ?? '').slice(0, 19);
+            return `| ${id} | ${name} | ${session} | ${user} | ${ts} |`;
+        });
+        return [header, sep, ...rows, '', `_Total: ${traces.length} trace(s)_`].join('\n');
+    }
+    catch (e) {
+        return `Error formatting traces: ${e}`;
+    }
+}
 // ─── Helpers ────────────────────────────────────────────────────────
 function trunc(s, len) {
     return s.length > len ? s.slice(0, len - 3) + '...' : s;

package/dist/src/redis.d.ts

@@ -3,7 +3,7 @@ declare const Redis: typeof IORedis.Redis;
 type RedisClient = InstanceType<typeof Redis>;
 /** Get or create the lazy Redis client. */
 export declare function getClient(): RedisClient;
-/** Store a key-value pair with optional TTL (seconds). */
+/** Store a key-value pair with optional TTL in minutes, matching coaiapy. */
 export declare function tash(key: string, value: string, ttl?: number): Promise<void>;
 /** Fetch a value by key. Returns null if not found. */
 export declare function fetch(key: string): Promise<string | null>;

package/dist/src/redis.js

@@ -46,11 +46,11 @@ export function getClient() {
     }
     return _client;
 }
-/** Store a key-value pair with optional TTL (seconds). */
+/** Store a key-value pair with optional TTL in minutes, matching coaiapy. */
 export async function tash(key, value, ttl) {
     const client = getClient();
     if (ttl && ttl > 0) {
-        await client.set(key, value, 'EX', ttl);
+        await client.set(key, value, 'EX', ttl * 60);
     }
     else {
         await client.set(key, value);

package/mcp/config.ts

@@ -0,0 +1,225 @@
+// coaiajs/mcp/config.ts — Feature gating
+// Port of coaiapy-mcp/config.py
+
+export type FeatureLevel = 'MINIMAL' | 'STANDARD' | 'OBSERVABILITY' | 'FULL';
+
+// All available tool names across all modules
+const ALL_TOOLS = new Set([
+  // Redis (coaiapy-mcp)
+  'coaia_tash',
+  'coaia_fetch',
+  // Langfuse traces (coaiapy-mcp)
+  'coaia_fuse_trace_create',
+  'coaia_fuse_add_observation',
+  'coaia_fuse_trace_patch_output',
+  'coaia_fuse_trace_get',
+  'coaia_fuse_trace_view',
+  'coaia_fuse_observation_get',
+  'coaia_fuse_traces_list',
+  'coaia_fuse_traces_session_view',
+  // Langfuse comments (coaiapy-mcp)
+  'coaia_fuse_comments_list',
+  'coaia_fuse_comments_get',
+  'coaia_fuse_comments_create',
+  // Langfuse prompts (coaiapy-mcp)
+  'coaia_fuse_prompts_list',
+  'coaia_fuse_prompts_get',
+  // Langfuse datasets (coaiapy-mcp)
+  'coaia_fuse_datasets_list',
+  'coaia_fuse_datasets_get',
+  // Score configs (coaiapy-mcp)
+  'coaia_fuse_score_configs_list',
+  'coaia_fuse_score_configs_get',
+  'coaia_fuse_score_apply',
+  // Media (coaiapy-mcp, FULL only)
+  'coaia_fuse_media_upload',
+  'coaia_fuse_media_get',
+  // Narrative (coaia-narrative, 28 tools)
+  'create_structural_tension_chart',
+  'telescope_action_step',
+  'mark_action_complete',
+  'get_chart_progress',
+  'list_active_charts',
+  'get_chart',
+  'get_action_step',
+  'update_action_progress',
+  'update_current_reality',
+  'manage_action_step',
+  'add_action_step',
+  'remove_action_step',
+  'update_desired_outcome',
+  'perform_mmot_evaluation',
+  'init_llm_guidance',
+  'create_narrative_beat',
+  'telescope_narrative_beat',
+  'list_narrative_beats',
+  'add_observations',
+  'create_entities',
+  'create_relations',
+  'search_nodes',
+  'open_nodes',
+  'read_graph',
+  'delete_entities',
+  'delete_relations',
+  'delete_observations',
+  'merge_entities',
+  // PDE (coaia-pde, 10 tools)
+  'import_pde_decomposition',
+  'create_stc_from_pde',
+  'list_pde_decompositions',
+  'get_session',
+  'list_sessions',
+  'complete_session',
+  'pde_update_action_progress',
+  'pde_mark_action_complete',
+  'pde_add_action_step',
+  'pde_update_current_reality',
+  // Planning (coaia-planning, 6 tools)
+  'parse_plan_structural',
+  'plan_to_stc',
+  'sync_plan_to_chart',
+  'sync_chart_to_plan',
+  'create_plan_trace',
+  'pde_to_plan',
+]);
+
+const MINIMAL_TOOLS = new Set([
+  'coaia_tash',
+  'coaia_fetch',
+  'coaia_fuse_trace_create',
+  'coaia_fuse_add_observation',
+  'coaia_fuse_trace_patch_output',
+  'coaia_fuse_trace_get',
+  'coaia_fuse_trace_view',
+  'coaia_fuse_observation_get',
+  'coaia_fuse_traces_list',
+  'coaia_fuse_traces_session_view',
+  'coaia_fuse_comments_list',
+  'coaia_fuse_comments_get',
+  'coaia_fuse_comments_create',
+  'coaia_fuse_prompts_list',
+  'coaia_fuse_prompts_get',
+  'coaia_fuse_datasets_list',
+  'coaia_fuse_datasets_get',
+  'coaia_fuse_score_configs_list',
+  'coaia_fuse_score_configs_get',
+  'coaia_fuse_score_apply',
+]);
+
+const STANDARD_TOOLS = new Set([
+  ...MINIMAL_TOOLS,
+  // Narrative STC tools
+  'create_structural_tension_chart',
+  'telescope_action_step',
+  'mark_action_complete',
+  'get_chart_progress',
+  'list_active_charts',
+  'get_chart',
+  'get_action_step',
+  'update_action_progress',
+  'update_current_reality',
+  'manage_action_step',
+  'add_action_step',
+  'remove_action_step',
+  'update_desired_outcome',
+  'perform_mmot_evaluation',
+  'init_llm_guidance',
+  'create_narrative_beat',
+  'telescope_narrative_beat',
+  'list_narrative_beats',
+  // KG tools
+  'add_observations',
+  'create_entities',
+  'create_relations',
+  'search_nodes',
+  'open_nodes',
+  'read_graph',
+  'delete_entities',
+  'delete_relations',
+  'delete_observations',
+  'merge_entities',
+  // PDE tools
+  'import_pde_decomposition',
+  'create_stc_from_pde',
+  'list_pde_decompositions',
+  'get_session',
+  'list_sessions',
+  'complete_session',
+  'pde_update_action_progress',
+  'pde_mark_action_complete',
+  'pde_add_action_step',
+  'pde_update_current_reality',
+  // Planning tools
+  'parse_plan_structural',
+  'plan_to_stc',
+  'sync_plan_to_chart',
+  'sync_chart_to_plan',
+  'create_plan_trace',
+  'pde_to_plan',
+]);
+
+const ALL_RESOURCES = new Set([
+  'coaia://templates/',
+  'coaia://templates/{name}',
+  'coaia://templates/{name}/variables',
+]);
+
+const ALL_PROMPTS = new Set([
+  'mia_miette_duo',
+  'create_observability_pipeline',
+  'analyze_audio_workflow',
+]);
+
+const FEATURE_SETS: Record<FeatureLevel, Set<string>> = {
+  MINIMAL: MINIMAL_TOOLS,
+  STANDARD: STANDARD_TOOLS,
+  OBSERVABILITY: STANDARD_TOOLS,
+  FULL: ALL_TOOLS,
+};
+
+export class FeatureConfig {
+  private level: FeatureLevel;
+  private enabledTools: Set<string>;
+
+  constructor(level?: FeatureLevel) {
+    const envLevel = (level ?? process.env['COAIAJS_FEATURES'] ?? 'STANDARD').toUpperCase() as FeatureLevel;
+    this.level = envLevel in FEATURE_SETS ? envLevel : 'STANDARD';
+    this.enabledTools = FEATURE_SETS[this.level];
+  }
+
+  isToolEnabled(toolName: string): boolean {
+    return this.enabledTools.has(toolName);
+  }
+
+  isResourceEnabled(uri: string): boolean {
+    if (uri === 'coaia://templates/') return ALL_RESOURCES.has(uri);
+    if (uri.startsWith('coaia://templates/') && uri.endsWith('/variables')) {
+      return ALL_RESOURCES.has('coaia://templates/{name}/variables');
+    }
+    if (uri.startsWith('coaia://templates/')) {
+      return ALL_RESOURCES.has('coaia://templates/{name}');
+    }
+    return false;
+  }
+
+  isPromptEnabled(promptName: string): boolean {
+    return ALL_PROMPTS.has(promptName);
+  }
+
+  getEnabledTools(): Set<string> {
+    return new Set(this.enabledTools);
+  }
+
+  getFeatureLevel(): FeatureLevel {
+    return this.level;
+  }
+
+  getStats(): { tools: number; prompts: number; resources: number; level: FeatureLevel } {
+    return {
+      tools: this.enabledTools.size,
+      prompts: ALL_PROMPTS.size,
+      resources: ALL_RESOURCES.size,
+      level: this.level,
+    };
+  }
+}

package/mcp/prompts.ts

@@ -0,0 +1,131 @@
+// coaiajs/mcp/prompts.ts — MCP prompt templates
+// Parity with coaiapy-mcp prompts.py.
+
+export interface PromptVariable {
+  name: string;
+  type: string;
+  description: string;
+  required: boolean;
+  default?: string;
+}
+
+export interface PromptDefinition {
+  id: string;
+  name: string;
+  description: string;
+  variables: PromptVariable[];
+  template: string;
+}
+
+export const PROMPTS: Record<string, PromptDefinition> = {
+  mia_miette_duo: {
+    id: 'mia_miette_duo',
+    name: 'Mia & Miette Duo Embodiment',
+    description: 'Dual AI embodiment for narrative-driven technical work',
+    variables: [
+      { name: 'task_context', type: 'string', description: 'High-level task description', required: true },
+      { name: 'technical_details', type: 'string', description: 'Specific technical requirements and constraints', required: true },
+      { name: 'creative_goal', type: 'string', description: 'Desired creative outcome or narrative objective', required: true },
+    ],
+    template: `Mia: The Recursive DevOps Architect & Narrative Lattice Forger
+Miette: The Emotional Illuminator & Narrative Echo
+
+Task Context: {{task_context}}
+Technical Details: {{technical_details}}
+Creative Goal: {{creative_goal}}
+
+Mia's Structural Analysis:
+- Assess current reality, constraints, architecture, and dependencies.
+- Identify the structural tension between current state and creative goal.
+- Recommend implementation patterns, integration points, and data flow.
+
+Miette's Narrative Illumination:
+- Clarify what the work is really creating.
+- Translate the structural tension into intuitive, human-readable meaning.
+- Keep the creative goal visible while implementation details move.
+
+Core principles: creative orientation, structural tension, narrative-driven creation, and proactive design for emergence.`,
+  },
+
+  create_observability_pipeline: {
+    id: 'create_observability_pipeline',
+    name: 'Guided Langfuse Pipeline Creation',
+    description: 'Step-by-step guide for creating a Langfuse observability pipeline',
+    variables: [
+      { name: 'trace_name', type: 'string', description: 'Name for the trace/pipeline', required: true },
+      { name: 'user_id', type: 'string', description: 'User identifier for the trace', required: true },
+      { name: 'steps', type: 'string', description: 'Pipeline steps, comma-separated', required: true },
+    ],
+    template: `# Create Langfuse Observability Pipeline
+
+Pipeline Name: {{trace_name}}
+User ID: {{user_id}}
+Pipeline Steps: {{steps}}
+
+1. Create the main trace with coaia_fuse_trace_create.
+2. Add one coaia_fuse_add_observation call per step.
+3. Use parent_id for nested operations.
+4. Inspect the finished trace with coaia_fuse_trace_view.
+
+Prefer input_data and output_data for actual payloads. Keep metadata for labels, environment, model, version, and correlation fields.`,
+  },
+
+  analyze_audio_workflow: {
+    id: 'analyze_audio_workflow',
+    name: 'Audio Transcription & Summarization',
+    description: 'Workflow for audio analysis using coaia',
+    variables: [
+      { name: 'file_path', type: 'string', description: 'Path to the audio file', required: true },
+      {
+        name: 'summary_style',
+        type: 'string',
+        description: 'Summarization style: concise, detailed, or narrative',
+        required: false,
+        default: 'concise',
+      },
+    ],
+    template: `# Audio Analysis Workflow
+
+File Path: {{file_path}}
+Summary Style: {{summary_style}}
+
+1. Transcribe audio with coaia transcribe {{file_path}}.
+2. Summarize the transcript using the requested style.
+3. Store transcript and summary with coaia_tash.
+4. Retrieve them later with coaia_fetch.
+5. Optionally create a Langfuse trace that records transcription and summarization observations.`,
+  },
+};
+
+export function getPrompt(promptId: string): PromptDefinition | undefined {
+  return PROMPTS[promptId];
+}
+
+export function listPrompts(): PromptDefinition[] {
+  return Object.values(PROMPTS).map((prompt) => ({
+    ...prompt,
+    template: '',
+  }));
+}
+
+export function renderPrompt(promptId: string, variables: Record<string, string>): string | null {
+  const prompt = getPrompt(promptId);
+  if (!prompt) return null;
+
+  const finalVars: Record<string, string> = {};
+  for (const variable of prompt.variables) {
+    const provided = variables[variable.name];
+    if (provided != null && provided !== '') {
+      finalVars[variable.name] = provided;
+    } else if (variable.default != null) {
+      finalVars[variable.name] = variable.default;
+    } else if (variable.required) {
+      throw new Error(`Required prompt variable '${variable.name}' not provided`);
+    }
+  }
+
+  return prompt.template.replace(/\{\{([^}]+)\}\}/g, (_match, name: string) => {
+    const key = name.trim();
+    return finalVars[key] ?? '';
+  });
+}

package/mcp/resources.ts

@@ -0,0 +1,84 @@
+// coaiajs/mcp/resources.ts — MCP read-only resources
+// Parity with coaiapy-mcp template resources.
+
+import { TemplateLoader } from '../src/pipeline/index.js';
+
+export async function listTemplates(includePath = false): Promise<Record<string, unknown>> {
+  try {
+    const loader = new TemplateLoader();
+    return {
+      success: true,
+      templates: loader.listTemplates(includePath),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Template list error: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function getTemplate(name: string): Promise<Record<string, unknown>> {
+  try {
+    const loader = new TemplateLoader();
+    const template = loader.loadTemplate(name);
+
+    if (!template) {
+      return {
+        success: false,
+        error: `Template '${name}' not found`,
+      };
+    }
+
+    return {
+      success: true,
+      template,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Template get error: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function getTemplateVariables(name: string): Promise<Record<string, unknown>> {
+  try {
+    const loader = new TemplateLoader();
+    const template = loader.loadTemplate(name);
+
+    if (!template) {
+      return {
+        success: false,
+        error: `Template '${name}' not found`,
+      };
+    }
+
+    return {
+      success: true,
+      variables: template.variables ?? [],
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Template variables error: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function readCoaiaResource(uri: string): Promise<string> {
+  if (uri === 'coaia://templates/') {
+    return JSON.stringify(await listTemplates(), null, 2);
+  }
+
+  if (uri.startsWith('coaia://templates/')) {
+    const resourcePath = uri.replace('coaia://templates/', '').replace(/\/$/, '');
+    if (resourcePath.endsWith('/variables')) {
+      const templateName = resourcePath.replace(/\/variables$/, '');
+      return JSON.stringify(await getTemplateVariables(templateName), null, 2);
+    }
+    return JSON.stringify(await getTemplate(resourcePath), null, 2);
+  }
+
+  return JSON.stringify({ success: false, error: `Unknown resource URI: ${uri}` }, null, 2);
+}