@memberjunction/db-auto-doc 5.37.0 → 5.38.0

package/dist/discovery/ColumnNormalizer.js

@@ -0,0 +1,376 @@
+/**
+ * TableNormalizer — one LLM call per TABLE (not per column), upstream of embedding.
+ *
+ * For each in-scope table, a single LLM call sees:
+ *   - The table's name + description + sibling columns
+ *   - Every column's identity + description + sample values + FK/PK status
+ *
+ * The call returns one normalized entry per column with:
+ *   - conceptName            : canonical snake_case (`email_address`, `customer_id`, ...)
+ *   - normalizationStrategy  : how values should be compared
+ *   - normalizedDescription  : business-concept-focused, system-agnostic sentence
+ *   - isUsefulOrganicKey     : false for audit/system/free-form (filtered out)
+ *   - confidence + reasoning
+ *
+ * Why per-table instead of per-column:
+ *   - Fewer calls (5K cols across 500 tables → 500 calls instead of 5K). At
+ *     Gemini Flash pricing, that's ~$0.04 instead of ~$0.20 for APTIFY-scale.
+ *   - System prompt amortizes across all columns in the table.
+ *   - The LLM sees siblings as context — knowing the table has FirstName + LastName
+ *     next to an Email column reveals it's a person email, not a server hostname.
+ *   - More token-efficient: one JSON array out instead of N independent objects.
+ *
+ * The single most important constraint: same-concept columns from DIFFERENT
+ * TABLES (across systems) must produce the same conceptName and a similar
+ * normalizedDescription so the embedding step naturally clusters them. The
+ * prompt enforces this via a canonical concept-name list.
+ */
+import { createLLMInstance } from '../utils/llm-factory.js';
+import { cleanAndParseJSON } from '../utils/json.js';
+export class TableNormalizer {
+    constructor(aiConfig) {
+        this.aiConfig = aiConfig;
+        this.llm = createLLMInstance(aiConfig.provider, aiConfig.apiKey);
+    }
+    /** Normalize one table — one LLM call returning per-column entries. */
+    async normalizeTable(input, maxRetries = 2) {
+        if (input.columns.length === 0) {
+            return { normalized: [], tokens: { total: 0, input: 0, output: 0 } };
+        }
+        const userPrompt = buildUserPrompt(input);
+        const params = {
+            model: this.aiConfig.model,
+            messages: [
+                { role: 'system', content: SYSTEM_PROMPT },
+                { role: 'user', content: userPrompt },
+            ],
+            temperature: this.aiConfig.temperature ?? 0,
+            maxOutputTokens: this.aiConfig.maxTokens,
+            responseFormat: 'JSON',
+        };
+        let lastError = '';
+        let cumTokens = { total: 0, input: 0, output: 0 };
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            let result;
+            try {
+                result = await this.llm.ChatCompletion(params);
+            }
+            catch (err) {
+                lastError = `LLM call threw: ${err.message}`;
+                continue;
+            }
+            if (!result.success) {
+                lastError = `LLM call failed: ${result.errorMessage ?? 'unknown'}`;
+                continue;
+            }
+            const content = result.data?.choices?.[0]?.message?.content ?? '';
+            const usage = result.data?.usage;
+            cumTokens = {
+                total: cumTokens.total + (usage?.totalTokens ?? 0),
+                input: cumTokens.input + (usage?.promptTokens ?? 0),
+                output: cumTokens.output + (usage?.completionTokens ?? 0),
+            };
+            let parsed = null;
+            try {
+                parsed = cleanAndParseJSON(content);
+            }
+            catch (err) {
+                lastError = `JSON parse threw: ${err.message}. Content prefix: ${content.slice(0, 200)}`;
+                if (attempt < maxRetries)
+                    continue;
+                return { normalized: [], tokens: cumTokens, errorMessage: lastError };
+            }
+            if (!parsed || !Array.isArray(parsed.columns)) {
+                lastError = `JSON parse returned bad shape. Content prefix: ${content.slice(0, 200)}`;
+                if (attempt < maxRetries)
+                    continue;
+                return { normalized: [], tokens: cumTokens, errorMessage: lastError };
+            }
+            // Match the LLM's response entries back to input columns by name.
+            const byName = new Map(input.columns.map((c) => [c.column.toLowerCase(), c]));
+            const normalized = [];
+            for (const entry of parsed.columns) {
+                if (!entry || typeof entry.column !== 'string')
+                    continue;
+                const inputCol = byName.get(entry.column.toLowerCase());
+                if (!inputCol)
+                    continue; // LLM hallucinated a column name; skip
+                normalized.push({
+                    ...inputCol,
+                    conceptName: entry.conceptName ?? '',
+                    normalizationStrategy: entry.normalizationStrategy ?? 'LowerCaseTrim',
+                    customNormalizationExpression: sanitizePlaceholder(entry.customNormalizationExpression),
+                    normalizedDescription: entry.normalizedDescription ?? '',
+                    isUsefulOrganicKey: !!entry.isUsefulOrganicKey,
+                    confidence: clamp01(entry.confidence),
+                    reasoning: entry.reasoning ?? '',
+                });
+            }
+            return { normalized, tokens: cumTokens };
+        }
+        return { normalized: [], tokens: cumTokens, errorMessage: lastError || 'unknown failure after retries' };
+    }
+    /** Batch normalize many tables with bounded concurrency. */
+    async normalizeAll(tables, opts = {}) {
+        const concurrency = Math.max(1, opts.concurrency ?? 8);
+        const maxRetries = Math.max(0, opts.maxRetries ?? 2);
+        const allNormalized = [];
+        let rejected = 0;
+        let errors = 0;
+        let total = 0;
+        let input = 0;
+        let output = 0;
+        let completed = 0;
+        let cursor = 0;
+        const runners = Array.from({ length: concurrency }, async () => {
+            while (true) {
+                const idx = cursor++;
+                if (idx >= tables.length)
+                    return;
+                const r = await this.normalizeTable(tables[idx], maxRetries);
+                total += r.tokens.total;
+                input += r.tokens.input;
+                output += r.tokens.output;
+                if (r.errorMessage) {
+                    errors++;
+                }
+                else {
+                    for (const n of r.normalized) {
+                        if (n.isUsefulOrganicKey)
+                            allNormalized.push(n);
+                        else
+                            rejected++;
+                    }
+                }
+                completed++;
+                opts.onProgress?.(completed, tables.length);
+            }
+        });
+        await Promise.all(runners);
+        return { normalized: allNormalized, rejected, errors, tokens: { total, input, output } };
+    }
+}
+// ─── Prompt ─────────────────────────────────────────────────────────────────
+const SYSTEM_PROMPT = `You are translating database columns into a NORMALIZED BUSINESS-CONCEPT REPRESENTATION
+for organic-key detection per MemberJunction PR #2193.
+
+═══ PR #2193 — WHAT AN ORGANIC KEY IS ═══
+
+An organic key is a column whose value can be used to MATCH two rows that
+refer to the SAME real-world entity, WITHOUT going through a declared foreign
+key. PR #2193 lets the framework "join by value" wherever the schema lacks an
+explicit FK link (cross-system data, late-bound integrations, denormalized
+warehouses, partial schemas).
+
+KEEP a column as an organic-key candidate when this test passes:
+
+  "If I take two rows that have the same value in this column, do they
+   refer to the SAME real-world entity (the same customer, the same person,
+   the same order, the same product, the same location, the same legal
+   entity, the same communication endpoint)?"
+
+This test is SATISFIED by:
+  - Customer / member / employee / person / company / product / order IDs —
+    natural OR surrogate. Within a database an EmployeeID of 42 in one table
+    DOES refer to the same employee as EmployeeID 42 in another table. That
+    is the WHOLE POINT of PR #2193 — these are the matches it makes navigable.
+  - Email addresses, phone numbers, fax numbers, URLs.
+  - Tax IDs, social security numbers, account numbers, license numbers.
+  - ISBNs, SKUs, product codes, part numbers.
+  - Postal codes, street addresses, geocodes (they identify a delivery point
+    or location entity).
+  - Full names, first names, last names, organization names — identifiers of
+    persons or organizations even when fuzzy.
+
+FK columns are EXPLICITLY ALLOWED. PR #2193 organic keys often overlap with
+FK columns by design — the same EmployeeID that's a declared FK in one table
+is the organic match key for tables where the FK isn't declared. Do not
+disqualify a column just because it participates in a FK.
+
+REJECT (isUsefulOrganicKey=false) ONLY in these cases:
+
+  - Categorical / enum-like values with a small fixed vocabulary (status =
+    'Active'/'Pending'/'Closed'; type = 'A'/'B'/'C'; region code = 'NA'/'EMEA';
+    country code = 'US'/'UK'/'FR'). Two rows sharing status='Active' do NOT
+    refer to the same real-world entity — they're just both active.
+
+  - Booleans / flags (IsActive, HasDiscount).
+
+  - Measurements, quantities, prices, percentages, aggregates (price, qty,
+    discount, count, score, weight).
+
+  - Audit metadata (created_at, modified_by, version, row_version, rowguid,
+    last_login_at).
+
+  - Free-form descriptive text (notes, comments, description paragraphs,
+    long-text fields).
+
+  - System paths / blob references (photo_path, file_url, attachment_uri)
+    when they're pointers to assets rather than the asset's identity.
+
+DO NOT REJECT a column just because:
+  - It is auto-increment (auto-increment IDs are still valid organic keys
+    across tables in the same system).
+  - It is a foreign key (FKs are valid organic keys, see above).
+  - It "identifies a location, not the parent row's entity" (a postal code
+    DOES identify a delivery location entity, which is a valid organic-key
+    use; clustering will decide whether it's useful).
+  - Names "could collide" (low uniqueness lowers confidence but does NOT
+    disqualify — names are valid organic-key candidates per PR #2193).
+
+═══ YOUR TASK ═══
+
+For each column you receive, produce a JSON object with these fields. Look at
+the sibling columns and the table's purpose for context — they often clarify
+whether a value identifies or categorizes.
+
+1. normalizedDescription — A STRUCTURED BUSINESS-FOCUSED SENTENCE that any
+   reader (or embedding model) can use to recognize this kind of value. Use
+   this exact structural template:
+
+     "<value-kind> identifying <entity-kind>; <normalization rule>."
+
+   Example shapes:
+     "RFC-5322 email address identifying a natural person; case-insensitive
+      whitespace-trimmed equality."
+     "E.164 phone number identifying a person or organization; digits-only
+      equality after stripping formatting."
+     "Customer identifier (auto-increment or business code) identifying a
+      customer entity across tables; exact equality after trimming."
+     "Employee identifier identifying an employee across HR tables; exact
+      equality."
+     "Postal / ZIP code identifying a delivery area; exact equality after
+      trimming."
+     "Family name (last name) identifying a natural person; case-insensitive
+      whitespace-trimmed equality."
+
+   For REJECTED columns, the template flips:
+     "ISO-3166 country code (categorical, 250 buckets); not an entity
+      identifier; not applicable."
+     "Order line quantity (measurement); not an entity identifier; not
+      applicable."
+     "Modification timestamp (audit metadata); not applicable."
+
+   Same-concept columns from different tables MUST produce highly similar
+   normalizedDescription strings so they cluster geometrically. Generic prose
+   ("a code", "an identifier") is NOT acceptable — name the value kind
+   (email address, phone number, customer id, postal code, family name, etc.)
+   and the entity kind explicitly.
+
+2. conceptName — A canonical snake_case label for this value kind
+   (e.g. "email_address", "phone_number", "postal_code", "customer_id",
+   "employee_id", "person_family_name"). Use the same name for the same
+   concept across tables. Used as a cluster label hint downstream.
+
+3. normalizationStrategy — How equality should be tested at match time:
+     "LowerCaseTrim"  (default for case-insensitive text)
+     "Trim"           (whitespace only)
+     "ExactMatch"     (codes, IDs that are case-sensitive)
+     "Custom"         (provide customNormalizationExpression — a SQL expression
+                      that MUST use the literal placeholder {{FieldName}} where the
+                      column reference goes, e.g.
+                      REPLACE(REPLACE({{FieldName}}, '-', ''), ' ', ''). Do NOT use
+                      'value', 'x', or a column name — only {{FieldName}}.)
+
+4. isUsefulOrganicKey — Apply the test at the top of the prompt:
+   "If I take two rows with the same value in this column, do they refer to
+   the SAME real-world entity?" True for IDs, emails, phones, names,
+   addresses, codes that are entity-level. False ONLY for categorical
+   enums, booleans, measurements, audit metadata, free-form text, and
+   asset paths.
+
+5. confidence — 0.0 to 1.0. Reflect uncertainty honestly; sample values that
+   contradict the column name should lower confidence even if you commit to
+   a judgment.
+
+6. reasoning — One short sentence stating why this kind of value satisfies
+   or fails the test in field 4.
+
+Sample values are the strongest signal. If the column is named "Status" but
+samples are all distinct uuid-like tokens, trust the data over the name.
+
+Output STRICT JSON only, no markdown fences:
+{
+  "columns": [
+    {
+      "column": "<exact column name from input>",
+      "conceptName": "snake_case_name",
+      "normalizationStrategy": "LowerCaseTrim" | "Trim" | "ExactMatch" | "Custom",
+      "customNormalizationExpression": "...",
+      "normalizedDescription": "<structured sentence per template above>",
+      "isUsefulOrganicKey": true,
+      "confidence": 0.95,
+      "reasoning": "One short sentence."
+    }
+  ]
+}
+
+Include EVERY column from the input, in the same order. Match the "column" field
+exactly to the input column name.`;
+/**
+ * Normalize whatever column placeholder the LLM used in a Custom expression to the
+ * canonical {{FieldName}} token that CodeGen + the PR #2193 runtime substitute. The
+ * prompt asks for {{FieldName}}, but models frequently emit `value`, `x`, `col`, or
+ * `column` instead — this guards against the resulting silent runtime breakage where
+ * the literal placeholder would survive into the executed SQL.
+ */
+function sanitizePlaceholder(expr) {
+    if (!expr)
+        return expr;
+    let out = expr;
+    // Already correct — leave alone.
+    if (/\{\{\s*FieldName\s*\}\}/.test(out)) {
+        return out.replace(/\{\{\s*FieldName\s*\}\}/g, '{{FieldName}}');
+    }
+    // Replace common standalone placeholder identifiers (word-boundary, not inside quotes).
+    // Order matters: longer tokens first.
+    for (const token of ['column', 'value', 'col', 'x']) {
+        const re = new RegExp(`\\b${token}\\b`, 'g');
+        if (re.test(out)) {
+            out = out.replace(re, '{{FieldName}}');
+            break; // only the first matching convention is the placeholder
+        }
+    }
+    return out;
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function buildUserPrompt(input) {
+    const lines = [];
+    lines.push(`Table: ${input.schema}.${input.table}`);
+    if (input.schemaDescription)
+        lines.push(`Schema purpose: ${truncate(input.schemaDescription, 240)}`);
+    if (input.tableDescription)
+        lines.push(`Table purpose:  ${truncate(input.tableDescription, 240)}`);
+    lines.push('');
+    lines.push(`Columns (${input.columns.length}):`);
+    for (const c of input.columns) {
+        lines.push(`  - ${c.column}  [${c.dataType}]${c.isPrimaryKey ? '  PK' : ''}${c.participatesInFK ? `  FK${c.fkTarget ? `→${c.fkTarget.schema}.${c.fkTarget.table}.${c.fkTarget.column}` : ''}` : ''}`);
+        if (c.originalDescription)
+            lines.push(`      description: ${truncate(c.originalDescription, 240)}`);
+        if (c.sampleValues && c.sampleValues.length > 0) {
+            const samples = c.sampleValues
+                .slice(0, 5)
+                .map((v) => JSON.stringify(truncate(String(v), 80)))
+                .join(', ');
+            lines.push(`      samples: [${samples}]`);
+        }
+    }
+    lines.push('');
+    lines.push('Output the normalized JSON per the system prompt — one entry per column, in order.');
+    return lines.join('\n');
+}
+function clamp01(x) {
+    if (!Number.isFinite(x))
+        return 0;
+    if (x < 0)
+        return 0;
+    if (x > 1)
+        return 1;
+    return x;
+}
+function truncate(s, n) {
+    if (!s)
+        return '';
+    return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+//# sourceMappingURL=ColumnNormalizer.js.map

package/dist/discovery/ColumnNormalizer.js.map

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

package/dist/discovery/Composer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Composer — flag-and-emit (no destructive filtering).
+ *
+ * Computes `isFKRedundant` for each cluster (PR #2193 organic keys are meant
+ * to be used "in place of a foreign-key reference" — when every non-PK member
+ * is a declared FK pointing to the PK member, the cluster adds no new
+ * navigation). Sets the flag on the cluster but does NOT drop — well-modeled
+ * OLTP schemas would lose 30-50% of valid organic-key candidates if we
+ * dropped, and the discovery value (cross-system extension, naming
+ * consistency checks) survives the redundancy.
+ *
+ * The dashboard surfaces a "hide FK-redundant" filter so users get the lookup-
+ * table-PK noise out of view without losing the underlying candidates.
+ */
+import { OrganicKeyCluster, OrganicKeyClusterMember } from '../types/organic-keys.js';
+import { DetectedOrganicKeysOutput } from './OrganicKeyTranslator.js';
+import { TransitiveBridgeFinding } from './TransitiveBridgeDetector.js';
+/** Output of the compose step: the PR #2193 JSON, the FK-redundancy-annotated clusters, and emit counts. */
+export interface ComposerResult {
+    output: DetectedOrganicKeysOutput;
+    /** Clusters with isFKRedundant filled in — callers that persist the cluster list
+     *  (e.g. detector → state.json → dashboard) should use THIS, not the pre-compose
+     *  input, otherwise the flag is silently lost. */
+    annotatedClusters: OrganicKeyCluster[];
+    emitted: number;
+    flaggedFKRedundant: number;
+    summary: {
+        outputSchemas: number;
+        outputTables: number;
+        outputKeys: number;
+        outputSpokes: number;
+    };
+}
+/**
+ * Compose detected clusters + transitive bridges into the PR #2193 emit JSON.
+ *
+ * Each cluster is annotated with `isFKRedundant` (true when it's already navigable via a
+ * declared foreign key — kept but flagged, not dropped). Matching transitive bridges are
+ * attached as spokes. Returns the JSON plus the annotated clusters and emit counts.
+ */
+export declare function compose(clusters: OrganicKeyCluster[], bridges: TransitiveBridgeFinding[]): ComposerResult;
+/**
+ * A cluster is FK-redundant when ALL non-PK members are declared FKs pointing
+ * at the same target column (typically the PK member of the cluster). PR #2193
+ * organic keys are "used in place of a foreign-key reference" — if the FK is
+ * already declared, the cluster doesn't add navigability.
+ *
+ * Requires at least one PK and at least one FK in the cluster to apply.
+ * Returns false for clusters that are entirely PKs, entirely non-FKs, or that
+ * have mixed FK targets (the latter is a genuine value-based correlation that
+ * no single FK covers).
+ */
+declare function isFKRedundant(cluster: OrganicKeyCluster): boolean;
+/** Re-export for tests / observability. */
+export declare const __test__: {
+    isFKRedundant: typeof isFKRedundant;
+};
+export type { OrganicKeyClusterMember };
+//# sourceMappingURL=Composer.d.ts.map

package/dist/discovery/Composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Composer.d.ts","sourceRoot":"","sources":["../../src/discovery/Composer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACtF,OAAO,EACH,yBAAyB,EAI5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAExE,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,yBAAyB,CAAC;IAClC;;sDAEkD;IAClD,iBAAiB,EAAE,iBAAiB,EAAE,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CACtG;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CACnB,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,EAAE,uBAAuB,EAAE,GACnC,cAAc,CA0ChB;AAED;;;;;;;;;;GAUG;AACH,iBAAS,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAiB1D;AAED,2CAA2C;AAC3C,eAAO,MAAM,QAAQ;;CAAoB,CAAC;AAC1C,YAAY,EAAE,uBAAuB,EAAE,CAAC"}

package/dist/discovery/Composer.js

@@ -0,0 +1,95 @@
+/**
+ * Composer — flag-and-emit (no destructive filtering).
+ *
+ * Computes `isFKRedundant` for each cluster (PR #2193 organic keys are meant
+ * to be used "in place of a foreign-key reference" — when every non-PK member
+ * is a declared FK pointing to the PK member, the cluster adds no new
+ * navigation). Sets the flag on the cluster but does NOT drop — well-modeled
+ * OLTP schemas would lose 30-50% of valid organic-key candidates if we
+ * dropped, and the discovery value (cross-system extension, naming
+ * consistency checks) survives the redundancy.
+ *
+ * The dashboard surfaces a "hide FK-redundant" filter so users get the lookup-
+ * table-PK noise out of view without losing the underlying candidates.
+ */
+import { translateClusters, countOutputEntries, } from './OrganicKeyTranslator.js';
+/**
+ * Compose detected clusters + transitive bridges into the PR #2193 emit JSON.
+ *
+ * Each cluster is annotated with `isFKRedundant` (true when it's already navigable via a
+ * declared foreign key — kept but flagged, not dropped). Matching transitive bridges are
+ * attached as spokes. Returns the JSON plus the annotated clusters and emit counts.
+ */
+export function compose(clusters, bridges) {
+    let flaggedCount = 0;
+    const annotated = clusters.map((c) => {
+        const redundant = isFKRedundant(c);
+        if (redundant)
+            flaggedCount += 1;
+        return { ...c, isFKRedundant: redundant };
+    });
+    const hubKeys = new Set();
+    for (const c of annotated) {
+        for (const m of c.members)
+            hubKeys.add(`${m.schema}.${m.table}.${m.column}`);
+    }
+    const spokes = bridges
+        .filter((b) => hubKeys.has(`${b.hubSchema}.${b.hubTable}.${b.hubKeyFields[0]}`))
+        .map((b) => ({
+        hubSchema: b.hubSchema,
+        hubTable: b.hubTable,
+        hubKeyFields: b.hubKeyFields,
+        spokeSchema: b.spokeSchema,
+        spokeTable: b.spokeTable,
+        transitiveView: { Name: b.view.viewName, SchemaName: b.view.schemaName, SQL: b.view.sql },
+        transitiveMatchFieldNames: [b.view.hubKeyField],
+        transitiveOutputFieldName: b.view.spokeOutputField,
+        relatedEntityJoinFieldName: b.view.spokeJoinField,
+        hubConcept: b.hubConcept,
+    }));
+    const output = translateClusters(annotated, spokes);
+    const counts = countOutputEntries(output);
+    return {
+        output,
+        annotatedClusters: annotated,
+        emitted: annotated.length,
+        flaggedFKRedundant: flaggedCount,
+        summary: {
+            outputSchemas: counts.schemas,
+            outputTables: counts.tables,
+            outputKeys: counts.keys,
+            outputSpokes: counts.spokes,
+        },
+    };
+}
+/**
+ * A cluster is FK-redundant when ALL non-PK members are declared FKs pointing
+ * at the same target column (typically the PK member of the cluster). PR #2193
+ * organic keys are "used in place of a foreign-key reference" — if the FK is
+ * already declared, the cluster doesn't add navigability.
+ *
+ * Requires at least one PK and at least one FK in the cluster to apply.
+ * Returns false for clusters that are entirely PKs, entirely non-FKs, or that
+ * have mixed FK targets (the latter is a genuine value-based correlation that
+ * no single FK covers).
+ */
+function isFKRedundant(cluster) {
+    const pkMembers = cluster.members.filter((m) => m.isPrimaryKey);
+    const nonPK = cluster.members.filter((m) => !m.isPrimaryKey);
+    if (pkMembers.length === 0 || nonPK.length === 0)
+        return false;
+    // Build the set of plausible "target" identifiers from the PK members.
+    const pkTargets = new Set(pkMembers.map((m) => `${m.schema}.${m.table}.${m.column}`.toLowerCase()));
+    // Every non-PK member must be a FK pointing into one of the PK targets.
+    for (const m of nonPK) {
+        if (!m.participatesInFK || !m.fkTarget)
+            return false;
+        const key = `${m.fkTarget.schema}.${m.fkTarget.table}.${m.fkTarget.column}`.toLowerCase();
+        if (!pkTargets.has(key))
+            return false;
+    }
+    return true;
+}
+/** Re-export for tests / observability. */
+export const __test__ = { isFKRedundant };
+//# sourceMappingURL=Composer.js.map

package/dist/discovery/Composer.js.map

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

package/dist/discovery/EmbeddingProvider.d.ts

@@ -0,0 +1,27 @@
+/**
+ * EmbeddingProvider — thin wrapper over MemberJunction's `BaseEmbeddings` infrastructure.
+ *
+ * Embeddings are produced through the same MJ ClassFactory + driver pattern that
+ * `llm-factory` uses for LLMs (so DBAutoDoc stays coupled to MJ's AI stack rather
+ * than talking to provider REST endpoints directly). The concrete driver class is
+ * resolved from the provider name and instantiated with the supplied API key.
+ *
+ * Vectors are unit-normalized so the clustering step can use cosine distance
+ * directly regardless of whether the underlying model returns normalized output.
+ */
+/** Provider names that map to a registered `BaseEmbeddings` driver class. */
+export type EmbeddingProviderName = 'openai' | 'mistral' | 'azure' | 'bedrock' | 'ollama' | 'local';
+export interface EmbeddingProviderConfig {
+    provider: EmbeddingProviderName;
+    apiKey: string;
+    model?: string;
+    dimensions?: number;
+    batchSize?: number;
+    endpoint?: string;
+}
+export interface EmbeddingProvider {
+    readonly provider: EmbeddingProviderName;
+    embed(texts: string[]): Promise<Float32Array[]>;
+}
+export declare function createEmbeddingProvider(config: EmbeddingProviderConfig): EmbeddingProvider;
+//# sourceMappingURL=EmbeddingProvider.d.ts.map

package/dist/discovery/EmbeddingProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingProvider.d.ts","sourceRoot":"","sources":["../../src/discovery/EmbeddingProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,6EAA6E;AAC7E,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpG,MAAM,WAAW,uBAAuB;IACpC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACnD;AAyBD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,uBAAuB,GAAG,iBAAiB,CAO1F"}