@deepagents/text2sql 6.0.0 → 6.1.2

package/dist/lib/adapters/posthog/index.js

@@ -0,0 +1,1317 @@
+// packages/text2sql/src/lib/adapters/groundings/abstract.grounding.ts
+function filterColumns(columns, filter) {
+  if (Array.isArray(filter)) {
+    return columns.filter((col) => filter.includes(col.name));
+  }
+  if (filter instanceof RegExp) {
+    return columns.filter((col) => filter.test(col.name));
+  }
+  return columns.filter((col) => filter(col.name));
+}
+function applyColumnFilter(entity, columnsConfig) {
+  if (!columnsConfig) return entity;
+  const filter = columnsConfig[entity.name];
+  if (!filter) return entity;
+  return { ...entity, columns: filterColumns(entity.columns, filter) };
+}
+var AbstractGrounding = class {
+  /**
+   * Grounding identifier for debugging/logging.
+   */
+  name;
+  phase;
+  constructor(name, phase) {
+    this.name = name;
+    this.phase = phase;
+  }
+  /**
+   * Populate ctx with the tables/views this grounding makes available for scope
+   * resolution. Annotators decorate entities other groundings produced and add
+   * no membership, so the default is a no-op; entity-producing groundings
+   * override it. This lets scope resolution skip the annotators' metadata scans.
+   *
+   * @param _ctx - Shared context for accumulating entity membership
+   */
+  async contributeEntities(_ctx) {
+  }
+};
+
+// packages/text2sql/src/lib/adapters/posthog/definitions.posthog.grounding.ts
+var PostHogDefinitionsGrounding = class extends AbstractGrounding {
+  #adapter;
+  #config;
+  constructor(adapter, config = {}) {
+    super("definitions", "definitions");
+    this.#adapter = adapter;
+    this.#config = config;
+  }
+  async execute(ctx) {
+    const fragments = ctx.fragments ??= [];
+    const configuredPropertyTypes = this.#config.propertyTypes ?? ["event", "person", "session"];
+    const propertyTypes = [
+      ...new Set(configuredPropertyTypes)
+    ];
+    validatePropertyTypes(propertyTypes);
+    const groupTypeIndexes = [...new Set(this.#config.groupTypeIndexes ?? [])];
+    if (groupTypeIndexes.some((index2) => !Number.isInteger(index2) || index2 < 0)) {
+      throw new Error(
+        "PostHog groupTypeIndexes must contain non-negative integers."
+      );
+    }
+    const propertyRequests = [
+      ...propertyTypes.map(async (type) => ({
+        type,
+        definitions: await this.#adapter.transport.listPropertyDefinitions({
+          type
+        })
+      })),
+      ...groupTypeIndexes.map(async (groupTypeIndex) => ({
+        type: `group:${groupTypeIndex}`,
+        definitions: await this.#adapter.transport.listPropertyDefinitions({
+          type: "group",
+          groupTypeIndex
+        })
+      }))
+    ];
+    const [events, properties] = await Promise.all([
+      this.#adapter.transport.listEventDefinitions(),
+      Promise.all(propertyRequests)
+    ]);
+    const eventData = readEvents(events, this.#config.events);
+    if (eventData.length > 0) {
+      fragments.push({ name: "posthogEvents", data: eventData });
+    }
+    const propertyData = {};
+    for (const group of properties) {
+      const definitions2 = readProperties(
+        group.definitions,
+        this.#config.properties
+      );
+      if (definitions2.length > 0) propertyData[group.type] = definitions2;
+    }
+    if (Object.keys(propertyData).length > 0) {
+      fragments.push({
+        name: "posthogProperties",
+        data: propertyData
+      });
+    }
+  }
+};
+function readEvents(values, filter) {
+  return values.map(validateEvent).filter((event) => matchesFilter(event.name, filter)).toSorted((left, right) => left.name.localeCompare(right.name)).map(
+    (event) => compact({
+      name: event.name,
+      description: event.description ?? void 0,
+      tags: event.tags?.length ? event.tags : void 0,
+      verified: event.verified ?? void 0
+    })
+  );
+}
+function readProperties(values, filter) {
+  return values.map(validateProperty).filter((property) => matchesFilter(property.name, filter)).toSorted((left, right) => left.name.localeCompare(right.name)).map(
+    (property) => compact({
+      name: property.name,
+      description: property.description ?? void 0,
+      propertyType: property.property_type ?? void 0,
+      numerical: property.is_numerical ?? void 0,
+      verified: property.verified ?? void 0
+    })
+  );
+}
+function validateEvent(value) {
+  if (!isRecord(value) || !readNonEmptyString(value.name) || !isOptionalString(value.description) || !isOptionalBoolean(value.verified) || !isOptionalStringArray(value.tags)) {
+    throw new Error("PostHog returned a malformed event definition.");
+  }
+  return value;
+}
+function validateProperty(value) {
+  if (!isRecord(value) || !readNonEmptyString(value.name) || !isOptionalString(value.description) || !isOptionalString(value.property_type) || !isOptionalBoolean(value.is_numerical) || !isOptionalBoolean(value.verified)) {
+    throw new Error("PostHog returned a malformed property definition.");
+  }
+  return value;
+}
+function validatePropertyTypes(values) {
+  const allowed = /* @__PURE__ */ new Set(["event", "person", "session"]);
+  if (values.some((value) => !allowed.has(value))) {
+    throw new Error("PostHog propertyTypes contains an unsupported type.");
+  }
+}
+function matchesFilter(name, filter) {
+  if (!filter) return true;
+  if (Array.isArray(filter)) return filter.includes(name);
+  if (filter instanceof RegExp) {
+    filter.lastIndex = 0;
+    return filter.test(name);
+  }
+  return filter(name);
+}
+function compact(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter((entry) => entry[1] !== void 0)
+  );
+}
+function isOptionalString(value) {
+  return value === void 0 || value === null || typeof value === "string";
+}
+function isOptionalBoolean(value) {
+  return value === void 0 || value === null || typeof value === "boolean";
+}
+function isOptionalStringArray(value) {
+  return value === void 0 || value === null || Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function readNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/text2sql/src/lib/adapters/posthog/info.posthog.grounding.ts
+var PostHogInfoGrounding = class extends AbstractGrounding {
+  constructor() {
+    super("info", "info");
+  }
+  async execute(ctx) {
+    ctx.info = {
+      dialect: "HogQL",
+      details: {
+        identifierQuoting: "Use backticks for identifiers that require quoting.",
+        propertyAccess: "Use PostHog HogQL property access and the grounded event/person/session property definitions. Do not guess property names.",
+        performance: "Prefer bounded time ranges and LIMIT for non-aggregate event queries. OFFSET is not supported by the Query API.",
+        execution: "Queries run through PostHog as read-only HogQLQuery nodes, not through a PostgreSQL connection."
+      }
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+import { format as formatSql } from "sql-formatter";
+
+// packages/text2sql/src/lib/agents/exceptions.ts
+var sqlValidationMarker = /* @__PURE__ */ Symbol("SQLValidationError");
+var unanswerableSqlMarker = /* @__PURE__ */ Symbol("UnanswerableSQLError");
+var sqlScopeMarker = /* @__PURE__ */ Symbol("SQLScopeError");
+var sqlReadOnlyMarker = /* @__PURE__ */ Symbol("SQLReadOnlyError");
+var SQLValidationError = class _SQLValidationError extends Error {
+  [sqlValidationMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLValidationError";
+    this[sqlValidationMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[sqlValidationMarker] === true;
+  }
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  [unanswerableSqlMarker];
+  constructor(message) {
+    super(message);
+    this.name = "UnanswerableSQLError";
+    this[unanswerableSqlMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
+  }
+};
+var SQLScopeError = class _SQLScopeError extends Error {
+  [sqlScopeMarker];
+  payload;
+  errorType;
+  constructor(payload) {
+    super(JSON.stringify(payload));
+    this.name = "SQLScopeError";
+    this.payload = payload;
+    this.errorType = payload.error_type;
+    this[sqlScopeMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLScopeError && error[sqlScopeMarker] === true;
+  }
+};
+var SQLReadOnlyError = class _SQLReadOnlyError extends Error {
+  [sqlReadOnlyMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLReadOnlyError";
+    this[sqlReadOnlyMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLReadOnlyError && error[sqlReadOnlyMarker] === true;
+  }
+};
+
+// packages/text2sql/src/lib/fragments/schema.ts
+function dialectInfo(input) {
+  return {
+    name: "dialectInfo",
+    data: {
+      dialect: input.dialect,
+      ...input.version && { version: input.version },
+      ...input.database && { database: input.database },
+      ...input.details && { details: input.details }
+    }
+  };
+}
+function table(input) {
+  return {
+    name: "table",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      ...input.rowCount != null && { rowCount: input.rowCount },
+      ...input.sizeHint && { sizeHint: input.sizeHint },
+      columns: input.columns,
+      ...input.indexes?.length && { indexes: input.indexes },
+      ...input.constraints?.length && { constraints: input.constraints }
+    }
+  };
+}
+function column(input) {
+  return {
+    name: "column",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.pk && { pk: true },
+      ...input.fk && { fk: input.fk },
+      ...input.unique && { unique: true },
+      ...input.notNull && { notNull: true },
+      ...input.default && { default: input.default },
+      ...input.indexed && { indexed: true },
+      ...input.values?.length && { values: input.values },
+      ...input.stats && { stats: input.stats }
+    }
+  };
+}
+function index(input) {
+  return {
+    name: "index",
+    data: {
+      name: input.name,
+      columns: input.columns,
+      ...input.unique && { unique: true },
+      ...input.type && { type: input.type }
+    }
+  };
+}
+function constraint(input) {
+  return {
+    name: "constraint",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.columns?.length && { columns: input.columns },
+      ...input.definition && { definition: input.definition },
+      ...input.defaultValue && { defaultValue: input.defaultValue },
+      ...input.referencedTable && { referencedTable: input.referencedTable },
+      ...input.referencedColumns?.length && {
+        referencedColumns: input.referencedColumns
+      }
+    }
+  };
+}
+function view(input) {
+  return {
+    name: "view",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      columns: input.columns,
+      ...input.definition && { definition: input.definition }
+    }
+  };
+}
+function relationship(input) {
+  return {
+    name: "relationship",
+    data: {
+      from: input.from,
+      to: input.to,
+      ...input.cardinality && { cardinality: input.cardinality }
+    }
+  };
+}
+
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+var noopProgress = () => {
+};
+function timestampProgress(onProgress) {
+  if (!onProgress) return noopProgress;
+  return (progress) => {
+    onProgress({
+      ...progress,
+      timestampMs: progress.timestampMs ?? Date.now()
+    });
+  };
+}
+function createGroundingContext(options = {}) {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0,
+    fragments: [],
+    cache: /* @__PURE__ */ new Map(),
+    onProgress: timestampProgress(options.onProgress)
+  };
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  #policyAnalyzer;
+  /**
+   * Injects the strategy that guards validate() and execute().
+   */
+  constructor(policyAnalyzer) {
+    this.#policyAnalyzer = policyAnalyzer;
+  }
+  /**
+   * Introspect the database schema and return context fragments.
+   *
+   * Executes all configured groundings to populate the context, then
+   * generates fragments from the complete context data.
+   *
+   * @param ctx - Optional grounding context for sharing state between groundings
+   * @returns Array of context fragments representing the database schema
+   */
+  async introspect(ctx = createGroundingContext()) {
+    for (const fn of this.grounding) {
+      const grounding = fn(this);
+      if (grounding.phase) {
+        ctx.onProgress({
+          type: "phase:start",
+          phase: grounding.phase,
+          message: `Starting ${grounding.name} introspection...`
+        });
+      }
+      try {
+        await grounding.execute(ctx);
+      } finally {
+        if (grounding.phase) {
+          ctx.onProgress({
+            type: "phase:end",
+            phase: grounding.phase,
+            message: `Finished ${grounding.name} introspection.`
+          });
+        }
+      }
+    }
+    return this.#toSchemaFragments(ctx);
+  }
+  /**
+   * Resolve the allowed entity names (tables + views) from grounding config.
+   * Asks each grounding to contribute its entities; annotators contribute
+   * nothing, so their metadata scans are skipped.
+   * Results are NOT cached — call once and store the result.
+   */
+  async resolveAllowedEntities() {
+    const ctx = createGroundingContext();
+    for (const fn of this.grounding) {
+      await fn(this).contributeEntities(ctx);
+    }
+    return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
+  }
+  /**
+   * Convert complete grounding context to schema fragments.
+   * Called after all groundings have populated ctx with data.
+   */
+  #toSchemaFragments(ctx) {
+    const fragments = [];
+    if (ctx.info) {
+      fragments.push(
+        dialectInfo({
+          dialect: ctx.info.dialect,
+          version: ctx.info.version,
+          database: ctx.info.database,
+          details: ctx.info.details
+        })
+      );
+    }
+    for (const t of ctx.tables) {
+      fragments.push(this.#tableToFragment(t));
+    }
+    for (const v of ctx.views) {
+      fragments.push(this.#viewToFragment(v));
+    }
+    const tableMap = new Map(ctx.tables.map((t) => [t.name, t]));
+    const tableColumnSets = new Map(
+      ctx.tables.map((t) => [t.name, new Set(t.columns.map((c) => c.name))])
+    );
+    for (const rel of ctx.relationships) {
+      const sourceColumns = tableColumnSets.get(rel.table);
+      const targetColumns = tableColumnSets.get(rel.referenced_table);
+      if (sourceColumns && rel.from.some((column2) => !sourceColumns.has(column2))) {
+        continue;
+      }
+      if (targetColumns && rel.to.some((column2) => !targetColumns.has(column2))) {
+        continue;
+      }
+      const sourceTable = tableMap.get(rel.table);
+      const targetTable = tableMap.get(rel.referenced_table);
+      fragments.push(
+        this.#relationshipToFragment(rel, sourceTable, targetTable)
+      );
+    }
+    fragments.push(...ctx.fragments ?? []);
+    return fragments;
+  }
+  /**
+   * Convert a Table to a table fragment with nested column, index, and constraint fragments.
+   */
+  #tableToFragment(t) {
+    const pkConstraint = t.constraints?.find((c) => c.type === "PRIMARY_KEY");
+    const pkColumns = new Set(pkConstraint?.columns ?? []);
+    const notNullColumns = new Set(
+      t.constraints?.filter((c) => c.type === "NOT_NULL").flatMap((c) => c.columns ?? []) ?? []
+    );
+    const defaultByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "DEFAULT") ?? []) {
+      for (const col of c.columns ?? []) {
+        if (c.defaultValue != null) {
+          defaultByColumn.set(col, c.defaultValue);
+        }
+      }
+    }
+    const uniqueColumns = new Set(
+      t.constraints?.filter((c) => c.type === "UNIQUE" && c.columns?.length === 1).flatMap((c) => c.columns ?? []) ?? []
+    );
+    const fkByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "FOREIGN_KEY") ?? []) {
+      const cols = c.columns ?? [];
+      const refCols = c.referencedColumns ?? [];
+      for (let i = 0; i < cols.length; i++) {
+        const refCol = refCols[i] ?? refCols[0] ?? cols[i];
+        fkByColumn.set(cols[i], `${c.referencedTable}.${refCol}`);
+      }
+    }
+    const columnFragments = t.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        pk: pkColumns.has(col.name) || void 0,
+        fk: fkByColumn.get(col.name),
+        unique: uniqueColumns.has(col.name) || void 0,
+        notNull: notNullColumns.has(col.name) || void 0,
+        default: defaultByColumn.get(col.name),
+        indexed: col.isIndexed || void 0,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    const presentColumns = new Set(t.columns.map((c) => c.name));
+    const indexFragments = (t.indexes ?? []).filter(
+      (idx) => idx.columns.every((column2) => presentColumns.has(column2))
+    ).map(
+      (idx) => index({
+        name: idx.name,
+        columns: idx.columns,
+        unique: idx.unique,
+        type: idx.type
+      })
+    );
+    const constraintFragments = (t.constraints ?? []).filter(
+      (c) => c.type === "CHECK" || c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
+    ).filter(
+      (c) => !c.columns?.length || c.columns.every((column2) => presentColumns.has(column2))
+    ).map(
+      (c) => constraint({
+        name: c.name,
+        type: c.type,
+        columns: c.columns,
+        definition: c.definition
+      })
+    );
+    return table({
+      name: t.name,
+      schema: t.schema,
+      rowCount: t.rowCount,
+      sizeHint: t.sizeHint,
+      columns: columnFragments,
+      indexes: indexFragments.length > 0 ? indexFragments : void 0,
+      constraints: constraintFragments.length > 0 ? constraintFragments : void 0
+    });
+  }
+  /**
+   * Convert a View to a view fragment with nested column fragments.
+   */
+  #viewToFragment(v) {
+    const columnFragments = v.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    return view({
+      name: v.name,
+      schema: v.schema,
+      columns: columnFragments,
+      definition: v.definition
+    });
+  }
+  /**
+   * Convert a Relationship to a relationship fragment.
+   * Infers cardinality from row counts if available.
+   */
+  #relationshipToFragment(rel, sourceTable, targetTable) {
+    const sourceCount = sourceTable?.rowCount;
+    const targetCount = targetTable?.rowCount;
+    let cardinality;
+    if (sourceCount != null && targetCount != null && targetCount > 0) {
+      const ratio = sourceCount / targetCount;
+      if (ratio > 5) {
+        cardinality = "many-to-one";
+      } else if (ratio < 1.2 && ratio > 0.8) {
+        cardinality = "one-to-one";
+      } else if (ratio < 0.2) {
+        cardinality = "one-to-many";
+      }
+    }
+    return relationship({
+      from: { table: rel.table, columns: rel.from },
+      to: { table: rel.referenced_table, columns: rel.to },
+      cardinality
+    });
+  }
+  format(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    try {
+      return formatSql(decoded, { language: this.formatterLanguage });
+    } catch {
+      return decoded;
+    }
+  }
+  #decodeShellEscapes(sql) {
+    return sql.replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\([().*])/g, "$1").replace(/\\(?=$)/gm, "");
+  }
+  #cachedAllowedEntities = null;
+  async #resolveScope() {
+    if (this.#cachedAllowedEntities) return this.#cachedAllowedEntities;
+    this.#cachedAllowedEntities = await this.resolveAllowedEntities();
+    return this.#cachedAllowedEntities;
+  }
+  async #analyzePolicy(sql) {
+    return this.#policyAnalyzer.analyze(sql, {
+      resolveAllowedEntities: () => this.#resolveScope()
+    });
+  }
+  async validate(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") return violation.message;
+    if (violation?.kind === "scope") return JSON.stringify(violation.payload);
+    return this.validateImpl(decoded);
+  }
+  async execute(sql) {
+    return this.executeImpl(await this.enforceExecutionPolicy(sql));
+  }
+  async enforceExecutionPolicy(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") {
+      throw new SQLReadOnlyError(violation.message);
+    }
+    if (violation?.kind === "scope") {
+      throw new SQLScopeError(violation.payload);
+    }
+    return decoded;
+  }
+  /**
+   * Convert unknown database value to number.
+   * Handles number, bigint, and string types.
+   */
+  toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Parse a potentially qualified table name into schema and table parts.
+   */
+  parseTableName(name) {
+    if (name.includes(".")) {
+      const [schema2, ...rest] = name.split(".");
+      return { schema: schema2, table: rest.join(".") };
+    }
+    return { schema: this.defaultSchema ?? "", table: name };
+  }
+  /**
+   * Escape a string value for use in SQL string literals (single quotes).
+   * Used in WHERE clauses like: WHERE name = '${escapeString(value)}'
+   */
+  escapeString(value) {
+    return value.replace(/'/g, "''");
+  }
+  /**
+   * Build a SQL filter clause to include/exclude schemas.
+   * @param columnName - The schema column name (e.g., 'TABLE_SCHEMA')
+   * @param allowedSchemas - If provided, filter to these schemas only
+   */
+  buildSchemaFilter(columnName, allowedSchemas) {
+    if (allowedSchemas && allowedSchemas.length > 0) {
+      const values = allowedSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    if (this.systemSchemas.length > 0) {
+      const values = this.systemSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} NOT IN (${values})`;
+    }
+    return "";
+  }
+};
+
+// packages/text2sql/src/lib/sql-scope-error.ts
+function buildScopeParseErrorPayload(sql, parserDialect, error) {
+  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
+  return {
+    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
+    error_type: "SQL_SCOPE_PARSE_ERROR",
+    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
+    sql_attempted: sql,
+    parser_dialect: parserDialect,
+    parser_error: parserError
+  };
+}
+
+// packages/text2sql/src/lib/adapters/posthog/posthog.sql-policy.ts
+var PostHogSqlPolicyAnalyzer = class {
+  #transport;
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  async analyze(sql, context) {
+    const response = await this.#transport.query({
+      query: { kind: "HogQLMetadata", language: "hogQL", query: sql },
+      name: "deepagents_text2sql_validate"
+    });
+    let metadata;
+    try {
+      metadata = validateMetadataResponse(response);
+    } catch (error) {
+      return {
+        kind: "scope",
+        payload: buildScopeParseErrorPayload(sql, "hogql", error)
+      };
+    }
+    const allowedEntities = await context.resolveAllowedEntities();
+    const allowed = new Set(allowedEntities.map(caseFold));
+    const rejected = metadata.table_names.filter(
+      (entity) => !allowed.has(caseFold(entity))
+    );
+    return rejected.length > 0 ? {
+      kind: "scope",
+      payload: buildOutOfScopePayload(sql, rejected, [...allowedEntities])
+    } : null;
+  }
+};
+function validateMetadataResponse(value) {
+  if (!isRecord2(value)) {
+    throw new Error("PostHog HogQLMetadata response must be a JSON object.");
+  }
+  if (typeof value.isValid !== "boolean") {
+    throw new Error("PostHog HogQLMetadata response has no isValid boolean.");
+  }
+  const errors = validateNotices(value.errors, "errors");
+  validateNotices(value.warnings, "warnings");
+  validateNotices(value.notices, "notices");
+  const tableNames = validateTableNames(value.table_names);
+  if (!value.isValid || errors.length > 0) {
+    const reason = errors.map((notice) => notice.message).join("; ");
+    throw new Error(
+      reason ? `PostHog rejected the HogQL query: ${reason}` : "PostHog rejected the HogQL query as invalid."
+    );
+  }
+  return {
+    isValid: true,
+    errors,
+    warnings: value.warnings,
+    notices: value.notices,
+    table_names: tableNames
+  };
+}
+function validateNotices(value, name) {
+  if (!Array.isArray(value)) {
+    throw new Error(`PostHog HogQLMetadata response has no ${name} array.`);
+  }
+  for (const notice of value) {
+    if (!isRecord2(notice) || typeof notice.message !== "string") {
+      throw new Error(
+        `PostHog HogQLMetadata response has an invalid ${name} notice.`
+      );
+    }
+  }
+  return value;
+}
+function validateTableNames(value) {
+  if (!Array.isArray(value) || value.some((name) => typeof name !== "string" || name.length === 0)) {
+    throw new Error("PostHog HogQLMetadata response has invalid table_names.");
+  }
+  return [...new Set(value)];
+}
+function buildOutOfScopePayload(sql, referencedEntities, allowedEntities) {
+  return {
+    error: `Query references entities outside grounded scope: ${referencedEntities.join(", ")}`,
+    error_type: "OUT_OF_SCOPE",
+    suggestion: "Restrict the query to grounded tables/views or expand grounding to include the referenced entities.",
+    sql_attempted: sql,
+    referenced_entities: referencedEntities,
+    allowed_entities: allowedEntities
+  };
+}
+function caseFold(value) {
+  return value.toLowerCase();
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/text2sql/src/lib/adapters/posthog/posthog.ts
+var PostHog = class extends Adapter {
+  transport;
+  grounding;
+  defaultSchema = void 0;
+  systemSchemas = ["system"];
+  formatterLanguage = "clickhouse";
+  constructor(options) {
+    if (!options?.transport || typeof options.transport.query !== "function") {
+      throw new Error("PostHog adapter requires a transport.");
+    }
+    if (typeof options.transport.listEventDefinitions !== "function" || typeof options.transport.listPropertyDefinitions !== "function") {
+      throw new Error(
+        "PostHog transport must provide event and property definition methods."
+      );
+    }
+    super(new PostHogSqlPolicyAnalyzer(options.transport));
+    this.transport = options.transport;
+    this.grounding = options.grounding ?? [];
+  }
+  async execute(sql, values) {
+    return this.#execute(
+      await this.enforceExecutionPolicy(sql),
+      "deepagents_text2sql_execute",
+      values
+    );
+  }
+  async executeImpl(sql) {
+    return this.#execute(sql, "deepagents_text2sql_execute");
+  }
+  validateImpl() {
+    return void 0;
+  }
+  async runQuery(sql) {
+    return await this.#execute(sql, "deepagents_text2sql_grounding");
+  }
+  quoteIdentifier(name) {
+    return `\`${name.replace(/`/g, "``")}\``;
+  }
+  escape(value) {
+    return value.replace(/`/g, "``");
+  }
+  buildSampleRowsQuery(tableName, columns, limit) {
+    const { schema: schema2, table: table2 } = this.parseTableName(tableName);
+    const relation = schema2 ? `${this.quoteIdentifier(schema2)}.${this.quoteIdentifier(table2)}` : this.quoteIdentifier(table2);
+    const projection = columns?.length ? columns.map((column2) => this.quoteIdentifier(column2)).join(", ") : "*";
+    return `SELECT ${projection} FROM ${relation} LIMIT ${limit}`;
+  }
+  async query(request) {
+    return this.transport.query(request);
+  }
+  async #execute(sql, name, values) {
+    const response = await this.transport.query({
+      query: {
+        kind: "HogQLQuery",
+        query: sql,
+        ...values === void 0 ? {} : { values }
+      },
+      name
+    });
+    return rowsFromResponse(response);
+  }
+};
+function rowsFromResponse(value) {
+  if (!isRecord3(value) || !Array.isArray(value.results)) {
+    throw new Error("PostHog HogQLQuery response has no results array.");
+  }
+  if (value.columns !== void 0 && (!Array.isArray(value.columns) || value.columns.some(
+    (column2) => typeof column2 !== "string" || column2.length === 0
+  ))) {
+    throw new Error("PostHog HogQLQuery response has invalid columns.");
+  }
+  if (Array.isArray(value.columns) && new Set(value.columns).size !== value.columns.length) {
+    throw new Error(
+      "PostHog HogQLQuery response contains duplicate column names; alias every selected expression uniquely."
+    );
+  }
+  if (value.results.length === 0) return [];
+  if (!Array.isArray(value.columns)) {
+    throw new Error(
+      "PostHog HogQLQuery response requires columns for non-empty results."
+    );
+  }
+  const columns = value.columns;
+  return value.results.map((row, index2) => {
+    if (!Array.isArray(row) || row.length !== columns.length) {
+      throw new Error(
+        `PostHog HogQLQuery result row ${index2} does not match the column count.`
+      );
+    }
+    return Object.fromEntries(
+      columns.map((column2, columnIndex) => [column2, row[columnIndex]])
+    );
+  });
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/text2sql/src/lib/adapters/posthog/schema.posthog.grounding.ts
+var SCALAR_FIELD_TYPES = /* @__PURE__ */ new Set([
+  "integer",
+  "float",
+  "decimal",
+  "string",
+  "datetime",
+  "date",
+  "boolean",
+  "array",
+  "json"
+]);
+var FIELD_TYPES = /* @__PURE__ */ new Set([
+  ...SCALAR_FIELD_TYPES,
+  "lazy_table",
+  "virtual_table",
+  "field_traverser",
+  "expression",
+  "view",
+  "materialized_view",
+  "unknown"
+]);
+var TABLE_TYPES = /* @__PURE__ */ new Set([
+  "posthog",
+  "system",
+  "data_warehouse",
+  "view",
+  "batch_export",
+  "materialized_view",
+  "managed_view",
+  "endpoint"
+]);
+var VIEW_TYPES = /* @__PURE__ */ new Set([
+  "view",
+  "materialized_view",
+  "managed_view",
+  "endpoint"
+]);
+var PostHogSchemaGrounding = class extends AbstractGrounding {
+  #adapter;
+  #config;
+  constructor(adapter, config = {}) {
+    super("schema", "tables");
+    this.#adapter = adapter;
+    this.#config = config;
+  }
+  async execute(ctx) {
+    const response = validateSchemaResponse(
+      await this.#adapter.query({
+        query: { kind: "DatabaseSchemaQuery" },
+        name: "deepagents_text2sql_schema"
+      })
+    );
+    const entities = Object.entries(response.tables).filter(
+      ([name, table2]) => (this.#config.includeSystem || table2.type !== "system") && matchesFilter2(name, this.#config.filter)
+    );
+    const tables = [];
+    const views = [];
+    for (const [index2, [name, table2]] of entities.entries()) {
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "tables",
+        table: name,
+        message: `Loading PostHog schema entity ${name}...`,
+        current: index2 + 1,
+        total: entities.length
+      });
+      const columns = readColumns(name, table2);
+      if (VIEW_TYPES.has(table2.type)) {
+        views.push(
+          applyColumnFilter(
+            {
+              name,
+              columns,
+              ...table2.query?.query ? { definition: table2.query.query } : {}
+            },
+            this.#config.columns
+          )
+        );
+      } else {
+        tables.push(
+          applyColumnFilter(
+            {
+              name,
+              columns,
+              ...typeof table2.row_count === "number" ? { rowCount: table2.row_count } : {}
+            },
+            this.#config.columns
+          )
+        );
+      }
+    }
+    ctx.tables.push(...tables);
+    ctx.views.push(...views);
+    ctx.relationships.push(...readRelationships(response.joins, tables, views));
+  }
+  async contributeEntities(ctx) {
+    await this.execute(ctx);
+  }
+};
+function validateSchemaResponse(value) {
+  if (!isRecord4(value) || !isRecord4(value.tables) || !Array.isArray(value.joins)) {
+    throw new Error(
+      "PostHog DatabaseSchemaQuery response must contain tables and joins."
+    );
+  }
+  for (const [name, valueTable] of Object.entries(value.tables)) {
+    if (!isRecord4(valueTable)) {
+      throw new Error(`PostHog schema table ${name} must be an object.`);
+    }
+    if (!TABLE_TYPES.has(valueTable.type)) {
+      throw new Error(`PostHog schema table ${name} has an unknown type.`);
+    }
+    if (typeof valueTable.id !== "string" || typeof valueTable.name !== "string" || !isRecord4(valueTable.fields)) {
+      throw new Error(`PostHog schema table ${name} is malformed.`);
+    }
+    if (valueTable.row_count !== void 0 && valueTable.row_count !== null && (typeof valueTable.row_count !== "number" || !Number.isFinite(valueTable.row_count) || valueTable.row_count < 0)) {
+      throw new Error(`PostHog schema table ${name} has an invalid row_count.`);
+    }
+    if (VIEW_TYPES.has(valueTable.type) && (!isRecord4(valueTable.query) || typeof valueTable.query.query !== "string")) {
+      throw new Error(`PostHog schema view ${name} has an invalid query.`);
+    }
+    validateFields(name, valueTable.fields);
+  }
+  for (const join of value.joins) {
+    if (!isRecord4(join)) {
+      throw new Error("PostHog schema contains a malformed join.");
+    }
+  }
+  return value;
+}
+function validateFields(tableName, fields) {
+  for (const [name, value] of Object.entries(fields)) {
+    if (!isRecord4(value) || typeof value.name !== "string" || typeof value.hogql_value !== "string" || typeof value.schema_valid !== "boolean" || !FIELD_TYPES.has(value.type)) {
+      throw new Error(
+        `PostHog schema field ${tableName}.${name} is malformed or has an unknown type.`
+      );
+    }
+  }
+}
+function readColumns(tableName, table2) {
+  const columns = [];
+  const names = /* @__PURE__ */ new Set();
+  for (const field of Object.values(table2.fields)) {
+    if (!field.schema_valid || !SCALAR_FIELD_TYPES.has(field.type)) continue;
+    const name = field.hogql_value.trim();
+    if (!name) {
+      throw new Error(`PostHog schema table ${tableName} has an empty field.`);
+    }
+    if (names.has(name)) {
+      throw new Error(
+        `PostHog schema table ${tableName} has duplicate HogQL field ${name}.`
+      );
+    }
+    names.add(name);
+    columns.push({ name, type: field.type });
+  }
+  return columns;
+}
+function readRelationships(joins, tables, views) {
+  const entityColumns = new Map(
+    [...tables, ...views].map((entity) => [
+      entity.name,
+      new Set(entity.columns.map((column2) => column2.name))
+    ])
+  );
+  return joins.flatMap((join) => {
+    const sourceTable = readNonEmptyString2(join.source_table_name);
+    const sourceKey = readNonEmptyString2(join.source_table_key);
+    const joiningTable = readNonEmptyString2(join.joining_table_name);
+    const joiningKey = readNonEmptyString2(join.joining_table_key);
+    if (!sourceTable || !sourceKey || !joiningTable || !joiningKey || !entityColumns.get(sourceTable)?.has(sourceKey) || !entityColumns.get(joiningTable)?.has(joiningKey)) {
+      return [];
+    }
+    return [
+      {
+        table: sourceTable,
+        from: [sourceKey],
+        referenced_table: joiningTable,
+        to: [joiningKey]
+      }
+    ];
+  });
+}
+function matchesFilter2(name, filter) {
+  if (!filter) return true;
+  if (Array.isArray(filter)) return filter.includes(name);
+  if (filter instanceof RegExp) {
+    filter.lastIndex = 0;
+    return filter.test(name);
+  }
+  return filter(name);
+}
+function readNonEmptyString2(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/text2sql/src/lib/adapters/posthog/transport.ts
+var DEFAULT_TIMEOUT_MS = 45e3;
+var PAGE_SIZE = 100;
+var PostHogApiError = class extends Error {
+  status;
+  code;
+  detail;
+  retryAfterMs;
+  constructor(options) {
+    super(options.message);
+    this.name = "PostHogApiError";
+    this.status = options.status;
+    this.code = options.code;
+    this.detail = options.detail;
+    this.retryAfterMs = options.retryAfterMs;
+  }
+};
+function createPostHogTransport(options) {
+  const origin = parseOrigin(options.host);
+  const projectId = String(options.projectId ?? "").trim();
+  if (!projectId) throw new Error("PostHog transport requires a projectId.");
+  if (typeof options.getAccessToken !== "function") {
+    throw new Error("PostHog transport requires getAccessToken().");
+  }
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("PostHog transport requires a fetch implementation.");
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("PostHog transport timeoutMs must be a positive integer.");
+  }
+  const projectPath = `/api/projects/${encodeURIComponent(projectId)}`;
+  const requestJson = async (path, init = {}) => {
+    const token = String(await options.getAccessToken()).trim();
+    if (!token) throw new Error("PostHog getAccessToken() returned no token.");
+    const signal = AbortSignal.timeout(timeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(new URL(path, origin), {
+        ...init,
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${token}`,
+          ...init.body === void 0 ? {} : { "Content-Type": "application/json" }
+        },
+        redirect: "error",
+        signal
+      });
+    } catch {
+      if (signal.aborted) {
+        throw new Error(`PostHog request timed out after ${timeoutMs}ms.`);
+      }
+      throw new Error("PostHog request failed before receiving a response.");
+    }
+    let body;
+    try {
+      body = await response.text();
+    } catch {
+      if (signal.aborted) {
+        throw new Error(`PostHog request timed out after ${timeoutMs}ms.`);
+      }
+      throw new Error("PostHog response body could not be read.");
+    }
+    const parsed = parseJson(body);
+    if (!response.ok) {
+      throw apiError(response, parsed, token);
+    }
+    if (parsed === void 0) {
+      throw new Error("PostHog returned an empty or non-JSON response.");
+    }
+    return parsed;
+  };
+  const listDefinitions = async (resource, parameters) => {
+    const definitions2 = [];
+    let offset = 0;
+    for (; ; ) {
+      const pageParameters = new URLSearchParams(parameters);
+      pageParameters.set("limit", String(PAGE_SIZE));
+      pageParameters.set("offset", String(offset));
+      const page = asRecord(
+        await requestJson(
+          `${projectPath}/${resource}/?${pageParameters.toString()}`
+        ),
+        `PostHog ${resource} response`
+      );
+      if (!Array.isArray(page.results)) {
+        throw new Error(`PostHog ${resource} response has no results array.`);
+      }
+      if (page.next !== null && typeof page.next !== "string") {
+        throw new Error(
+          `PostHog ${resource} response has an invalid next page.`
+        );
+      }
+      definitions2.push(...page.results);
+      if (page.next === null) return definitions2;
+      if (page.results.length === 0) {
+        throw new Error(
+          `PostHog ${resource} returned an empty non-final page.`
+        );
+      }
+      offset += page.results.length;
+    }
+  };
+  return {
+    async query(request) {
+      return await requestJson(`${projectPath}/query/`, {
+        method: "POST",
+        body: JSON.stringify(request)
+      });
+    },
+    listEventDefinitions() {
+      return listDefinitions(
+        "event_definitions",
+        new URLSearchParams({
+          exclude_hidden: "true",
+          exclude_stale: "true"
+        })
+      );
+    },
+    listPropertyDefinitions({
+      type,
+      groupTypeIndex
+    }) {
+      if (type === "group" && (groupTypeIndex === void 0 || !Number.isInteger(groupTypeIndex) || groupTypeIndex < 0)) {
+        throw new Error(
+          "PostHog group property definitions require a non-negative integer groupTypeIndex."
+        );
+      }
+      const parameters = new URLSearchParams({
+        type,
+        exclude_hidden: "true",
+        exclude_restricted: "true"
+      });
+      if (type === "group") {
+        parameters.set("group_type_index", String(groupTypeIndex));
+      }
+      return listDefinitions("property_definitions", parameters);
+    }
+  };
+}
+function parseOrigin(host) {
+  let url;
+  try {
+    url = new URL(host);
+  } catch {
+    throw new Error("PostHog host must be an absolute URL.");
+  }
+  const isLoopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+    throw new Error(
+      "PostHog host must use HTTPS except for loopback development hosts."
+    );
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error(
+      "PostHog host must be an origin without credentials or query data."
+    );
+  }
+  if (url.pathname !== "/" && url.pathname !== "") {
+    throw new Error("PostHog host must not include a path.");
+  }
+  url.pathname = "/";
+  return url;
+}
+function parseJson(body) {
+  if (!body.trim()) return void 0;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+function apiError(response, body, accessToken) {
+  const record = isRecord5(body) ? body : void 0;
+  const detail = redact(
+    readString(record?.detail) ?? readString(record?.error),
+    accessToken
+  );
+  const code = redact(readString(record?.code), accessToken);
+  const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+  return new PostHogApiError({
+    status: response.status,
+    message: detail ? `PostHog API returned ${response.status}: ${detail}` : `PostHog API returned HTTP ${response.status}.`,
+    code,
+    detail,
+    retryAfterMs
+  });
+}
+function parseRetryAfter(value) {
+  if (value === null) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) {
+    return seconds >= 0 ? seconds * 1e3 : void 0;
+  }
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, date - Date.now()) : void 0;
+}
+function asRecord(value, label) {
+  if (!isRecord5(value)) throw new Error(`${label} must be a JSON object.`);
+  return value;
+}
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function redact(value, secret) {
+  return value?.replaceAll(secret, "[REDACTED]");
+}
+
+// packages/text2sql/src/lib/adapters/posthog/index.ts
+function info() {
+  return () => new PostHogInfoGrounding();
+}
+function schema(config = {}) {
+  return (adapter) => new PostHogSchemaGrounding(adapter, config);
+}
+function definitions(config = {}) {
+  return (adapter) => new PostHogDefinitionsGrounding(adapter, config);
+}
+var posthog_default = {
+  PostHog,
+  definitions,
+  info,
+  schema
+};
+export {
+  PostHog,
+  PostHogApiError,
+  PostHogDefinitionsGrounding,
+  PostHogSchemaGrounding,
+  PostHogSqlPolicyAnalyzer,
+  createPostHogTransport,
+  posthog_default as default,
+  definitions,
+  info,
+  schema
+};
+//# sourceMappingURL=index.js.map