coaiajs 0.1.0

package/articles/technical/dotenv-config-patterns.md

@@ -0,0 +1,360 @@
+# Config Management in Node.js: Technical Assessment for CoAiA.js
+
+> Package selection brief — Configuration cascade replacing coaiapy's multi-file config (env vars > .env > coaia.json > defaults)
+
+## Summary & Recommendation
+
+**Use `dotenv` v16.x + `cosmiconfig` v9.x + `zod` for validation.** This triple replaces coaiapy's hand-rolled config cascade with a standard, validated pattern:
+- `dotenv` loads `.env` files (matching coaiapy's `.coaia-env`)
+- `cosmiconfig` discovers `coaia.json`, `coaia.yaml`, `.coaiarc`, or `coaia.config.js` (matching coaiapy's multi-format loading)
+- `zod` validates the merged config at startup (what coaiapy lacks entirely)
+
+**Pin:**
+```json
+"dotenv": "^16.4.0",
+"cosmiconfig": "^9.0.0",
+"zod": "^4.0.0"
+```
+
+## What We're Replacing
+
+Coaiapy has a complex config cascade across multiple modules:
+
+### environment.py (EnvironmentManager)
+```python
+@dataclass
+class EnvironmentConfig:
+    project_env_file: str = ".coaia-env"
+    global_env_file: str = "~/.coaia/global.env"
+    supported_formats: List[str] = ["json", "env"]
+
+class EnvironmentManager:
+    def _read_env_file(self, file_path: Path) -> Dict[str, Any]:
+        if content.startswith('{'):
+            return json.loads(content)
+        # Parse KEY=value format
+```
+
+### coaiamodule.py (read_config)
+```python
+def read_config():
+    # Priority: env vars > .env > coaia.json > defaults
+    # Searches: cwd, parent dirs, ~/.coaia/
+    # Supports: JSON, .env, shell env vars
+```
+
+### coaia-narrative CLI (minimist + dotenv)
+```typescript
+// Priority order:
+// 1. Command-line flags (--memory-path, -M)
+// 2. Custom env file (--env)
+// 3. .env in cwd
+// 4. _env.sh (fallback)
+// 5. Environment variables
+// 6. Defaults
+```
+
+The Python approach has no validation — missing keys fail at runtime deep in execution. The TypeScript approach in coaia-narrative works but is ad-hoc per module.
+
+## Options Compared
+
+| Feature | dotenv + cosmiconfig + zod | dotenv only | convict | nconf | node-config |
+|---------|--------------------------|-------------|---------|-------|-------------|
+| .env loading | ✅ dotenv | ✅ | ⚠️ Manual | ✅ | ❌ |
+| Multi-format (JSON/YAML/JS) | ✅ cosmiconfig | ❌ | ✅ JSON | ✅ | ✅ |
+| Parent dir search | ✅ cosmiconfig | ❌ | ❌ | ❌ | ❌ |
+| Schema validation | ✅ zod | ❌ | ✅ convict | ❌ | ❌ |
+| Type inference | ✅ zod infer | ❌ | ⚠️ Manual | ❌ | ❌ |
+| Variable expansion | ✅ dotenv-expand | ✅ dotenv-expand | ❌ | ❌ | ❌ |
+| Env override | ✅ process.env priority | ✅ | ✅ | ✅ | ✅ |
+| Weekly downloads | ~93M + ~30M + ~100M | ~93M | ~900K | ~900K | ~1.5M |
+| Bundle overhead | Minimal | Tiny | Medium | Medium | Medium |
+| TypeScript | All have types | ✅ | ⚠️ | ⚠️ | ⚠️ |
+
+## API Overview
+
+### Config Schema (Zod)
+
+```typescript
+// src/config/schema.ts
+import { z } from 'zod';
+
+export const CoaiaConfigSchema = z.object({
+  // Redis
+  redisUrl: z.string().url().default('redis://localhost:6379'),
+  
+  // Langfuse
+  langfusePublicKey: z.string().optional(),
+  langfuseSecretKey: z.string().optional(),
+  langfuseBaseUrl: z.string().url().default('https://cloud.langfuse.com'),
+  
+  // OpenAI
+  openaiApiKey: z.string().optional(),
+  openaiBaseUrl: z.string().url().optional(),
+  openaiModel: z.string().default('gpt-5.4'),
+  
+  // AWS Polly
+  awsRegion: z.string().default('us-east-1'),
+  pollyKey: z.string().optional(),
+  pollySecret: z.string().optional(),
+  
+  // GitHub
+  githubToken: z.string().optional(),
+  
+  // Paths
+  memoryPath: z.string().default('.coaia/memory.jsonl'),
+  plansDir: z.string().default('.coaia/plans'),
+  outputDir: z.string().default('.coaia/output'),
+  templateDir: z.string().default('.coaia/templates'),
+  
+  // Behavior
+  jsonOutput: z.boolean().default(false),
+  noColor: z.boolean().default(false),
+  verbose: z.boolean().default(false),
+});
+
+export type CoaiaConfig = z.infer<typeof CoaiaConfigSchema>;
+```
+
+### Config Loader (cosmiconfig + dotenv)
+
+```typescript
+// src/config/loader.ts
+import { cosmiconfig } from 'cosmiconfig';
+import dotenv from 'dotenv';
+import { CoaiaConfigSchema, type CoaiaConfig } from './schema.js';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+
+// cosmiconfig explorer — searches for config files
+const explorer = cosmiconfig('coaia', {
+  searchPlaces: [
+    'coaia.config.js',
+    'coaia.config.ts',
+    'coaia.json',
+    'coaia.yaml',
+    'coaia.yml',
+    '.coaiarc',
+    '.coaiarc.json',
+    '.coaiarc.yaml',
+    'package.json',  // "coaia" key in package.json
+  ],
+});
+
+let _config: CoaiaConfig | null = null;
+
+export async function loadConfig(overrides?: Partial<CoaiaConfig>): Promise<CoaiaConfig> {
+  if (_config && !overrides) return _config;
+
+  // Step 1: Load .env files (matches coaiapy's .coaia-env pattern)
+  const envFiles = [
+    '.env',
+    '.coaia-env',
+    resolve(process.env.HOME ?? '', '.coaia', 'global.env'),
+  ];
+  
+  for (const envFile of envFiles) {
+    if (existsSync(envFile)) {
+      dotenv.config({ path: envFile });
+    }
+  }
+
+  // Step 2: Load config file via cosmiconfig (searches parent dirs)
+  const result = await explorer.search();
+  const fileConfig = result?.config ?? {};
+
+  // Step 3: Merge sources (priority: CLI overrides > env vars > config file > defaults)
+  const merged = {
+    ...fileConfig,
+    // Env var overrides (matching coaiapy's env var names)
+    ...(process.env.REDIS_URL && { redisUrl: process.env.REDIS_URL }),
+    ...(process.env.UPSTASH_REDIS_URL && { redisUrl: process.env.UPSTASH_REDIS_URL }),
+    ...(process.env.LANGFUSE_PUBLIC_KEY && { langfusePublicKey: process.env.LANGFUSE_PUBLIC_KEY }),
+    ...(process.env.LANGFUSE_SECRET_KEY && { langfuseSecretKey: process.env.LANGFUSE_SECRET_KEY }),
+    ...(process.env.LANGFUSE_BASE_URL && { langfuseBaseUrl: process.env.LANGFUSE_BASE_URL }),
+    ...(process.env.OPENAI_API_KEY && { openaiApiKey: process.env.OPENAI_API_KEY }),
+    ...(process.env.OPENAI_BASE_URL && { openaiBaseUrl: process.env.OPENAI_BASE_URL }),
+    ...(process.env.AWS_REGION && { awsRegion: process.env.AWS_REGION }),
+    ...(process.env.GH_TOKEN && { githubToken: process.env.GH_TOKEN }),
+    ...(process.env.GITHUB_TOKEN && { githubToken: process.env.GITHUB_TOKEN }),
+    ...(process.env.COAIA_MEMORY_PATH && { memoryPath: process.env.COAIA_MEMORY_PATH }),
+    ...(process.env.COAIA_PLANS_DIR && { plansDir: process.env.COAIA_PLANS_DIR }),
+    ...(process.env.COAIA_OUTPUT_DIR && { outputDir: process.env.COAIA_OUTPUT_DIR }),
+    // CLI overrides (highest priority)
+    ...overrides,
+  };
+
+  // Step 4: Validate with Zod
+  _config = CoaiaConfigSchema.parse(merged);
+  return _config;
+}
+
+// Synchronous getter after initial load
+export function getConfig(): CoaiaConfig {
+  if (!_config) throw new Error('Config not loaded. Call loadConfig() first.');
+  return _config;
+}
+```
+
+### CLI Integration with Commander
+
+```typescript
+// src/cli.ts — CLI flags feed into config overrides
+import { Command } from 'commander';
+import { loadConfig } from './config/loader.js';
+
+const program = new Command()
+  .option('-M, --memory-path <path>', 'Memory file path')
+  .option('--env <file>', 'Custom env file path')
+  .option('--json', 'Output as JSON')
+  .option('--no-color', 'Disable colored output')
+  .option('--verbose', 'Verbose logging');
+
+program.hook('preAction', async (thisCommand) => {
+  const opts = thisCommand.opts();
+  
+  // Load custom env file if specified
+  if (opts.env) {
+    dotenv.config({ path: opts.env });
+  }
+  
+  // Initialize config with CLI overrides
+  await loadConfig({
+    ...(opts.memoryPath && { memoryPath: opts.memoryPath }),
+    ...(opts.json && { jsonOutput: true }),
+    ...(opts.color === false && { noColor: true }),
+    ...(opts.verbose && { verbose: true }),
+  });
+});
+```
+
+### Variable Expansion (dotenv-expand)
+
+```typescript
+// For .env files that reference other variables
+// .env:
+// BASE_DIR=/opt/coaia
+// MEMORY_PATH=${BASE_DIR}/memory.jsonl
+// PLANS_DIR=${BASE_DIR}/plans
+
+import dotenv from 'dotenv';
+import { expand } from 'dotenv-expand';
+
+const env = dotenv.config({ path: '.env' });
+expand(env);  // Resolves ${BASE_DIR} references
+```
+
+### Config File Examples
+
+```yaml
+# coaia.yaml — project-level config
+redis:
+  url: redis://localhost:6379
+
+langfuse:
+  publicKey: pk-lf-xxx
+  secretKey: sk-lf-xxx
+  baseUrl: https://cloud.langfuse.com
+
+openai:
+  apiKey: sk-xxx
+  model: gpt-5.4
+
+paths:
+  memory: .coaia/memory.jsonl
+  plans: .coaia/plans
+  templates: .coaia/templates
+```
+
+```json
+// coaia.json — alternative JSON format
+{
+  "redisUrl": "redis://localhost:6379",
+  "langfusePublicKey": "pk-lf-xxx",
+  "openaiModel": "gpt-5.4",
+  "memoryPath": ".coaia/memory.jsonl"
+}
+```
+
+```ini
+# .coaia-env — environment variable format (coaiapy compatible)
+REDIS_URL=redis://localhost:6379
+LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+LANGFUSE_SECRET_KEY=sk-lf-xxx
+OPENAI_API_KEY=sk-xxx
+GH_TOKEN=ghp_xxx
+AWS_REGION=us-east-1
+COAIA_MEMORY_PATH=.coaia/memory.jsonl
+```
+
+### Validation Error Messages
+
+```typescript
+// On startup with invalid config:
+try {
+  await loadConfig();
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    console.error('Configuration errors:');
+    error.issues.forEach(issue => {
+      console.error(`  ${issue.path.join('.')}: ${issue.message}`);
+    });
+    process.exit(1);
+  }
+  throw error;
+}
+
+// Output:
+// Configuration errors:
+//   redisUrl: Invalid url
+//   langfuseBaseUrl: Invalid url
+```
+
+## Integration Plan
+
+1. **Schema:** `src/config/schema.ts` — Zod schema for all config values
+2. **Loader:** `src/config/loader.ts` — dotenv + cosmiconfig + Zod validation
+3. **Export:** `src/config/index.ts` — `loadConfig()` and `getConfig()`
+4. **CLI hook:** Commander `preAction` hook loads config with CLI overrides
+5. **Testing:** Config loader is mockable via overrides parameter
+6. **Migration:** Support both `coaia.json` and `.coaia-env` formats (backward compat)
+
+### Config Priority (matches coaiapy's cascade)
+
+```
+1. CLI flags              (--memory-path, --json)     ← Highest
+2. Environment variables  (REDIS_URL, GH_TOKEN)
+3. .env / .coaia-env      (project root)
+4. ~/.coaia/global.env    (global user config)
+5. coaia.json / coaia.yaml (cosmiconfig search)
+6. Zod defaults           (schema defaults)            ← Lowest
+```
+
+## Version & Ecosystem
+
+| Package | Version | Weekly Downloads | Purpose |
+|---------|---------|-----------------|---------|
+| dotenv | 16.4.x | ~93M | .env file loading |
+| dotenv-expand | 12.0.x | ~30M | Variable expansion in .env |
+| cosmiconfig | 9.0.x | ~30M | Multi-format config discovery |
+| zod | 4.3.x | ~100M+ | Schema validation + type inference |
+
+All packages: MIT licensed, zero or minimal dependencies, TypeScript supported.
+
+## Why Not Convict?
+
+Convict (from Mozilla) offers built-in schema validation, but:
+1. ~900K downloads vs dotenv's ~93M — smaller ecosystem
+2. Doesn't support YAML config files natively
+3. Doesn't search parent directories (cosmiconfig does)
+4. We already have Zod for validation (no need for convict's schema DSL)
+5. Convict's API is less TypeScript-friendly than Zod's type inference
+
+## References
+
+- dotenv npm: https://www.npmjs.com/package/dotenv
+- cosmiconfig npm: https://www.npmjs.com/package/cosmiconfig
+- cosmiconfig GitHub: https://github.com/cosmiconfig/cosmiconfig
+- dotenv security: https://www.johal.in/secrets-dotenv-secure-config-management-in-production-2026/
+- Config comparison: https://npm-compare.com/config,convict,dotenv,nconf
+- dotenv usage: https://oneuptime.com/blog/post/2026-01-25-dotenv-configuration-nodejs/view

package/articles/technical/ioredis-vs-redis.md

@@ -0,0 +1,142 @@
+# ioredis vs node-redis: Technical Assessment for CoAiA.js
+
+> Package selection brief — Redis client for structural tension chart storage, session management, and MCP memory persistence
+
+## Summary & Recommendation
+
+**Use `ioredis` v5.4.x** for coaiajs. Despite Redis Inc. pushing `node-redis` as the official client, ioredis delivers superior ergonomics for our use case: URL-based connection strings (Upstash REST compatibility), built-in cluster support for future scaling, and a smoother pipelining API. The ~14M weekly downloads and battle-tested stability outweigh the marginal concurrency edge of node-redis that we don't need.
+
+**Pin:** `"ioredis": "^5.4.0"`
+
+## What We're Replacing
+
+Coaiapy uses `redis<=4.3.6` (Python redis-py) with a lazy-loading pattern:
+
+```python
+# coaiapy/coaiamodule.py — lazy import for Pythonista compatibility
+def _get_redis():
+    """Lazy import of redis module"""
+    import redis
+    return redis
+```
+
+The Python client connects via URL string and performs simple GET/SET with TTL for session data, chart state, and webhook coordination. coaia-narrative's MCP server (Redis-backed medicine wheel) also uses Redis for ceremony state.
+
+## Options Compared
+
+| Feature | ioredis v5.4 | node-redis v4.7 |
+|---------|-------------|-----------------|
+| Weekly npm downloads | ~14–15M | ~8–9M |
+| GitHub stars | ~15,000 | ~17,000 |
+| Connection from URL | `new Redis(url)` — native | `createClient({ url })` — native |
+| Upstash REST compat | Via `@upstash/redis` wrapper or direct URL | Via `@upstash/redis` wrapper |
+| GET/SET with TTL | `redis.set(key, val, 'EX', ttl)` | `client.set(key, val, { EX: ttl })` |
+| Pipelining | `redis.pipeline().set().get().exec()` | `client.multi().set().get().exec()` |
+| Cluster support | Built-in, first-class | Available but newer |
+| Auto-reconnect | Built-in with backoff | Built-in with strategy |
+| TypeScript | `@types/ioredis` bundled | Native types |
+| Concurrent 100-SET ops/sec | ~2,500 | ~3,800 |
+| Sequential GET ops/sec | ~8,700 | ~7,900 |
+| Lua scripting | First-class `defineCommand()` | Supported |
+| Streams API | Rich ergonomic API | Supported |
+
+## API Overview
+
+### Connection Pattern for coaiajs
+
+```typescript
+import Redis from 'ioredis';
+import { loadConfig } from '../config.js';
+
+// Connection from URL (matches coaiapy pattern)
+const config = loadConfig();
+const redis = new Redis(config.redisUrl ?? 'redis://localhost:6379');
+
+// With Upstash (TLS URL)
+const upstashRedis = new Redis(process.env.UPSTASH_REDIS_URL!, {
+  tls: { rejectUnauthorized: false },
+  lazyConnect: true,  // matches coaiapy's lazy pattern
+});
+```
+
+### Core Operations We Need
+
+```typescript
+// Session storage with TTL
+async function saveSession(sessionId: string, data: object, ttlSeconds = 3600): Promise<void> {
+  await redis.set(`session:${sessionId}`, JSON.stringify(data), 'EX', ttlSeconds);
+}
+
+async function loadSession(sessionId: string): Promise<object | null> {
+  const raw = await redis.get(`session:${sessionId}`);
+  return raw ? JSON.parse(raw) : null;
+}
+
+// Chart state persistence (coaia-narrative pattern)
+async function saveChart(chartId: string, chart: object): Promise<void> {
+  await redis.hset(`chart:${chartId}`, {
+    data: JSON.stringify(chart),
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+// Pipeline for batch operations
+async function loadMultipleCharts(ids: string[]): Promise<Map<string, object>> {
+  const pipeline = redis.pipeline();
+  ids.forEach(id => pipeline.hgetall(`chart:${id}`));
+  const results = await pipeline.exec();
+  // ... process results
+}
+```
+
+### Lazy Connection Pattern (matching coaiapy)
+
+```typescript
+let _redis: Redis | null = null;
+
+export function getRedis(): Redis {
+  if (!_redis) {
+    const url = process.env.REDIS_URL ?? process.env.UPSTASH_REDIS_URL ?? 'redis://localhost:6379';
+    _redis = new Redis(url, { lazyConnect: true });
+  }
+  return _redis;
+}
+```
+
+## Integration Plan
+
+1. **Core module:** `src/redis.ts` — connection singleton, lazy init, URL-from-config
+2. **Session storage:** `src/session.ts` — GET/SET with TTL for webhook session management
+3. **Chart persistence:** `src/narrative/redis-store.ts` — HSET/HGETALL for structural tension charts
+4. **MCP memory:** `mcp/tools/memory.ts` — Redis-backed tool state for MCP servers
+5. **Graceful shutdown:** `redis.quit()` in process exit handlers
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | 5.4.2 (March 2026) |
+| Weekly downloads | ~14.5M |
+| TypeScript | Built-in types since v5 |
+| Node.js compat | ≥14 (we target ≥20) |
+| Maintenance | Active, regular releases |
+| License | MIT |
+| Bundle size | ~85KB minified |
+
+## Why Not node-redis?
+
+1. **Connection API ergonomics**: ioredis accepts URL in constructor directly; node-redis requires `createClient()` factory
+2. **Cluster future-proofing**: ioredis has years of battle-tested cluster support
+3. **Pipelining**: ioredis pipeline API is cleaner for our batch chart operations
+4. **Lazy connect**: `lazyConnect: true` maps directly to coaiapy's lazy import pattern
+5. **Ecosystem**: Used by Bull, BullMQ, and most Redis-dependent MCP servers we integrate with
+
+The 3,800 vs 2,500 ops/sec concurrent difference in node-redis's favor is irrelevant — coaiajs is an agent framework, not a high-throughput data pipeline.
+
+## References
+
+- npm: https://www.npmjs.com/package/ioredis
+- GitHub: https://github.com/redis/ioredis
+- Benchmark: https://glama.ai/blog/2026-01-26-redis-vs-ioredis-vs-valkey-glide
+- npm trends: https://npmtrends.com/ioredis-vs-redis
+- Redis migration guide: https://redis.io/docs/latest/develop/clients/nodejs/migration/

package/articles/technical/langfuse-js-sdk-vs-rest.md

@@ -0,0 +1,191 @@
+# Langfuse JS SDK vs REST API: Technical Assessment for CoAiA.js
+
+> Package selection brief — LLM observability, tracing, and prompt management for CoAiA agent sessions
+
+## Summary & Recommendation
+
+**Use `langfuse` v4.x SDK** (`@langfuse/core` + `@langfuse/tracing`). The v4 rewrite (August 2025) brings OpenTelemetry-native tracing, modular packages, and direct integration with OpenAI — eliminating coaiapy's manual HTTP request overhead. The SDK handles batching, retries, and serialization that our REST wrapper currently does manually in `cofuse.py`.
+
+**Pin:** `"langfuse": "^4.0.0"` (pulls `@langfuse/core`, `@langfuse/tracing`)
+
+## What We're Replacing
+
+Coaiapy uses raw HTTP requests to the Langfuse REST API via Python `requests`:
+
+```python
+# coaiapy/cofuse.py — manual HTTP approach
+import requests
+from requests.auth import HTTPBasicAuth
+
+def create_session_and_save():
+    # Manual JSON construction, auth header assembly, error handling
+    response = requests.post(f"{base_url}/api/public/traces", 
+                            json=payload, 
+                            auth=HTTPBasicAuth(public_key, secret_key))
+
+def add_trace_node_and_save():
+    # More manual HTTP calls...
+
+def list_traces():
+    response = requests.get(f"{base_url}/api/public/traces", ...)
+```
+
+This pattern requires ~200 lines of boilerplate for authentication, serialization, error handling, and retry logic that the SDK provides out of the box.
+
+## Options Compared
+
+| Feature | Langfuse JS SDK v4 | REST API (manual) |
+|---------|-------------------|-------------------|
+| Setup complexity | `new Langfuse({ publicKey, secretKey })` | Manual auth headers, URL construction |
+| Trace creation | `langfuse.trace({ name, metadata })` | `POST /api/public/traces` + JSON body |
+| Span nesting | `trace.span({ name })` → `span.generation()` | Manual parent-child ID tracking |
+| OpenAI integration | `@langfuse/openai` drop-in wrapper | Manual extraction of token counts |
+| Batch flush | Automatic with configurable intervals | Manual batching implementation |
+| Retry logic | Built-in exponential backoff | Manual retry loops |
+| OpenTelemetry | Native OTEL span processor | Not available |
+| Type safety | Full TypeScript types | Manual interface definitions |
+| Prompt management | `langfuse.getPrompt()` | `GET /api/public/prompts` |
+| Scoring | `trace.score({ name, value })` | `POST /api/public/scores` + JSON body |
+| MCP server integration | Native via hosted MCP | Manual tool definitions |
+| Maintenance burden | ~5 lines setup | ~200+ lines of wrapper code |
+
+## API Overview
+
+### SDK Initialization
+
+```typescript
+import { Langfuse } from 'langfuse';
+import { loadConfig } from '../config.js';
+
+const config = loadConfig();
+const langfuse = new Langfuse({
+  publicKey: config.langfusePublicKey,
+  secretKey: config.langfuseSecretKey,
+  baseUrl: config.langfuseBaseUrl ?? 'https://cloud.langfuse.com',
+});
+```
+
+### Trace Creation (replacing cofuse.py create_session_and_save)
+
+```typescript
+// coaiapy equivalent: create_session_and_save()
+async function createAgentSession(sessionId: string, metadata: Record<string, unknown>) {
+  const trace = langfuse.trace({
+    id: sessionId,
+    name: `coaia-session-${sessionId}`,
+    metadata,
+    tags: ['coaiajs', 'agent-session'],
+  });
+
+  // Nested spans for pipeline steps
+  const span = trace.span({ name: 'pipeline-execution' });
+  
+  // Generation tracking (replaces add_trace_node_and_save)
+  const generation = span.generation({
+    name: 'llm-call',
+    model: 'gpt-5.4',
+    input: messages,
+    output: response,
+    usage: { promptTokens: 150, completionTokens: 300 },
+  });
+
+  generation.end();
+  span.end();
+  
+  return trace;
+}
+```
+
+### OpenAI Integration (automatic tracing)
+
+```typescript
+import { observeOpenAI } from '@langfuse/openai';
+import OpenAI from 'openai';
+
+// Wraps OpenAI client for automatic trace capture
+const openai = observeOpenAI(new OpenAI(), {
+  langfuse,
+  generationName: 'coaia-generation',
+});
+
+// Every call is automatically traced
+const response = await openai.chat.completions.create({
+  model: 'gpt-5.4',
+  messages: [{ role: 'user', content: 'Analyze this chart...' }],
+});
+```
+
+### Prompt Management
+
+```typescript
+// Fetch versioned prompts from Langfuse
+const prompt = await langfuse.getPrompt('pde-decompose-system');
+const compiled = prompt.compile({ context: 'structural tension chart' });
+```
+
+### Scoring (replacing cofuse.py create_score, apply_score_to_trace)
+
+```typescript
+async function scoreTrace(traceId: string, scores: Record<string, number>) {
+  for (const [name, value] of Object.entries(scores)) {
+    langfuse.score({
+      traceId,
+      name,
+      value,
+      comment: `MMOT evaluation: ${name}`,
+    });
+  }
+  await langfuse.flushAsync();
+}
+```
+
+## Integration Plan
+
+1. **Core module:** `src/langfuse/client.ts` — singleton Langfuse instance from config
+2. **Session tracing:** `src/langfuse/session.ts` — trace lifecycle for agent sessions (replaces cofuse.py)
+3. **OpenAI wrapper:** `src/langfuse/openai.ts` — `observeOpenAI` integration for automatic tracing
+4. **Scoring:** `src/langfuse/scoring.ts` — MMOT evaluation scoring
+5. **Prompt management:** `src/langfuse/prompts.ts` — versioned prompt fetching
+6. **Pipeline integration:** `src/pipeline/traced-step.ts` — auto-trace pipeline template execution
+
+### When to Fall Back to REST
+
+Keep a thin REST utility for edge cases:
+- Langfuse endpoints not yet covered by SDK v4
+- Direct database queries for custom dashboards
+- Webhook payload verification
+
+```typescript
+// Escape hatch for REST-only endpoints
+async function langfuseRest(path: string, method = 'GET', body?: object) {
+  const config = loadConfig();
+  const auth = Buffer.from(`${config.langfusePublicKey}:${config.langfuseSecretKey}`).toString('base64');
+  return fetch(`${config.langfuseBaseUrl}/api/public${path}`, {
+    method,
+    headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+}
+```
+
+## Version & Ecosystem
+
+| Metric | Value |
+|--------|-------|
+| Current version | v4.x (rewritten Aug 2025) |
+| Packages | `langfuse`, `@langfuse/core`, `@langfuse/tracing`, `@langfuse/openai` |
+| Tracing standard | OpenTelemetry native |
+| Node.js compat | ≥20 |
+| TypeScript | Full native types |
+| Bundle | Modular tree-shakeable |
+| Integrations | OpenAI, LangChain, Vercel AI SDK |
+| MCP | Hosted MCP server for prompt management |
+| License | MIT |
+
+## References
+
+- npm: https://www.npmjs.com/package/langfuse
+- GitHub: https://github.com/langfuse/langfuse-js
+- Docs: https://langfuse.com/docs/sdk/typescript
+- Changelog: https://langfuse.com/changelog
+- DeepWiki architecture: https://deepwiki.com/langfuse/langfuse-js