@conquext/core 0.1.0

package/dist/index.js

@@ -0,0 +1,657 @@
+// src/schemas.ts
+import { z } from "zod";
+var UserContextSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().optional(),
+  email: z.string().email().optional(),
+  team: z.string().optional(),
+  plan: z.string().optional()
+});
+var TaskContextSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().optional(),
+  type: z.string().optional(),
+  priority: z.enum(["low", "medium", "high", "critical"]).optional()
+});
+var SessionContextSchema = z.object({
+  id: z.string().min(1),
+  conversationId: z.string().optional(),
+  parentCallId: z.string().optional()
+});
+var ObservabilityContextSchema = z.object({
+  user: UserContextSchema.optional(),
+  task: TaskContextSchema.optional(),
+  session: SessionContextSchema.optional(),
+  labels: z.record(z.string(), z.string()).optional()
+});
+var UsageEventInputSchema = z.object({
+  model: z.string().min(1),
+  provider: z.string().min(1),
+  requested_model: z.string().optional(),
+  input_tokens: z.number().int().nonnegative(),
+  output_tokens: z.number().int().nonnegative(),
+  total_tokens: z.number().int().nonnegative().optional(),
+  cost: z.number().nonnegative().optional(),
+  latency_ms: z.number().nonnegative(),
+  status: z.enum(["success", "error"]),
+  error: z.string().optional(),
+  streaming: z.boolean().optional(),
+  time_to_first_token_ms: z.number().nonnegative().optional(),
+  cache_read_tokens: z.number().int().nonnegative().optional(),
+  cache_write_tokens: z.number().int().nonnegative().optional(),
+  context: ObservabilityContextSchema.optional()
+});
+
+// src/errors.ts
+var BudgetExhaustedError = class extends Error {
+  scope;
+  scopeId;
+  spent;
+  limit;
+  window;
+  resetAt;
+  constructor(params) {
+    super(
+      `Budget exhausted for ${params.scope} "${params.scopeId}": $${params.spent.toFixed(2)} spent of $${params.limit.toFixed(2)} ${params.window} limit`
+    );
+    this.name = "BudgetExhaustedError";
+    this.scope = params.scope;
+    this.scopeId = params.scopeId;
+    this.spent = params.spent;
+    this.limit = params.limit;
+    this.window = params.window;
+    this.resetAt = params.resetAt;
+  }
+};
+
+// src/pricing-table.json
+var pricing_table_default = {
+  updatedAt: "2025-06-01",
+  models: {
+    "gpt-4o": { provider: "openai", input_per_million: 2.5, output_per_million: 10 },
+    "gpt-4o-mini": { provider: "openai", input_per_million: 0.15, output_per_million: 0.6 },
+    "gpt-4-turbo": { provider: "openai", input_per_million: 10, output_per_million: 30 },
+    "gpt-3.5-turbo": { provider: "openai", input_per_million: 0.5, output_per_million: 1.5 },
+    o1: { provider: "openai", input_per_million: 15, output_per_million: 60 },
+    "o1-mini": { provider: "openai", input_per_million: 3, output_per_million: 12 },
+    "o3-mini": { provider: "openai", input_per_million: 1.1, output_per_million: 4.4 },
+    "claude-opus-4-20250514": { provider: "anthropic", input_per_million: 15, output_per_million: 75, cache_read_per_million: 1.5, cache_write_per_million: 18.75 },
+    "claude-sonnet-4-20250514": { provider: "anthropic", input_per_million: 3, output_per_million: 15, cache_read_per_million: 0.3, cache_write_per_million: 3.75 },
+    "claude-haiku-3-5": { provider: "anthropic", input_per_million: 0.8, output_per_million: 4, cache_read_per_million: 0.08, cache_write_per_million: 1 },
+    "gemini-2.0-flash": { provider: "google", input_per_million: 0.1, output_per_million: 0.4 },
+    "gemini-1.5-pro": { provider: "google", input_per_million: 1.25, output_per_million: 5 },
+    "gemini-1.5-flash": { provider: "google", input_per_million: 0.075, output_per_million: 0.3 }
+  }
+};
+
+// src/pricing.ts
+var PricingEngine = class _PricingEngine {
+  table;
+  sortedModelKeys;
+  constructor(config) {
+    this.table = _PricingEngine.resolve(config);
+    this.sortedModelKeys = Object.keys(this.table.models).sort((a, b) => b.length - a.length);
+  }
+  static resolve(config) {
+    if (config === "builtin") {
+      return pricing_table_default;
+    }
+    if ("updatedAt" in config && "models" in config) {
+      return config;
+    }
+    const base = pricing_table_default;
+    return {
+      updatedAt: base.updatedAt,
+      models: { ...base.models, ...config.overrides }
+    };
+  }
+  calculateCost(event) {
+    const pricing = this.findModel(event.model);
+    if (!pricing) return 0;
+    let cost = 0;
+    const standardInput = event.input_tokens - (event.cache_read_tokens ?? 0);
+    cost += standardInput / 1e6 * pricing.input_per_million;
+    if (event.cache_read_tokens && pricing.cache_read_per_million) {
+      cost += event.cache_read_tokens / 1e6 * pricing.cache_read_per_million;
+    }
+    if (event.cache_write_tokens && pricing.cache_write_per_million) {
+      cost += event.cache_write_tokens / 1e6 * pricing.cache_write_per_million;
+    }
+    cost += event.output_tokens / 1e6 * pricing.output_per_million;
+    return cost;
+  }
+  isPricingMiss(model) {
+    return this.findModel(model) === void 0;
+  }
+  findModel(model) {
+    if (this.table.models[model]) {
+      return this.table.models[model];
+    }
+    for (const key of this.sortedModelKeys) {
+      if (model.startsWith(key)) {
+        return this.table.models[key];
+      }
+    }
+    return void 0;
+  }
+};
+
+// src/memory-backend.ts
+var MemoryBackend = class {
+  events = [];
+  async write(events) {
+    this.events.push(...events);
+  }
+  async query(query) {
+    return this.events.filter((event) => {
+      if (event.timestamp < query.from || event.timestamp > query.to) return false;
+      if (query.user && event.context?.user?.id !== query.user) return false;
+      if (query.task && event.context?.task?.id !== query.task) return false;
+      if (query.session && event.context?.session?.id !== query.session) return false;
+      if (query.model && event.model !== query.model) return false;
+      if (query.provider && event.provider !== query.provider) return false;
+      if (query.labels) {
+        const eventLabels = event.context?.labels ?? {};
+        for (const [key, value] of Object.entries(query.labels)) {
+          if (eventLabels[key] !== value) return false;
+        }
+      }
+      return true;
+    });
+  }
+  async close() {
+    this.events = [];
+  }
+  getAll() {
+    return [...this.events];
+  }
+  get size() {
+    return this.events.length;
+  }
+};
+
+// src/batch.ts
+var DEFAULT_BATCH_CONFIG = {
+  maxSize: 100,
+  flushInterval: 5e3
+};
+var BatchProcessor = class {
+  buffer = [];
+  timer = null;
+  backend;
+  config;
+  closed = false;
+  constructor(backend, config) {
+    this.backend = backend;
+    this.config = { ...DEFAULT_BATCH_CONFIG, ...config };
+    this.startTimer();
+  }
+  async add(event) {
+    if (this.closed) return;
+    this.buffer.push(event);
+    if (this.buffer.length >= this.config.maxSize) {
+      await this.flush();
+    }
+  }
+  async flush() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer;
+    this.buffer = [];
+    await this.backend.write(batch);
+  }
+  async close() {
+    this.closed = true;
+    this.stopTimer();
+    await this.flush();
+    await this.backend.close();
+  }
+  get pending() {
+    return this.buffer.length;
+  }
+  startTimer() {
+    if (this.config.flushInterval > 0) {
+      this.timer = setInterval(() => {
+        this.flush().catch(() => {
+        });
+      }, this.config.flushInterval);
+      if (this.timer && typeof this.timer === "object" && "unref" in this.timer) {
+        this.timer.unref();
+      }
+    }
+  }
+  stopTimer() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+};
+
+// src/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var storage = new AsyncLocalStorage();
+var ContextManager = {
+  get() {
+    return storage.getStore();
+  },
+  run(context, fn) {
+    return storage.run(context, fn);
+  },
+  merge(base, override) {
+    if (!base && !override) return {};
+    if (!base) return override;
+    if (!override) return base;
+    return {
+      user: override.user ?? base.user,
+      task: override.task ?? base.task,
+      session: override.session ?? base.session,
+      labels: { ...base.labels, ...override.labels }
+    };
+  }
+};
+
+// src/adapter.ts
+function defineAdapter(config) {
+  return {
+    name: config.name,
+    instrumentedMethods: config.instrumentedMethods,
+    extractUsage: config.extractUsage,
+    extractStreamUsage: config.extractStreamUsage ?? defaultStreamExtractor
+  };
+}
+function defaultStreamExtractor(_stream) {
+  throw new Error("Streaming not supported by this adapter. Implement extractStreamUsage.");
+}
+function createTrackedStream(source, onComplete) {
+  const chunks = [];
+  let usage;
+  let done = false;
+  const iterator = {
+    [Symbol.asyncIterator]() {
+      const sourceIterator = source[Symbol.asyncIterator]();
+      return {
+        async next() {
+          const result = await sourceIterator.next();
+          if (result.done) {
+            done = true;
+            usage = onComplete(chunks);
+            return result;
+          }
+          chunks.push(result.value);
+          return result;
+        }
+      };
+    }
+  };
+  return Object.assign(iterator, {
+    getUsage() {
+      if (done && usage) return Promise.resolve(usage);
+      return new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+          clearInterval(check);
+          reject(new Error("Stream usage not available \u2014 stream may not have been fully consumed"));
+        }, 3e4);
+        const check = setInterval(() => {
+          if (done && usage) {
+            clearInterval(check);
+            clearTimeout(timeoutId);
+            resolve(usage);
+          }
+        }, 10);
+      });
+    }
+  });
+}
+
+// src/callbacks.ts
+var CallbackDispatcher = class {
+  config;
+  errorCounts = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.config = config;
+  }
+  dispatch(event) {
+    try {
+      this.config.event?.(event);
+    } catch {
+    }
+    if (this.config.costThreshold && event.cost >= this.config.costThreshold.threshold) {
+      try {
+        this.config.costThreshold.handler(event);
+      } catch {
+      }
+    }
+    if (this.config.errorSpike) {
+      this.checkErrorSpike(event);
+    }
+  }
+  checkErrorSpike(event) {
+    const cfg = this.config.errorSpike;
+    const windowMs = parseWindow(cfg.window);
+    const now = Date.now();
+    const key = event.model;
+    let entry = this.errorCounts.get(key);
+    if (!entry || now - entry.windowStart > windowMs) {
+      entry = { errors: 0, total: 0, windowStart: now };
+      this.errorCounts.set(key, entry);
+    }
+    entry.total++;
+    if (event.status === "error") entry.errors++;
+    if (entry.total >= 5) {
+      const rate = entry.errors / entry.total;
+      if (rate >= cfg.threshold) {
+        try {
+          cfg.handler(event.model, rate);
+        } catch {
+        }
+      }
+    }
+  }
+};
+function parseWindow(window) {
+  const match = window.match(/^(\d+)(s|m|h)$/);
+  if (!match) return 5 * 60 * 1e3;
+  const [, num, unit] = match;
+  const multipliers = { s: 1e3, m: 6e4, h: 36e5 };
+  return Number(num) * multipliers[unit];
+}
+
+// src/budget.ts
+var WINDOW_DURATIONS = {
+  hourly: 36e5,
+  daily: 864e5,
+  monthly: 2592e6
+  // 30 days
+};
+var BudgetEngine = class {
+  config;
+  accumulators = {
+    user: createAccumulator(),
+    team: createAccumulator(),
+    task: createAccumulator()
+  };
+  constructor(config) {
+    this.config = config;
+  }
+  check(context, model, estimatedCost) {
+    if (!context) return { exceeded: false };
+    if (this.config.perUser && context.user?.id) {
+      const result = this.checkScope("user", context.user.id, this.config.perUser, model, estimatedCost);
+      if (result) return result;
+    }
+    if (this.config.perTeam && context.user?.team) {
+      const result = this.checkScope("team", context.user.team, this.config.perTeam, model, estimatedCost);
+      if (result) return result;
+    }
+    if (this.config.perTask && context.task?.id) {
+      const result = this.checkScope("task", context.task.id, this.config.perTask, model, estimatedCost);
+      if (result) return result;
+    }
+    return { exceeded: false };
+  }
+  accumulate(event) {
+    const now = Date.now();
+    if (event.context?.user?.id) {
+      addToAccumulator(this.accumulators.user, event.context.user.id, event.cost, now);
+    }
+    if (event.context?.user?.team) {
+      addToAccumulator(this.accumulators.team, event.context.user.team, event.cost, now);
+    }
+    if (event.context?.task?.id) {
+      addToAccumulator(this.accumulators.task, event.context.task.id, event.cost, now);
+    }
+  }
+  checkScope(scope, scopeId, limits, model, estimatedCost) {
+    const acc = this.accumulators[scope];
+    const now = Date.now();
+    for (const [window, limit] of Object.entries(limits)) {
+      if (limit === void 0) continue;
+      const spent = getSpent(acc, scopeId, window, now);
+      const projected = spent + estimatedCost;
+      if (projected > limit) {
+        return this.handleExceeded(scope, scopeId, spent, limit, window, model);
+      }
+      if (this.config.enforcement === "downgrade") {
+        const threshold = this.config.downgradeThreshold ?? 0.8;
+        if (spent / limit >= threshold) {
+          const downgradeModel = this.config.downgrades?.[model];
+          if (downgradeModel) {
+            return { exceeded: false, downgrade: downgradeModel };
+          }
+        }
+      }
+    }
+    return void 0;
+  }
+  handleExceeded(scope, scopeId, spent, limit, window, model) {
+    if (this.config.enforcement === "hard") {
+      throw new BudgetExhaustedError({ scope, scopeId, spent, limit, window });
+    }
+    if (this.config.enforcement === "downgrade") {
+      const downgradeModel = this.config.downgrades?.[model];
+      if (downgradeModel) {
+        return { exceeded: true, scope, scopeId, spent, limit, window, downgrade: downgradeModel };
+      }
+      throw new BudgetExhaustedError({ scope, scopeId, spent, limit, window });
+    }
+    return { exceeded: true, scope, scopeId, spent, limit, window };
+  }
+};
+function createAccumulator() {
+  return {
+    hourly: /* @__PURE__ */ new Map(),
+    daily: /* @__PURE__ */ new Map(),
+    monthly: /* @__PURE__ */ new Map(),
+    total: /* @__PURE__ */ new Map()
+  };
+}
+function addToAccumulator(acc, key, cost, now) {
+  for (const window of ["hourly", "daily", "monthly"]) {
+    const map = acc[window];
+    const entry = map.get(key);
+    const duration = WINDOW_DURATIONS[window];
+    if (!entry || now - entry.windowStart > duration) {
+      map.set(key, { amount: cost, windowStart: now });
+    } else {
+      entry.amount += cost;
+    }
+  }
+  acc.total.set(key, (acc.total.get(key) ?? 0) + cost);
+}
+function getSpent(acc, key, window, now) {
+  if (window === "total") {
+    return acc.total.get(key) ?? 0;
+  }
+  const entry = acc[window].get(key);
+  if (!entry) return 0;
+  const duration = WINDOW_DURATIONS[window];
+  if (now - entry.windowStart > duration) return 0;
+  return entry.amount;
+}
+
+// src/observatory.ts
+import { ulid } from "ulid";
+var Observatory = class {
+  backend;
+  pricing;
+  batch;
+  defaultContext;
+  disabled;
+  callbacks;
+  budgetEngine;
+  constructor(config) {
+    this.disabled = config.disabled ?? false;
+    this.backend = config.backend;
+    this.pricing = new PricingEngine(config.pricing ?? "builtin");
+    this.batch = new BatchProcessor(config.backend, config.batching);
+    this.defaultContext = config.defaultContext;
+    this.callbacks = config.on ? new CallbackDispatcher(config.on) : void 0;
+    this.budgetEngine = config.budgets ? new BudgetEngine(config.budgets) : void 0;
+  }
+  async record(input) {
+    if (this.disabled) return;
+    const validated = UsageEventInputSchema.parse(input);
+    const pricingMiss = this.pricing.isPricingMiss(validated.model);
+    const cost = validated.cost ?? (pricingMiss ? 0 : this.pricing.calculateCost(validated));
+    const resolvedContext = ContextManager.merge(this.defaultContext, validated.context);
+    const event = {
+      ...validated,
+      id: ulid(),
+      timestamp: /* @__PURE__ */ new Date(),
+      total_tokens: validated.total_tokens ?? validated.input_tokens + validated.output_tokens,
+      cost,
+      pricing_miss: pricingMiss || void 0,
+      context: Object.keys(resolvedContext).length > 0 ? resolvedContext : void 0
+    };
+    await this.batch.add(event);
+    this.budgetEngine?.accumulate(event);
+    this.callbacks?.dispatch(event);
+  }
+  async track(fn, opts) {
+    if (this.disabled) return fn();
+    const start = performance.now();
+    let result;
+    try {
+      result = await fn();
+    } catch (err) {
+      const latency_ms2 = performance.now() - start;
+      await this.record({
+        model: "unknown",
+        provider: opts.provider.name,
+        input_tokens: 0,
+        output_tokens: 0,
+        latency_ms: latency_ms2,
+        status: "error",
+        error: err instanceof Error ? err.message : String(err),
+        context: opts.context
+      });
+      throw err;
+    }
+    const latency_ms = performance.now() - start;
+    const usage = opts.provider.extractUsage(result);
+    const mergedContext = ContextManager.merge(ContextManager.get(), opts.context);
+    await this.record({
+      model: usage.model,
+      provider: opts.provider.name,
+      input_tokens: usage.input_tokens,
+      output_tokens: usage.output_tokens,
+      cache_read_tokens: usage.cache_read_tokens,
+      cache_write_tokens: usage.cache_write_tokens,
+      latency_ms,
+      status: "success",
+      context: mergedContext
+    });
+    return result;
+  }
+  instrument(client, adapter) {
+    if (this.disabled) return client;
+    const obs = this;
+    const handler = {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof prop === "string" && adapter.instrumentedMethods.includes(prop) && typeof value === "function") {
+          return (...args) => {
+            return obs.track(
+              () => value.apply(target, args),
+              { provider: adapter, context: ContextManager.get() }
+            );
+          };
+        }
+        if (typeof prop === "string" && typeof value === "object" && value !== null) {
+          const hasMatchingMethod = adapter.instrumentedMethods.some(
+            (m) => m === prop || m.startsWith(`${prop}.`)
+          );
+          if (hasMatchingMethod) {
+            return new Proxy(value, makeNestedHandler(obs, adapter, prop));
+          }
+        }
+        return value;
+      }
+    };
+    return new Proxy(client, handler);
+  }
+  async withContext(ctx, fn) {
+    if (this.disabled) return fn();
+    return ContextManager.run(ctx, fn);
+  }
+  middleware(opts) {
+    const obs = this;
+    return (req, _res, next) => {
+      const ctx = opts.extractContext(req);
+      return ContextManager.run(ctx, next);
+    };
+  }
+  async flush() {
+    await this.batch.flush();
+  }
+  async close() {
+    await this.batch.close();
+  }
+};
+function makeNestedHandler(obs, adapter, parentPath) {
+  return {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      const fullPath = `${parentPath}.${String(prop)}`;
+      if (typeof prop === "string" && adapter.instrumentedMethods.includes(fullPath) && typeof value === "function") {
+        return (...args) => {
+          return obs.track(
+            () => value.apply(target, args),
+            { provider: adapter, context: ContextManager.get() }
+          );
+        };
+      }
+      if (typeof prop === "string" && typeof value === "object" && value !== null) {
+        const hasMatchingMethod = adapter.instrumentedMethods.some(
+          (m) => m === fullPath || m.startsWith(`${fullPath}.`)
+        );
+        if (hasMatchingMethod) {
+          return new Proxy(value, makeNestedHandler(obs, adapter, fullPath));
+        }
+      }
+      return value;
+    }
+  };
+}
+
+// src/noop.ts
+var NoopObservatory = class {
+  async record() {
+  }
+  async track(fn) {
+    return fn();
+  }
+  instrument(client) {
+    return client;
+  }
+  async withContext(_ctx, fn) {
+    return fn();
+  }
+  middleware() {
+    return (_req, _res, next) => next();
+  }
+  async flush() {
+  }
+  async close() {
+  }
+};
+export {
+  BatchProcessor,
+  BudgetEngine,
+  BudgetExhaustedError,
+  CallbackDispatcher,
+  ContextManager,
+  DEFAULT_BATCH_CONFIG,
+  MemoryBackend,
+  NoopObservatory,
+  ObservabilityContextSchema,
+  Observatory,
+  PricingEngine,
+  SessionContextSchema,
+  TaskContextSchema,
+  UsageEventInputSchema,
+  UserContextSchema,
+  createTrackedStream,
+  defineAdapter
+};
+//# sourceMappingURL=index.js.map