@aperdomoll90/ledger-ai 1.3.0 → 1.4.2

package/dist/lib/observability.js

@@ -0,0 +1,296 @@
+// observability.ts
+// Langfuse tracing integration for pipeline observability.
+//
+// Provides trace/span helpers for instrumenting Ledger's ingestion pipeline.
+// When Langfuse env vars are absent, all functions no-op silently.
+// Ledger works identically with or without observability enabled.
+//
+// Built on OpenTelemetry (OTel), the industry-standard tracing protocol.
+// Langfuse acts as the trace collector and dashboard. The OTel foundation
+// means switching to Datadog, Grafana Tempo, or Jaeger requires swapping
+// the exporter, not the instrumentation.
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { LangfuseSpanProcessor } from '@langfuse/otel';
+import { setLangfuseTracerProvider, startObservation, startActiveObservation } from '@langfuse/tracing';
+import { propagateAttributes } from '@langfuse/core';
+import { trace as otelTrace, context as otelContext } from '@opentelemetry/api';
+// =============================================================================
+// State
+// =============================================================================
+let provider = null;
+let enabled = false;
+const NOOP_HANDLE = {
+    update: () => { },
+    end: () => { },
+};
+const NOOP_ACTIVE_HANDLE = {
+    update: () => { },
+    end: () => { },
+    _otelSpan: null,
+};
+// =============================================================================
+// Init / Shutdown
+// =============================================================================
+/**
+ * Initialize Langfuse observability.
+ * Returns true if enabled, false if skipped (missing env vars).
+ *
+ * Call once at CLI startup. Safe to call multiple times (idempotent).
+ */
+export function initObservability() {
+    if (enabled)
+        return true;
+    const publicKey = process.env.LANGFUSE_PUBLIC_KEY;
+    const secretKey = process.env.LANGFUSE_SECRET_KEY;
+    const baseUrl = process.env.LANGFUSE_BASE_URL;
+    if (!publicKey || !secretKey)
+        return false;
+    provider = new NodeTracerProvider({
+        spanProcessors: [
+            new LangfuseSpanProcessor({
+                publicKey,
+                secretKey,
+                baseUrl: baseUrl ?? 'http://localhost:9100',
+                environment: process.env.NODE_ENV ?? 'development',
+                exportMode: 'batched',
+                flushAt: 10,
+                flushInterval: 2,
+            }),
+        ],
+    });
+    // Register the provider globally AND install an async context manager so
+    // propagateAttributes() can pass sessionId/tags through to child spans
+    // across `await` boundaries. Without this, propagated attributes never
+    // reach the root trace record in Langfuse.
+    provider.register();
+    setLangfuseTracerProvider(provider);
+    enabled = true;
+    return true;
+}
+/**
+ * Flush pending traces and shut down the provider.
+ * Call before process exit to ensure all traces are sent.
+ */
+export async function shutdownObservability() {
+    if (!provider)
+        return;
+    await provider.forceFlush();
+    await provider.shutdown();
+    provider = null;
+    enabled = false;
+}
+/**
+ * Check if observability is currently enabled.
+ */
+export function isObservabilityEnabled() {
+    return enabled;
+}
+// =============================================================================
+// Trace / Span helpers
+// =============================================================================
+/**
+ * Start a new trace (root-level observation).
+ * Use for top-level operations like document ingestion.
+ *
+ * Returns a handle with update() and end() methods.
+ * When observability is disabled, returns a no-op handle.
+ */
+export function startTrace(name, options) {
+    if (!enabled)
+        return NOOP_HANDLE;
+    const observation = startObservation(name, {
+        input: options?.input,
+        metadata: { ...options?.metadata, tags: options?.tags },
+    });
+    return {
+        update: (data) => observation.update(data),
+        end: () => observation.end(),
+    };
+}
+/**
+ * Start a span (child observation within a trace).
+ * Use for pipeline steps like chunking, enrichment, embedding, DB write.
+ *
+ * Uses the OTel tracer so spans automatically nest under the active context
+ * set by startActiveObservation in runSearchTrace. Langfuse's startObservation
+ * does NOT read OTel context, so using it here would create orphaned traces.
+ *
+ * Returns a handle with update() and end() methods.
+ * When observability is disabled, returns a no-op handle.
+ */
+export function startSpan(name, options) {
+    if (!enabled)
+        return NOOP_ACTIVE_HANDLE;
+    const tracer = otelTrace.getTracer('langfuse-sdk');
+    const span = tracer.startSpan(name);
+    if (options?.input) {
+        span.setAttribute('langfuse.span.input', JSON.stringify(options.input));
+    }
+    if (options?.metadata) {
+        span.setAttribute('langfuse.span.metadata', JSON.stringify(options.metadata));
+    }
+    return {
+        update: (data) => {
+            for (const [key, value] of Object.entries(data)) {
+                span.setAttribute(`langfuse.span.${key}`, typeof value === 'string' ? value : JSON.stringify(value));
+            }
+        },
+        end: () => span.end(),
+        _otelSpan: span,
+    };
+}
+/**
+ * Open a root trace for a search operation.
+ *
+ * Attaches environment (prod/eval/dev), sessionId, tags, input, metadata so
+ * the Langfuse dashboard can slice traces by any of those dimensions.
+ *
+ * Returns a handle with update() and end() methods. The caller is expected to
+ * call .update({ output: {...} }) before .end() to record resultCount, cacheHit,
+ * topResultIds, etc. No-op when observability is disabled.
+ */
+/**
+ * Run a search operation inside an open Langfuse trace.
+ *
+ * Wraps `work` in a `propagateAttributes` context so sessionId, tags, and
+ * environment are attached to the root trace as first-class indexed fields
+ * (not metadata). All spans created inside `work` inherit that context.
+ *
+ * Langfuse's SDK only exposes this via a callback pattern — there is no
+ * imperative "open context, return handle, close later" API. Hence the HOF.
+ *
+ * When observability is disabled, `work` runs with a no-op handle and no
+ * tracing overhead.
+ */
+export async function runSearchTrace(props, work) {
+    if (!enabled)
+        return work(NOOP_HANDLE);
+    return propagateAttributes({
+        sessionId: props.sessionId,
+        tags: ['search', props.mode],
+    }, async () => {
+        // startActiveObservation (not startObservation) makes this the ACTIVE
+        // OpenTelemetry span, so any spans created inside `work` nest under it
+        // instead of being emitted as orphan top-level traces.
+        return startActiveObservation('search', async (observation) => {
+            // sessionId and tags are accepted at runtime but not in LangfuseSpanAttributes.
+            // propagateAttributes sets them in OTel context (metadata), but observation.update
+            // is needed to promote them to first-class indexed fields on the trace record.
+            observation.update({
+                input: props.input ?? { query: props.query },
+                metadata: props.metadata,
+                environment: props.environment,
+                ...{ sessionId: props.sessionId, tags: ['search', props.mode] },
+            });
+            const handle = {
+                update: (data) => observation.update(data),
+                end: () => observation.end(),
+            };
+            return work(handle);
+        });
+    });
+}
+/**
+ * Run an eval execution inside an open Langfuse trace.
+ *
+ * Creates a root trace named 'eval-run' that groups all per-query spans
+ * under one session. The search traces from Phase 2 (runSearchTrace)
+ * auto-nest under per-query spans via OTel context propagation.
+ *
+ * When observability is disabled, `work` runs with a no-op handle.
+ */
+export async function runEvalTrace(props, work) {
+    if (!enabled)
+        return work(NOOP_HANDLE);
+    const tags = props.dryRun ? [...props.tags, 'dry-run'] : props.tags;
+    return propagateAttributes({
+        sessionId: props.sessionId,
+        tags,
+    }, async () => {
+        return startActiveObservation('eval-run', async (observation) => {
+            observation.update({
+                input: props.config,
+                environment: 'eval',
+                ...{ sessionId: props.sessionId, tags },
+            });
+            const handle = {
+                update: (data) => observation.update(data),
+                end: () => observation.end(),
+            };
+            return work(handle);
+        });
+    });
+}
+/**
+ * Run a single eval query inside a child span of the eval trace.
+ *
+ * Wraps the searchHybrid call + scoring for one golden dataset query.
+ * The search trace (runSearchTrace) fires inside this span and auto-nests.
+ *
+ * When observability is disabled, `work` runs with a no-op handle.
+ */
+export async function runEvalQuerySpan(props, work) {
+    if (!enabled)
+        return work(NOOP_HANDLE);
+    return startActiveObservation('eval-query', async (observation) => {
+        observation.update({
+            input: {
+                query: props.query,
+                goldenId: props.goldenId,
+                tags: props.tags,
+                expectedDocs: props.expectedDocs,
+            },
+        });
+        const handle = {
+            update: (data) => observation.update(data),
+            end: () => observation.end(),
+        };
+        return work(handle);
+    });
+}
+// =============================================================================
+// Child span helpers
+// =============================================================================
+/**
+ * Emit a completed span with pre-computed duration.
+ *
+ * Used for sub-steps whose timing was measured elsewhere (e.g., the three
+ * retrieve.* sub-spans derived from the Postgres timing sidecar). Unlike
+ * startSpan, this does not return a handle. The span opens and closes
+ * immediately, carrying the measured duration as attributes.
+ *
+ * Uses OTel tracer so spans nest under the active context (same reason as
+ * startSpan). The startTime parameter backdates the span to align with the
+ * measured window.
+ *
+ * No-op when observability is disabled.
+ */
+export function recordChildSpan(name, startMs, endMs, attributes) {
+    if (!enabled)
+        return;
+    const tracer = otelTrace.getTracer('langfuse-sdk');
+    const span = tracer.startSpan(name, { startTime: startMs });
+    span.setAttribute('langfuse.span.metadata', JSON.stringify({
+        ...attributes,
+        startMs,
+        endMs,
+        durationMs: endMs - startMs,
+        synthetic: true,
+    }));
+    span.end(endMs);
+}
+/**
+ * Execute work within an active OTel context for the given span.
+ *
+ * Child spans created inside `work` (via startSpan or recordChildSpan)
+ * will nest under this span. Used to activate a passive span created
+ * by startSpan before calling code that needs to emit children.
+ *
+ * No-op when observability is disabled or span has no OTel reference.
+ */
+export async function withActiveSpan(handle, work) {
+    const activeHandle = handle;
+    if (!enabled || !activeHandle._otelSpan)
+        return work();
+    return otelContext.with(otelTrace.setSpan(otelContext.active(), activeHandle._otelSpan), work);
+}

package/dist/lib/op-add-note-types.test.js

@@ -85,21 +85,22 @@ describe('opAddNote — unknown type handling', () => {
 describe('opAddNote — type registration', () => {
     it('registers type and saves note when register_type is true', async () => {
         const clients = createMockClients();
-        const result = await opAddNote(clients, 'Tasting notes for 2024 Malbec', 'wine-log', 'claude-code', { upsert_key: 'wine-2024-malbec', description: 'Tasting notes', delivery: 'project' }, false, true);
+        const result = await opAddNote(clients, 'Tasting notes for 2024 Malbec', 'wine-log', 'claude-code', { upsert_key: 'wine-2024-malbec', description: 'Tasting notes', domain: 'general' }, false, true);
         // Should succeed (type got registered mid-call)
         expect(result.status).toBe('ok');
-        // Type should now be in config
-        expect(mockConfigState.current.types?.['wine-log']).toBe('project');
+        // Unknown type defaults to general domain → knowledge delivery tier
+        expect(mockConfigState.current.types?.['wine-log']).toBe('knowledge');
     });
-    it('defaults delivery to knowledge when not specified', async () => {
+    it('defaults to general tier for unknown types (inferred from domain)', async () => {
         const clients = createMockClients();
-        await opAddNote(clients, 'My recipe content', 'recipe', 'claude-code', { upsert_key: 'recipe-pasta', description: 'Pasta recipe' }, false, true);
+        await opAddNote(clients, 'My recipe content', 'recipe', 'claude-code', { upsert_key: 'recipe-pasta', description: 'Pasta recipe', status: 'active' }, false, true);
+        // Unknown types default to general domain, which maps to knowledge delivery tier
         expect(mockConfigState.current.types?.['recipe']).toBe('knowledge');
     });
     it('registered type persists for subsequent calls', async () => {
         const clients = createMockClients();
         // First call: register
-        await opAddNote(clients, 'First wine note', 'wine-log', 'claude-code', { upsert_key: 'wine-1', description: 'First', delivery: 'project' }, false, true);
+        await opAddNote(clients, 'First wine note', 'wine-log', 'claude-code', { upsert_key: 'wine-1', description: 'First', domain: 'project' }, false, true);
         // Second call: should NOT need register_type anymore
         const result = await opAddNote(clients, 'Second wine note', 'wine-log', 'claude-code', { upsert_key: 'wine-2', description: 'Second' }, false, false);
         expect(result.status).toBe('ok');

package/dist/lib/prompt.js

@@ -19,9 +19,9 @@ export async function askMasked(question) {
             process.stdin.setRawMode(true);
         }
         process.stdin.resume();
-        const onData = (buf) => {
-            const c = buf.toString();
-            if (c === '\n' || c === '\r') {
+        const onData = (buffer) => {
+            const char = buffer.toString();
+            if (char === '\n' || char === '\r') {
                 process.stdin.removeListener('data', onData);
                 if (process.stdin.isTTY) {
                     process.stdin.setRawMode(false);
@@ -30,18 +30,18 @@ export async function askMasked(question) {
                 process.stderr.write('\n');
                 resolve(input.trim());
             }
-            else if (c === '\u007f' || c === '\b') {
+            else if (char === '\u007f' || char === '\b') {
                 if (input.length > 0) {
                     input = input.slice(0, -1);
                     process.stderr.write('\b \b');
                 }
             }
-            else if (c === '\u0003') {
+            else if (char === '\u0003') {
                 // Ctrl+C
                 process.exit(1);
             }
             else {
-                input += c;
+                input += char;
                 process.stderr.write('*');
             }
         };
@@ -53,13 +53,13 @@ export async function confirm(question) {
     return answer === 'y' || answer === 'yes';
 }
 export async function choose(question, options) {
-    const optionList = options.map((o, i) => `  ${i + 1}. ${o}`).join('\n');
+    const optionList = options.map((option, index) => `  ${index + 1}. ${option}`).join('\n');
     const answer = await ask(`${question}\n${optionList}\n> `);
     const index = parseInt(answer, 10) - 1;
     if (index >= 0 && index < options.length) {
         return options[index];
     }
     // Try matching by name
-    const match = options.find(o => o.toLowerCase().startsWith(answer));
+    const match = options.find(option => option.toLowerCase().startsWith(answer));
     return match || options[0];
 }

package/dist/lib/rate-limiter.js

@@ -0,0 +1,103 @@
+// rate-limiter.ts
+// Provider-agnostic rate limiter using Bottleneck.
+//
+// Proactive pacing layer: controls how many API requests go out per minute
+// and how many can run concurrently. Prevents 429 errors before they happen.
+//
+// The OpenAI SDK handles reactive retry (backoff after 429). This module
+// handles proactive pacing (don't hit 429 in the first place).
+//
+// Usage: import the singleton instances (openaiLimiter, cohereLimiter) and
+// wrap API calls with limiter.schedule(() => apiCall()).
+import Bottleneck from 'bottleneck';
+// =============================================================================
+// Provider presets
+// =============================================================================
+// OpenAI Tier 1: 500 RPM. Safety margin: 90% = 450 RPM.
+export const OPENAI_PRESET = {
+    maxConcurrent: 10,
+    reservoirAmount: 450,
+    reservoirRefreshInterval: 60_000,
+    minTime: 100,
+    retryLimit: 3,
+};
+// Cohere trial: 100 RPM. Safety margin: 90% = 90 RPM.
+export const COHERE_PRESET = {
+    maxConcurrent: 5,
+    reservoirAmount: 90,
+    reservoirRefreshInterval: 60_000,
+    minTime: 200,
+    retryLimit: 3,
+};
+// =============================================================================
+// Retryable status codes
+// =============================================================================
+const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+function isRetryableError(error) {
+    if (error && typeof error === 'object' && 'status' in error) {
+        return RETRYABLE_STATUS_CODES.has(error.status);
+    }
+    return false;
+}
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create a rate limiter with the given config.
+ *
+ * Returns a Bottleneck instance with:
+ * - Reservoir-based rate limiting (token bucket, refills each window)
+ * - Concurrency control (maxConcurrent parallel jobs)
+ * - Minimum spacing between requests (minTime)
+ * - Automatic retry on 429 and 5xx errors with exponential backoff
+ */
+export function createRateLimiter(config) {
+    const limiter = new Bottleneck({
+        maxConcurrent: config.maxConcurrent,
+        reservoir: config.reservoirAmount,
+        reservoirRefreshAmount: config.reservoirAmount,
+        reservoirRefreshInterval: config.reservoirRefreshInterval,
+        minTime: config.minTime,
+    });
+    // Retry handler: Bottleneck calls this on job failure.
+    // Return a number (ms to wait) to retry, or void/undefined to give up.
+    limiter.on('failed', (error, jobInfo) => {
+        if (isRetryableError(error) && jobInfo.retryCount < config.retryLimit) {
+            // Exponential backoff with jitter: 1s, 2s, 4s, ...
+            const baseDelay = 1000 * Math.pow(2, jobInfo.retryCount);
+            const jitter = baseDelay * 0.25 * Math.random();
+            return baseDelay + jitter;
+        }
+        // Non-retryable or retries exhausted: don't retry (error propagates)
+        return undefined;
+    });
+    return limiter;
+}
+// =============================================================================
+// Adaptive header reading
+// =============================================================================
+/**
+ * Adjust the limiter's reservoir based on OpenAI rate limit response headers.
+ *
+ * If OpenAI reports fewer remaining requests than our reservoir thinks,
+ * we adjust downward. This self-tunes without replacing the static baseline.
+ *
+ * Call this after each successful API request.
+ */
+export async function updateLimitsFromHeaders(limiter, headers) {
+    const remaining = headers.get('x-ratelimit-remaining-requests');
+    if (remaining === null)
+        return;
+    const remainingCount = parseInt(remaining, 10);
+    if (isNaN(remainingCount))
+        return;
+    const currentReservoir = await limiter.currentReservoir();
+    if (currentReservoir !== null && remainingCount < currentReservoir) {
+        await limiter.updateSettings({ reservoir: remainingCount });
+    }
+}
+// =============================================================================
+// Singleton instances
+// =============================================================================
+export const openaiLimiter = createRateLimiter(OPENAI_PRESET);
+export const cohereLimiter = createRateLimiter(COHERE_PRESET);