@happyvertical/smrt-core 0.30.0

package/dist/class.js

@@ -0,0 +1,896 @@
+import { getAI } from "@happyvertical/ai";
+import { FilesystemAdapter } from "@happyvertical/files";
+import { createLogger } from "@happyvertical/logger";
+import { getDatabase } from "@happyvertical/sql";
+import { AiUsageCollector, AiUsagePersistenceHandler } from "./adapters/ai-usage.js";
+import { estimateAiUsageCost } from "./adapters/cost-rates.js";
+import { config } from "./config.js";
+import { detectEngine } from "./schema/ddl/index.js";
+import { SignalBus } from "./signals/bus.js";
+import { tableExists, ensureLegacySystemTableCompatibility } from "./system/compatibility.js";
+import { SMRT_SCHEMA_VERSION, ALL_SYSTEM_TABLES } from "./system/schema.js";
+const SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL = "SELECT pg_advisory_xact_lock(hashtext('smrt'), hashtext('system-tables'))";
+const logger = createLogger({ level: "info" });
+function firstString(...candidates) {
+  return candidates.find((candidate) => {
+    return typeof candidate === "string";
+  });
+}
+function firstNumber(...candidates) {
+  return candidates.find((candidate) => {
+    return typeof candidate === "number";
+  });
+}
+function getDatabaseUrl(db) {
+  const dbWithConfig = db;
+  return db.url || dbWithConfig.config?.url || "";
+}
+function getDatabaseTypeHint(config2) {
+  if (!config2 || typeof config2 === "string") {
+    return void 0;
+  }
+  const configWithType = config2;
+  if (typeof configWithType.type === "string") {
+    return configWithType.type;
+  }
+  if (typeof configWithType.config?.type === "string") {
+    return configWithType.config.type;
+  }
+  if ("query" in configWithType && typeof configWithType.query === "function") {
+    return void 0;
+  }
+  if ("client" in configWithType && configWithType.client) {
+    return "postgres";
+  }
+  return void 0;
+}
+function normalizeIncomingAiUsageTokens(value) {
+  if (!value || typeof value !== "object") {
+    return void 0;
+  }
+  const usage = value;
+  const promptTokens = typeof usage.promptTokens === "number" ? usage.promptTokens : typeof usage.inputTokens === "number" ? usage.inputTokens : void 0;
+  const completionTokens = typeof usage.completionTokens === "number" ? usage.completionTokens : typeof usage.outputTokens === "number" ? usage.outputTokens : void 0;
+  const totalTokens = typeof usage.totalTokens === "number" ? usage.totalTokens : promptTokens !== void 0 || completionTokens !== void 0 ? (promptTokens ?? 0) + (completionTokens ?? 0) : void 0;
+  if (promptTokens === void 0 && completionTokens === void 0 && totalTokens === void 0) {
+    return void 0;
+  }
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens
+  };
+}
+function hydratePersistedAiUsageTokens(row) {
+  const promptTokens = typeof row.prompt_tokens === "number" ? row.prompt_tokens : row.prompt_tokens === null || row.prompt_tokens === void 0 ? void 0 : Number(row.prompt_tokens);
+  const completionTokens = typeof row.completion_tokens === "number" ? row.completion_tokens : row.completion_tokens === null || row.completion_tokens === void 0 ? void 0 : Number(row.completion_tokens);
+  const totalTokens = typeof row.total_tokens === "number" ? row.total_tokens : row.total_tokens === null || row.total_tokens === void 0 ? void 0 : Number(row.total_tokens);
+  if (promptTokens === void 0 && completionTokens === void 0 && totalTokens === void 0) {
+    return void 0;
+  }
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens
+  };
+}
+function normalizeAiUsageTags(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  const tags = {};
+  for (const [key, tagValue] of Object.entries(value)) {
+    if (tagValue === void 0 || tagValue === null) continue;
+    tags[key] = String(tagValue);
+  }
+  return Object.keys(tags).length > 0 ? tags : void 0;
+}
+function parseAiUsageTags(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  try {
+    return normalizeAiUsageTags(JSON.parse(value));
+  } catch {
+    return void 0;
+  }
+}
+function normalizeAiUsageTimestamp(value) {
+  if (value instanceof Date) {
+    return value;
+  }
+  if (typeof value === "string" || typeof value === "number") {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) {
+      return date;
+    }
+  }
+  return /* @__PURE__ */ new Date();
+}
+function getQueryRows(result) {
+  return Array.isArray(result) ? result : result.rows ?? [];
+}
+function buildAiUsageWhereClause(options) {
+  const conditions = [];
+  const params = [];
+  let nextParamIndex = 1;
+  if (options.since) {
+    conditions.push(`created_at >= $${nextParamIndex++}`);
+    params.push(options.since.toISOString());
+  }
+  if (options.until) {
+    conditions.push(`created_at <= $${nextParamIndex++}`);
+    params.push(options.until.toISOString());
+  }
+  if (options.provider) {
+    conditions.push(`provider = $${nextParamIndex++}`);
+    params.push(options.provider);
+  }
+  if (options.model) {
+    conditions.push(`model = $${nextParamIndex++}`);
+    params.push(options.model);
+  }
+  if (options.operation) {
+    conditions.push(`operation = $${nextParamIndex++}`);
+    params.push(options.operation);
+  }
+  if (options.className) {
+    conditions.push(`class_name = $${nextParamIndex++}`);
+    params.push(options.className);
+  }
+  if (options.tenantId === null) {
+    conditions.push(`tenant_id IS NULL`);
+  } else if (options.tenantId) {
+    conditions.push(`tenant_id = $${nextParamIndex++}`);
+    params.push(options.tenantId);
+  }
+  return {
+    conditions,
+    params,
+    nextParamIndex
+  };
+}
+class SmrtClass {
+  /**
+   * AI client instance for interacting with AI models
+   */
+  _ai;
+  /**
+   * Filesystem adapter for file operations
+   */
+  _fs;
+  /**
+   * Database interface for data persistence
+   */
+  _db;
+  _dbEngineHint;
+  /**
+   * Class name used for identification
+   */
+  _className;
+  /**
+   * Signal bus for method execution tracking
+   */
+  _signalBus;
+  /**
+   * Adapters registered by this instance (for cleanup)
+   */
+  _registeredAdapters = [];
+  /**
+   * In-memory AI usage collector for quick inspection.
+   */
+  _aiUsageCollector;
+  /**
+   * Registered AI usage handlers for this instance.
+   */
+  _aiUsageHandlers = [];
+  /**
+   * Tracks whether optional runtime services (signals, AI, fs) are ready.
+   */
+  _runtimeServicesInitialized = false;
+  /**
+   * Shared in-flight runtime initialization promise for single-flight setup.
+   */
+  _runtimeServicesInitPromise;
+  /**
+   * Configuration options provided to the class
+   */
+  options;
+  /**
+   * Track which databases have had system tables initialized
+   * - WeakSet for :memory: databases (URL not unique, track by instance)
+   * - Set<string> for all others (URL is unique identifier)
+   */
+  static _systemTablesInitialized = /* @__PURE__ */ new WeakSet();
+  static _systemTablesInitializedByUrl = /* @__PURE__ */ new Set();
+  /**
+   * Creates a new SmrtClass instance
+   *
+   * @param options - Configuration options for database, filesystem, and AI clients
+   */
+  constructor(options = {}) {
+    this.options = options;
+    this._className = this.constructor.name;
+  }
+  /**
+   * Determines whether this class requires a database to function
+   *
+   * Override this method in subclasses that require database access
+   * to enable early validation during initialization.
+   *
+   * @returns True if database is required, false otherwise
+   * @example
+   * ```typescript
+   * class MyDataModel extends SmrtClass {
+   *   protected requiresDatabase(): boolean {
+   *     return true; // This class needs database access
+   *   }
+   * }
+   * ```
+   */
+  requiresDatabase() {
+    return false;
+  }
+  /**
+   * Initializes database, filesystem, and AI client connections
+   *
+   * This method sets up all required services based on the provided options.
+   * It should be called before using any of the service interfaces.
+   *
+   * @returns Promise that resolves to this instance for chaining
+   * @throws {Error} If database is required but not provided in options
+   */
+  async initialize() {
+    await this.initializeCoreResources();
+    if (!this.options._deferRuntimeInitialization) {
+      await this.initializeRuntimeServices();
+    }
+    return this;
+  }
+  /**
+   * Initialize core resources required for ORM behavior.
+   *
+   * This setup is shared by both full runtime initialization and lightweight
+   * query hydration. Hydrated objects reuse an existing DB connection and skip
+   * repeated system-table checks.
+   */
+  async initializeCoreResources() {
+    if (this.options.persistence && !this.options.db) {
+      this.options.db = this.options.persistence;
+    }
+    if (this.requiresDatabase() && !this.options.db) {
+      throw new Error(
+        `${this._className} requires a database configuration. Please provide 'db' in options: { db: { url: '...' } } or { db: 'database.db' }`
+      );
+    }
+    if (this.options.db) {
+      this._dbEngineHint = getDatabaseTypeHint(this.options.db);
+      if (this.options._reuseInitializedDb && typeof this.options.db === "object" && "query" in this.options.db) {
+        this._db = this.options.db;
+        this.options.db = this._db;
+      } else {
+        if (typeof this.options.db === "string") {
+          const isMemoryDb = this.options.db === ":memory:";
+          this._db = await getDatabase({
+            url: this.options.db,
+            ...isMemoryDb ? {} : { dbid: `smrt:${this.options.db}` }
+          });
+        } else if ("query" in this.options.db) {
+          this._db = this.options.db;
+        } else if ("client" in this.options.db && this.options.db.client) {
+          const dbConfig = this.options.db;
+          this._db = await getDatabase({
+            type: dbConfig.type || "postgres",
+            client: dbConfig.client,
+            url: dbConfig.url
+          });
+        } else {
+          const dbConfig = this.options.db;
+          const dbUrl = dbConfig.url || "memory";
+          const isMemoryDb = dbUrl === ":memory:" || dbUrl === "memory";
+          this._db = await getDatabase({
+            ...this.options.db,
+            ...isMemoryDb ? {} : { dbid: `smrt:${dbUrl}` }
+          });
+        }
+        this.options.db = this._db;
+        await this.ensureSystemTables();
+      }
+    }
+  }
+  /**
+   * Initialize optional runtime services that are not required for plain ORM reads.
+   */
+  async initializeRuntimeServices() {
+    if (this._runtimeServicesInitialized) {
+      return;
+    }
+    if (!this._runtimeServicesInitPromise) {
+      this._runtimeServicesInitPromise = (async () => {
+        if (this.options.fs && !this._fs) {
+          this._fs = await FilesystemAdapter.create(this.options.fs);
+        }
+        const globalConfig = config.toJSON();
+        const usageConfig = this.mergeAiUsageConfig(globalConfig);
+        this.initializeAiUsageHandlers(usageConfig);
+        if (!this._ai && (this.options.ai || globalConfig.ai || process.env.SMRT_AI_PROVIDER)) {
+          const aiOption = this.options.ai;
+          if (aiOption && typeof aiOption === "object" && typeof aiOption.embed === "function" && !aiOption.provider) {
+            this._ai = aiOption;
+          } else {
+            const { loadEnvConfig } = await import("@happyvertical/utils");
+            const baseConfig = globalConfig.ai || {};
+            const userConfig = { ...baseConfig, ...this.options.ai };
+            const aiConfig = loadEnvConfig(userConfig, {
+              packageName: "ai",
+              prefix: "SMRT",
+              schema: {
+                provider: "string",
+                model: "string",
+                apiKey: "string",
+                timeout: "number",
+                maxRetries: "number",
+                temperature: "number",
+                maxTokens: "number"
+              }
+            });
+            const existingOnUsage = aiConfig.onUsage ?? userConfig.onUsage ?? void 0;
+            aiConfig.onUsage = async (event) => {
+              if (typeof existingOnUsage === "function") {
+                await existingOnUsage(
+                  event
+                );
+              }
+              await this.handleAiUsageCallback(event, aiConfig, usageConfig);
+            };
+            if (aiConfig.provider || aiConfig.type || aiConfig.apiKey) {
+              this._ai = await getAI(aiConfig);
+            }
+          }
+        }
+        await this.initializeSignals();
+        this._runtimeServicesInitialized = true;
+      })();
+    }
+    try {
+      await this._runtimeServicesInitPromise;
+    } finally {
+      this._runtimeServicesInitPromise = void 0;
+    }
+  }
+  /**
+   * Ensure deferred runtime services are ready before using them.
+   */
+  async ensureRuntimeServicesInitialized() {
+    if (!this._runtimeServicesInitialized) {
+      await this.initializeRuntimeServices();
+    }
+  }
+  /**
+   * Resolve the AI client, initializing deferred runtime services on demand.
+   */
+  async getAiClient() {
+    await this.ensureRuntimeServicesInitialized();
+    if (!this._ai) {
+      throw new Error(
+        `${this._className} does not have an AI client configured. Provide 'ai' in options or configure a global SMRT AI provider.`
+      );
+    }
+    return this._ai;
+  }
+  /**
+   * Resolve the AI client if one is configured, otherwise return undefined.
+   */
+  async getOptionalAiClient() {
+    await this.ensureRuntimeServicesInitialized();
+    return this._ai;
+  }
+  async isSystemSchemaVersionApplied(db, version) {
+    const engine = detectEngine(getDatabaseUrl(db), this._dbEngineHint);
+    if (engine === "postgres" && !await tableExists(db, "_smrt_migrations", this._dbEngineHint)) {
+      return false;
+    }
+    try {
+      const versionParam = engine === "postgres" ? "$1" : "?";
+      const rows = await db.query(
+        `SELECT 1 FROM _smrt_migrations WHERE version = ${versionParam} LIMIT 1`,
+        version
+      );
+      return getQueryRows(rows).length > 0;
+    } catch (error) {
+      if (engine === "postgres") {
+        throw error;
+      }
+      return false;
+    }
+  }
+  /**
+   * Ensure SMRT system tables exist in the database
+   *
+   * System tables use _smrt_ prefix and store framework metadata:
+   * - _smrt_contexts: Context memory storage for remembered patterns
+   * - _smrt_migrations: Schema version tracking
+   * - _smrt_registry: Object registry persistence
+   * - _smrt_signals: Signal history/audit log
+   *
+   * This method is idempotent and safe to call multiple times.
+   * Tables are only created once per database connection.
+   */
+  async ensureSystemTables() {
+    if (!this._db) return;
+    const dbUrl = getDatabaseUrl(this._db);
+    const dbConstructorName = this._db.constructor?.name || "";
+    const isMemoryDb = dbUrl === ":memory:";
+    const isJsonDb = dbConstructorName.toLowerCase().includes("json");
+    const hasUndefinedUrl = !dbUrl;
+    const useInstanceTracking = isMemoryDb || isJsonDb || hasUndefinedUrl;
+    if (useInstanceTracking) {
+      if (SmrtClass._systemTablesInitialized.has(this._db)) {
+        return;
+      }
+    } else {
+      if (SmrtClass._systemTablesInitializedByUrl.has(dbUrl)) {
+        return;
+      }
+    }
+    try {
+      await this.withSystemTableBootstrapLock(
+        (db) => this.bootstrapSystemTables(db)
+      );
+      await this.ensureNativeVectorStorage();
+      if (useInstanceTracking) {
+        SmrtClass._systemTablesInitialized.add(this._db);
+      } else {
+        SmrtClass._systemTablesInitializedByUrl.add(dbUrl);
+      }
+    } catch (error) {
+      const dbInfo = this._db.constructor?.name || "unknown database";
+      throw new Error(
+        `Failed to create system tables for ${dbInfo}: ${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  async withSystemTableBootstrapLock(callback) {
+    if (!this._db) {
+      throw new Error("Database is not initialized");
+    }
+    const beginTransaction = this._db.beginTransaction;
+    const transaction = this._db.transaction;
+    const shouldUsePostgresLock = detectEngine(getDatabaseUrl(this._db), this._dbEngineHint) === "postgres";
+    if (!shouldUsePostgresLock) {
+      return callback(this._db);
+    }
+    if (typeof beginTransaction === "function") {
+      const tx = await beginTransaction.call(this._db);
+      if (!tx) {
+        throw new Error("Database transaction could not be started");
+      }
+      try {
+        await tx.query(SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL);
+        const result = await callback(tx);
+        await tx.commit();
+        return result;
+      } catch (error) {
+        await this.rollbackSystemTableBootstrap(tx);
+        throw error;
+      }
+    }
+    if (typeof transaction === "function") {
+      const runInTransaction = transaction.bind(this._db);
+      return runInTransaction(async (tx) => {
+        await tx.query(SYSTEM_TABLE_BOOTSTRAP_LOCK_SQL);
+        return callback(tx);
+      });
+    }
+    throw new Error(
+      "Postgres system table bootstrap requires a transaction-capable database adapter"
+    );
+  }
+  async rollbackSystemTableBootstrap(tx) {
+    try {
+      if (typeof tx.isActive !== "function" || tx.isActive()) {
+        await tx.rollback();
+      }
+    } catch (rollbackError) {
+      logger.warn(
+        `[smrt] Failed to rollback system table bootstrap transaction: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`
+      );
+    }
+  }
+  async bootstrapSystemTables(db) {
+    const version = SMRT_SCHEMA_VERSION;
+    if (await this.isSystemSchemaVersionApplied(db, version)) {
+      return;
+    }
+    await ensureLegacySystemTableCompatibility(db, this._dbEngineHint);
+    const allStatements = [];
+    for (const multiStatementSQL of ALL_SYSTEM_TABLES) {
+      const statements = multiStatementSQL.split(";").map((s) => s.trim()).filter((s) => s.length > 0);
+      allStatements.push(...statements);
+    }
+    for (const statement of allStatements) {
+      await db.query(statement);
+    }
+    const id = crypto.randomUUID();
+    const description = "Initial SMRT system tables";
+    await db.execute`
+      INSERT INTO _smrt_migrations (id, version, description)
+      VALUES (${id}, ${version}, ${description})
+      ON CONFLICT(version) DO NOTHING
+    `;
+  }
+  async ensureNativeVectorStorage() {
+    if (!this._db) {
+      return;
+    }
+    try {
+      const { ObjectRegistry } = await import("./registry.js");
+      const embeddingConfig = ObjectRegistry.getProjectEmbeddingConfig();
+      if (embeddingConfig?.storage === "native") {
+        const { EmbeddingStorage } = await import("./embeddings/storage.js");
+        const vector = this._db.vector;
+        if (vector) {
+          const dimensions = embeddingConfig.dimensions || 768;
+          await EmbeddingStorage.ensureVectorStorage(
+            this._db,
+            dimensions,
+            vector
+          );
+        } else {
+          logger.warn(
+            '[smrt] Embedding storage set to "native" but database has no vector capability. Falling back to JSON storage.'
+          );
+        }
+      }
+    } catch (error) {
+      logger.warn(
+        `[smrt] Failed to initialize vector storage: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Access system tables through standard database interface
+   * System tables use _smrt_ prefix to avoid conflicts with user tables
+   */
+  get systemDb() {
+    return this._db;
+  }
+  /**
+   * Initialize signal bus and adapters
+   *
+   * Merges global configuration with instance-specific overrides.
+   * Registers built-in and custom adapters based on configuration.
+   */
+  async initializeSignals() {
+    const globalConfig = config.toJSON();
+    const effectiveConfig = this.mergeSignalConfig(globalConfig);
+    if (this.options.signals?.bus) {
+      this._signalBus = this.options.signals.bus;
+      return;
+    }
+    if (!this.shouldInitializeSignals(effectiveConfig)) {
+      return;
+    }
+    this._signalBus = new SignalBus({
+      sanitization: effectiveConfig.sanitization
+    });
+    await this.registerAdapters(effectiveConfig);
+  }
+  /**
+   * Merge global and instance signal configuration
+   *
+   * Instance configuration takes priority over global defaults.
+   *
+   * @param globalConfig - Global configuration from smrt.configure()
+   * @returns Merged configuration
+   */
+  mergeSignalConfig(globalConfig) {
+    return {
+      logging: this.options.logging ?? globalConfig.logging,
+      metrics: this.options.metrics ?? globalConfig.metrics,
+      pubsub: this.options.pubsub ?? globalConfig.pubsub,
+      usage: this.mergeAiUsageConfig(globalConfig),
+      sanitization: this.options.sanitization ?? globalConfig.sanitization,
+      signals: {
+        bus: this.options.signals?.bus ?? globalConfig.signals?.bus,
+        adapters: [
+          ...globalConfig.signals?.adapters ?? [],
+          ...this.options.signals?.adapters ?? []
+        ]
+      }
+    };
+  }
+  /**
+   * Check if signals should be initialized
+   *
+   * Signals are initialized if any adapter is configured.
+   *
+   * @param config - Effective signal configuration
+   * @returns True if signals should be initialized
+   */
+  shouldInitializeSignals(config2) {
+    return !!(config2.logging !== false || config2.metrics?.enabled || config2.pubsub?.enabled || config2.signals?.adapters?.length);
+  }
+  /**
+   * Register signal adapters based on configuration
+   *
+   * @param config - Effective signal configuration
+   */
+  async registerAdapters(config2) {
+    if (!this._signalBus) return;
+    if (config2.logging !== false) {
+      const { createLogger: createLogger2, LoggerAdapter } = await import("@happyvertical/logger");
+      const logger2 = createLogger2(config2.logging ?? true);
+      const adapter = new LoggerAdapter(logger2);
+      this._signalBus.register(adapter);
+      this._registeredAdapters.push(adapter);
+    }
+    if (config2.metrics?.enabled) {
+      const { MetricsAdapter } = await import("./adapters/metrics.js");
+      const adapter = new MetricsAdapter();
+      this._signalBus.register(adapter);
+      this._registeredAdapters.push(adapter);
+    }
+    if (config2.pubsub?.enabled) {
+      const { PubSubAdapter } = await import("./adapters/pubsub.js");
+      const adapter = new PubSubAdapter();
+      this._signalBus.register(adapter);
+      this._registeredAdapters.push(adapter);
+    }
+    if (config2.signals?.adapters) {
+      for (const adapter of config2.signals.adapters) {
+        this._signalBus.register(adapter);
+        this._registeredAdapters.push(adapter);
+      }
+    }
+  }
+  /**
+   * Gets the filesystem adapter instance
+   */
+  get fs() {
+    return this._fs;
+  }
+  /**
+   * Gets the database interface instance
+   */
+  get db() {
+    if (!this._db) {
+      throw new Error(
+        `Database accessed before initialization. Please call await instance.initialize() before accessing the database.`
+      );
+    }
+    return this._db;
+  }
+  /**
+   * Gets the AI client instance
+   */
+  get ai() {
+    return this._ai;
+  }
+  /**
+   * Get the in-memory AI usage snapshot for this instance.
+   */
+  getAiUsageSnapshot() {
+    return this._aiUsageCollector?.getSnapshot();
+  }
+  /**
+   * Reset the in-memory AI usage collector.
+   */
+  resetAiUsage() {
+    this._aiUsageCollector?.reset();
+  }
+  /**
+   * List persisted AI usage records.
+   */
+  async listAiUsage(options = {}) {
+    if (!this._db) {
+      throw new Error(
+        `AI usage requires a database configuration. Please call initialize() with a db option before querying usage.`
+      );
+    }
+    const { conditions, params } = buildAiUsageWhereClause(options);
+    let paramIndex = params.length + 1;
+    let sql = "SELECT * FROM _smrt_ai_usage";
+    if (conditions.length > 0) {
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+    }
+    sql += ` ORDER BY ${options.orderBy === "timestamp ASC" ? "created_at ASC" : "created_at DESC"}`;
+    if (options.limit !== void 0) {
+      sql += ` LIMIT $${paramIndex++}`;
+      params.push(options.limit);
+    }
+    if (options.offset !== void 0) {
+      sql += ` OFFSET $${paramIndex++}`;
+      params.push(options.offset);
+    }
+    const rows = getQueryRows(await this._db.query(sql, ...params));
+    return rows.map((row) => ({
+      id: String(row.id),
+      provider: String(row.provider),
+      model: String(row.model),
+      operation: String(row.operation),
+      usage: hydratePersistedAiUsageTokens(row),
+      estimatedCost: row.estimated_cost === null || row.estimated_cost === void 0 ? void 0 : Number(row.estimated_cost),
+      duration: Number(row.duration ?? 0),
+      className: row.class_name === null || row.class_name === void 0 ? void 0 : String(row.class_name),
+      tenantId: row.tenant_id === void 0 ? void 0 : row.tenant_id,
+      tags: parseAiUsageTags(row.tags),
+      timestamp: normalizeAiUsageTimestamp(row.created_at)
+    }));
+  }
+  /**
+   * Summarize persisted AI usage records by a grouping dimension.
+   */
+  async summarizeAiUsage(options = {}) {
+    if (!this._db) {
+      throw new Error(
+        `AI usage requires a database configuration. Please call initialize() with a db option before querying usage.`
+      );
+    }
+    const groupBy = options.groupBy ?? "model";
+    const bucketExpression = groupBy === "provider" ? `provider` : groupBy === "model" ? `provider || ':' || model` : groupBy === "class" ? `COALESCE(class_name, 'unknown')` : groupBy === "tenant" ? `COALESCE(tenant_id, 'global')` : groupBy === "operation" ? `operation` : `substr(CAST(created_at AS TEXT), 1, 10)`;
+    const { conditions, params } = buildAiUsageWhereClause(options);
+    let sql = `
+      SELECT ${bucketExpression} AS bucket,
+             COUNT(*) AS call_count,
+             COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,
+             COALESCE(SUM(completion_tokens), 0) AS completion_tokens,
+             COALESCE(SUM(total_tokens), 0) AS total_tokens,
+             COALESCE(SUM(duration), 0) AS total_duration,
+             COALESCE(SUM(estimated_cost), 0) AS estimated_cost,
+             MAX(created_at) AS last_used
+      FROM _smrt_ai_usage
+    `;
+    if (conditions.length > 0) {
+      sql += ` WHERE ${conditions.join(" AND ")}`;
+    }
+    sql += " GROUP BY bucket ORDER BY bucket ASC";
+    const rows = getQueryRows(await this._db.query(sql, ...params));
+    const summary = {};
+    for (const row of rows) {
+      const bucket = String(row.bucket);
+      summary[bucket] = {
+        callCount: Number(row.call_count ?? 0),
+        promptTokens: Number(row.prompt_tokens ?? 0),
+        completionTokens: Number(row.completion_tokens ?? 0),
+        totalTokens: Number(row.total_tokens ?? 0),
+        totalDuration: Number(row.total_duration ?? 0),
+        estimatedCost: Number(row.estimated_cost ?? 0),
+        lastUsed: row.last_used ? new Date(String(row.last_used)).getTime() : 0
+      };
+    }
+    return summary;
+  }
+  /**
+   * Gets the signal bus instance
+   *
+   * @returns Signal bus if signals are enabled, undefined otherwise
+   */
+  get signalBus() {
+    return this._signalBus;
+  }
+  /**
+   * Cleanup method to prevent memory leaks
+   *
+   * Unregisters all adapters from the signal bus that were registered
+   * by this instance. Call this when the SmrtClass instance is no longer
+   * needed to prevent memory leaks.
+   *
+   * @example
+   * ```typescript
+   * const product = new Product({ name: 'Widget' });
+   * await product.initialize();
+   * // ... use product ...
+   * product.destroy(); // Clean up when done
+   * ```
+   */
+  destroy() {
+    if (this._signalBus && !this.options.signals?.bus) {
+      for (const adapter of this._registeredAdapters) {
+        this._signalBus.unregister(adapter);
+      }
+      this._registeredAdapters = [];
+    }
+    this._aiUsageCollector = void 0;
+    this._aiUsageHandlers = [];
+  }
+  mergeAiUsageConfig(globalConfig) {
+    const globalUsage = globalConfig.usage ?? {};
+    const instanceUsage = this.options.usage ?? {};
+    return {
+      enabled: instanceUsage.enabled ?? globalUsage.enabled ?? true,
+      persist: instanceUsage.persist ?? globalUsage.persist ?? true,
+      estimateCosts: instanceUsage.estimateCosts ?? globalUsage.estimateCosts ?? true,
+      costRates: {
+        ...globalUsage.costRates ?? {},
+        ...instanceUsage.costRates ?? {}
+      },
+      handlers: [
+        ...globalUsage.handlers ?? [],
+        ...instanceUsage.handlers ?? []
+      ]
+    };
+  }
+  initializeAiUsageHandlers(config2) {
+    this._aiUsageCollector = void 0;
+    this._aiUsageHandlers = [];
+    if (!config2.enabled) {
+      return;
+    }
+    this._aiUsageCollector = new AiUsageCollector();
+    this._aiUsageHandlers.push(this._aiUsageCollector);
+    if (config2.persist && this._db) {
+      this._aiUsageHandlers.push(new AiUsagePersistenceHandler(this._db));
+    }
+    this._aiUsageHandlers.push(...config2.handlers);
+  }
+  async handleAiUsageCallback(event, aiConfig, usageConfig) {
+    if (!usageConfig.enabled || this._aiUsageHandlers.length === 0) {
+      return;
+    }
+    const normalizedEvent = this.normalizeAiUsageEvent(event, aiConfig);
+    if (!normalizedEvent) {
+      return;
+    }
+    if (usageConfig.estimateCosts) {
+      normalizedEvent.estimatedCost = estimateAiUsageCost(
+        normalizedEvent.provider,
+        normalizedEvent.model,
+        normalizedEvent.usage,
+        usageConfig.costRates
+      );
+    }
+    const results = await Promise.allSettled(
+      this._aiUsageHandlers.map((handler) => handler.handle(normalizedEvent))
+    );
+    for (const result of results) {
+      if (result.status === "rejected") {
+        logger.warn(
+          `[smrt] AI usage handler failed for ${normalizedEvent.provider}:${normalizedEvent.model}: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`
+        );
+      }
+    }
+  }
+  normalizeAiUsageEvent(event, aiConfig) {
+    const raw = event ?? {};
+    const provider = firstString(
+      raw.provider,
+      raw.type,
+      aiConfig.provider,
+      aiConfig.type
+    );
+    const model = firstString(
+      raw.model,
+      raw.defaultModel,
+      aiConfig.model,
+      aiConfig.defaultModel
+    );
+    const operation = firstString(raw.operation, raw.kind, raw.method) ?? "unknown";
+    const usage = normalizeIncomingAiUsageTokens(raw.usage) ?? normalizeIncomingAiUsageTokens(raw.tokenUsage) ?? normalizeIncomingAiUsageTokens({
+      promptTokens: raw.promptTokens,
+      completionTokens: raw.completionTokens,
+      totalTokens: raw.totalTokens
+    });
+    if (!provider || !model) {
+      return void 0;
+    }
+    const duration = firstNumber(raw.duration, raw.durationMs, raw.latency) ?? 0;
+    const tenantId = "tenantId" in this && this.tenantId !== void 0 ? this.tenantId ?? null : void 0;
+    return {
+      provider,
+      model,
+      operation,
+      usage,
+      duration,
+      timestamp: normalizeAiUsageTimestamp(raw.timestamp),
+      tags: normalizeAiUsageTags(raw.tags),
+      className: this._className,
+      tenantId
+    };
+  }
+}
+export {
+  SmrtClass
+};
+//# sourceMappingURL=class.js.map