arkna-sdk 0.1.0

package/dist/init.js

@@ -0,0 +1,333 @@
+"use strict";
+/**
+ * ARKNA Auto-Instrumentation for Node.js
+ *
+ * Usage:
+ *   import { init } from '@arkna/sdk';
+ *   init('intk_...');
+ *
+ * Or with env vars:
+ *   ARKNA_TOKEN=intk_... node app.js
+ *   import { init } from '@arkna/sdk';
+ *   init();
+ *
+ * All OpenAI and Anthropic SDK calls are automatically recorded as ARKNA runs.
+ * Each LLM call becomes a run with a reasoning step. Use trace() to group
+ * multiple LLM calls into a single run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+exports.trace = trace;
+exports.shutdown = shutdown;
+const async_hooks_1 = require("async_hooks");
+const _config = { apiKey: '', ingestionUrl: '', debug: false };
+let _initialized = false;
+const _runCtx = new async_hooks_1.AsyncLocalStorage();
+// ── HTTP helpers (zero dependencies, uses Node 18+ fetch) ───
+async function _post(path, body) {
+    try {
+        const resp = await fetch(`${_config.ingestionUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                'X-Integration-Token': _config.apiKey,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(10_000),
+        });
+        return resp.ok ? await resp.json() : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function _patch(path, body) {
+    try {
+        const resp = await fetch(`${_config.ingestionUrl}${path}`, {
+            method: 'PATCH',
+            headers: {
+                'X-Integration-Token': _config.apiKey,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(10_000),
+        });
+        return resp.ok ? await resp.json() : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Cost estimation (per 1K tokens, USD) ────────────────────
+const _COSTS = {
+    'gpt-4o': [0.0025, 0.01],
+    'gpt-4o-mini': [0.00015, 0.0006],
+    'gpt-4-turbo': [0.01, 0.03],
+    'gpt-4': [0.03, 0.06],
+    'gpt-3.5-turbo': [0.0005, 0.0015],
+    'claude-opus-4-6': [0.015, 0.075],
+    'claude-sonnet-4-5-20250929': [0.003, 0.015],
+    'claude-haiku-4-5-20251001': [0.0008, 0.004],
+    'claude-3-5-sonnet-20241022': [0.003, 0.015],
+    'claude-3-haiku-20240307': [0.00025, 0.00125],
+};
+function _costCents(model, inp, out) {
+    let c = _COSTS[model];
+    if (!c) {
+        for (const [k, v] of Object.entries(_COSTS)) {
+            if (model.startsWith(k)) {
+                c = v;
+                break;
+            }
+        }
+    }
+    if (!c)
+        return 0;
+    return Math.round(((inp / 1000) * c[0] + (out / 1000) * c[1]) * 10000) / 100;
+}
+// ── Recording (fire-and-forget) ─────────────────────────────
+function _record(provider, model, input, output, durationMs, tokens, error) {
+    const run = _runCtx.getStore();
+    const cost = _costCents(model, tokens.inp, tokens.out);
+    const stepBody = {
+        step_type: error ? 'error' : 'reasoning',
+        input: input.substring(0, 10000),
+        output: (error ? `${error.type}: ${error.message}` : output).substring(0, 10000),
+        duration_ms: durationMs,
+        tokens_used: tokens.total || undefined,
+        cost_cents: cost || undefined,
+        metadata: {
+            provider,
+            model,
+            prompt_tokens: tokens.inp,
+            completion_tokens: tokens.out,
+        },
+    };
+    if (error) {
+        stepBody.error_type = error.type;
+        stepBody.error_message = error.message;
+    }
+    if (run) {
+        // Inside a trace() — record as step in existing run
+        _post(`/runs/${run.runId}/steps`, stepBody).catch(() => { });
+        run.stepCount++;
+    }
+    else {
+        // Standalone call — create run → record step → complete run
+        (async () => {
+            const r = await _post('/runs', {
+                trigger_type: 'auto',
+                input: input.substring(0, 5000),
+                metadata: { provider, model, auto_instrumented: true },
+            });
+            if (!r?.run_id)
+                return;
+            await _post(`/runs/${r.run_id}/steps`, stepBody);
+            const completeBody = {
+                status: error ? 'failed' : 'completed',
+                output: output.substring(0, 5000),
+                total_tokens: tokens.total || undefined,
+                total_cost_cents: cost || undefined,
+            };
+            if (error) {
+                completeBody.error_type = error.type;
+                completeBody.error_message = error.message;
+            }
+            await _patch(`/runs/${r.run_id}`, completeBody);
+        })().catch(() => { });
+    }
+}
+// ── OpenAI patch ────────────────────────────────────────────
+function _patchOpenAI() {
+    try {
+        const mod = require('openai/resources/chat/completions');
+        const Cls = mod.Completions;
+        if (!Cls?.prototype?.create || Cls.prototype.create.__arkna)
+            return false;
+        const orig = Cls.prototype.create;
+        const patched = async function (body, opts) {
+            const t0 = Date.now();
+            const msgs = body?.messages;
+            const inputStr = Array.isArray(msgs)
+                ? JSON.stringify(msgs.slice(-3))
+                : String(msgs ?? '');
+            try {
+                const res = await orig.call(this, body, opts);
+                if (!body?.stream && res?.choices) {
+                    const out = res.choices[0]?.message?.content ?? '';
+                    const u = res.usage ?? {};
+                    _record('openai', body.model ?? 'unknown', inputStr, out, Date.now() - t0, {
+                        inp: u.prompt_tokens ?? 0,
+                        out: u.completion_tokens ?? 0,
+                        total: u.total_tokens ?? 0,
+                    });
+                }
+                return res;
+            }
+            catch (e) {
+                _record('openai', body?.model ?? 'unknown', inputStr, '', Date.now() - t0, { inp: 0, out: 0, total: 0 }, { type: e.name || 'Error', message: e.message });
+                throw e;
+            }
+        };
+        patched.__arkna = true;
+        Cls.prototype.create = patched;
+        if (_config.debug)
+            console.log('[arkna] Patched openai.chat.completions.create');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Anthropic patch ─────────────────────────────────────────
+function _patchAnthropic() {
+    try {
+        const mod = require('@anthropic-ai/sdk/resources/messages');
+        const Cls = mod.Messages;
+        if (!Cls?.prototype?.create || Cls.prototype.create.__arkna)
+            return false;
+        const orig = Cls.prototype.create;
+        const patched = async function (body, opts) {
+            const t0 = Date.now();
+            const msgs = body?.messages;
+            const inputStr = Array.isArray(msgs)
+                ? JSON.stringify(msgs.slice(-3))
+                : String(msgs ?? '');
+            try {
+                const res = await orig.call(this, body, opts);
+                if (!body?.stream && res?.content) {
+                    const out = res.content.map((c) => c.text ?? '').join('');
+                    const u = res.usage ?? {};
+                    const inp = u.input_tokens ?? 0;
+                    const outp = u.output_tokens ?? 0;
+                    _record('anthropic', body.model ?? 'unknown', inputStr, out, Date.now() - t0, {
+                        inp,
+                        out: outp,
+                        total: inp + outp,
+                    });
+                }
+                return res;
+            }
+            catch (e) {
+                _record('anthropic', body?.model ?? 'unknown', inputStr, '', Date.now() - t0, { inp: 0, out: 0, total: 0 }, { type: e.name || 'Error', message: e.message });
+                throw e;
+            }
+        };
+        patched.__arkna = true;
+        Cls.prototype.create = patched;
+        if (_config.debug)
+            console.log('[arkna] Patched anthropic.messages.create');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Initialize ARKNA auto-instrumentation.
+ *
+ * Monkey-patches OpenAI and Anthropic SDKs to automatically record all LLM
+ * calls as ARKNA observability runs. Each call creates a run with a reasoning
+ * step capturing model, tokens, cost, latency, and input/output.
+ *
+ * @example
+ * ```typescript
+ * import { init } from '@arkna/sdk';
+ *
+ * // With API key directly
+ * init('intk_...');
+ *
+ * // With env vars (ARKNA_TOKEN)
+ * init();
+ *
+ * // With options
+ * init({ apiKey: 'intk_...', debug: true });
+ * ```
+ */
+function init(apiKeyOrOptions) {
+    if (_initialized)
+        return;
+    const opts = typeof apiKeyOrOptions === 'string'
+        ? { apiKey: apiKeyOrOptions }
+        : (apiKeyOrOptions ?? {});
+    const apiKey = opts.apiKey || process.env.ARKNA_TOKEN || '';
+    const baseUrl = (opts.baseUrl || process.env.ARKNA_URL || 'https://api.arkna.com.au')
+        .replace(/\/+$/, '');
+    _config.debug = opts.debug ?? false;
+    if (!apiKey) {
+        if (_config.debug)
+            console.warn('[arkna] No API key. Set ARKNA_TOKEN or pass to init().');
+        return;
+    }
+    _config.apiKey = apiKey;
+    _config.ingestionUrl = baseUrl.endsWith('/api/v1') ? baseUrl : `${baseUrl}/api/v1`;
+    _initialized = true;
+    const patched = [];
+    if (_patchOpenAI())
+        patched.push('openai');
+    if (_patchAnthropic())
+        patched.push('anthropic');
+    if (_config.debug) {
+        console.log(`[arkna] Initialized. Patched: ${patched.length ? patched.join(', ') : 'none (install openai or @anthropic-ai/sdk)'}`);
+    }
+}
+/**
+ * Trace a function as a single ARKNA run.
+ *
+ * All LLM calls made inside the function are recorded as steps in a single
+ * run, rather than creating separate runs for each call.
+ *
+ * @example
+ * ```typescript
+ * import { init, trace } from '@arkna/sdk';
+ * init();
+ *
+ * const result = await trace('research-task', async () => {
+ *   const plan = await openai.chat.completions.create({ ... });
+ *   const result = await openai.chat.completions.create({ ... });
+ *   return result.choices[0].message.content;
+ * });
+ * ```
+ */
+async function trace(name, fn, options) {
+    if (!_initialized)
+        return fn();
+    const run = await _post('/runs', {
+        trigger_type: 'auto',
+        input: name,
+        session_id: options?.sessionId,
+        metadata: { ...options?.metadata, auto_instrumented: true },
+    });
+    if (!run?.run_id)
+        return fn();
+    const ctx = { runId: run.run_id, stepCount: 0 };
+    return _runCtx.run(ctx, async () => {
+        try {
+            const result = await fn();
+            const out = typeof result === 'string' ? result : JSON.stringify(result);
+            _patch(`/runs/${run.run_id}`, {
+                status: 'completed',
+                output: out?.substring(0, 5000),
+            }).catch(() => { });
+            return result;
+        }
+        catch (err) {
+            _patch(`/runs/${run.run_id}`, {
+                status: 'failed',
+                error_type: err.name || 'Error',
+                error_message: err.message,
+            }).catch(() => { });
+            throw err;
+        }
+    });
+}
+/**
+ * Shut down ARKNA instrumentation and clear internal state.
+ * Call before process exit if you want to ensure clean teardown.
+ */
+function shutdown() {
+    _initialized = false;
+    _config.apiKey = '';
+    _config.ingestionUrl = '';
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}

package/dist/instrumentations/langchain.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ARKNA LangChain Auto-Instrumentation
+ *
+ * Callback handler that automatically captures LangChain chain/agent
+ * executions as ARKNA observability runs — no manual SDK calls needed.
+ *
+ * Usage:
+ *   import { ArknaClient, ArknaLangChainHandler } from '@arkna/sdk';
+ *   const client = new ArknaClient();
+ *   const handler = new ArknaLangChainHandler(client);
+ *   const result = await chain.invoke(input, { callbacks: [handler] });
+ *
+ * Requires: langchain >= 0.2.0 (peer dependency, not bundled)
+ */
+import type { ArknaClient } from '../client';
+/** Options for the ARKNA LangChain handler */
+export interface ArknaLangChainHandlerOptions {
+    /** Session ID to group related runs */
+    sessionId?: string;
+    /** How the run was triggered (e.g. 'api', 'user', 'cron') */
+    trigger?: string;
+    /** Additional metadata attached to the run */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * LangChain callback handler that auto-captures runs into ARKNA observability.
+ *
+ * Event mapping:
+ *   chain start  → startRun() (top-level) or recordStep(reasoning) (nested)
+ *   LLM start    → recordStep(reasoning)
+ *   LLM end      → update step with output + token usage
+ *   tool start   → recordToolCall()
+ *   tool end     → (tool result captured)
+ *   retriever    → recordStep(retrieval)
+ *   chain end    → completeRun(completed)
+ *   chain error  → completeRun(failed)
+ *
+ * This class dynamically extends BaseCallbackHandler at runtime so that
+ * `@langchain/core` is only required at runtime (peer dependency).
+ */
+export declare class ArknaLangChainHandler {
+    private client;
+    private sessionId?;
+    private trigger;
+    private runMetadata;
+    private runs;
+    private parentToArknaRun;
+    private rootRunId;
+    private _handler;
+    constructor(client: ArknaClient, options?: ArknaLangChainHandlerOptions);
+    /**
+     * Get the LangChain-compatible callback handler instance.
+     * Lazily creates a BaseCallbackHandler subclass on first access.
+     * Pass this to LangChain's `callbacks` option.
+     */
+    get handler(): any;
+    /**
+     * Also allow using the ArknaLangChainHandler directly as a callback
+     * by implementing the key callback methods on the instance itself.
+     * LangChain checks for method existence, so this works as a duck-typed handler.
+     */
+    private createHandler;
+    private post;
+    private patch;
+    private handleChainStart;
+    private handleChainEnd;
+    private handleChainError;
+    private handleLLMStart;
+    private handleLLMEnd;
+    private handleLLMError;
+    private handleToolStart;
+    private handleToolError;
+    private handleRetrieverStart;
+    private handleRetrieverEnd;
+    private handleRetrieverError;
+    private getArknaRunId;
+    private cleanup;
+}
+//# sourceMappingURL=langchain.d.ts.map

package/dist/instrumentations/langchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.d.ts","sourceRoot":"","sources":["../../src/instrumentations/langchain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,8CAA8C;AAC9C,MAAM,WAAW,4BAA4B;IAC3C,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAQD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAA0B;IAG7C,OAAO,CAAC,IAAI,CAA+B;IAE3C,OAAO,CAAC,gBAAgB,CAA6B;IAErD,OAAO,CAAC,SAAS,CAAuB;IAGxC,OAAO,CAAC,QAAQ,CAAa;gBAEjB,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,4BAA4B;IAOvE;;;;OAIG;IACH,IAAI,OAAO,IAAI,GAAG,CAKjB;IAED;;;;OAIG;IACH,OAAO,CAAC,aAAa;YAuDP,IAAI;YAIJ,KAAK;YAQL,gBAAgB;YA6ChB,cAAc;YAkBd,gBAAgB;YAyBhB,cAAc;YA8Bd,YAAY;YA8BZ,cAAc;YAsBd,eAAe;YA+Cf,eAAe;YAsBf,oBAAoB;YA6BpB,kBAAkB;YAwBlB,oBAAoB;IAsBlC,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,OAAO;CAKhB"}