@adminiumjs/llm 0.1.0-rc.1

package/dist/apply/normalize.js

@@ -0,0 +1,232 @@
+/** §7.1: "heuristic entries use fixed 0.5." Shared with the diff engine. */
+export const HEURISTIC_CONFIDENCE = 0.5;
+/**
+ * Reduce a validated `LlmResponseV1` to the normalized `EnrichmentSet` (§7.1).
+ *
+ * `tables` is keyed by `"schema.table"`, `enums` by `"schema.table.column"`.
+ * Confirmed relations that AFFIRM a declared FK (`correct: true`) re-state an
+ * existing relation and are handled at apply time (§8.3), not in the refinement
+ * diff. Confirmed relations the model REJECTS (`correct: false`) are a different
+ * matter: §8.2 lists them as `rejects-heuristic` rows a human must confirm and
+ * "Accept all ≥ 0.8" must never auto-select, so they are lifted into
+ * `suppressedRelations` for the diff to surface (finding: without this a
+ * `correct: false` suppression produced no diff row at all and bypassed the
+ * human-confirm gate).
+ */
+export function normalizeLlmResponse(response, opts = {}) {
+    const tables = {};
+    for (const t of response.tables) {
+        const columns = {};
+        for (const c of t.columns) {
+            const column = { label: c.label, pii: c.pii };
+            if (c.description !== undefined)
+                column.description = c.description;
+            columns[c.column] = column;
+        }
+        const table = {
+            label: t.label,
+            description: t.description,
+            icon: t.icon,
+            displayColumn: t.displayColumn,
+            naturalKey: t.naturalKey,
+            templates: t.pageTemplates.map((p) => ({
+                template: p.template,
+                rank: p.rank,
+                reason: p.reason,
+                confidence: p.confidence,
+            })),
+            columns,
+            confidence: t.confidence,
+        };
+        if (t.microcopy !== undefined)
+            table.microcopy = t.microcopy;
+        tables[t.table] = table;
+    }
+    const enums = {};
+    for (const e of response.enums) {
+        enums[`${e.table}.${e.column}`] = e;
+    }
+    const set = {
+        source: 'llm',
+        tables,
+        enums,
+        inferredRelations: response.relations.inferred,
+        suppressedRelations: response.relations.confirmed.filter((r) => !r.correct),
+        navGroups: response.navGroups,
+        dashboards: response.dashboards,
+    };
+    const runId = opts.llmRunId ?? response.run_id;
+    if (runId !== undefined)
+        set.llmRunId = runId;
+    return set;
+}
+// ─── Heuristic classified model → EnrichmentSet ──────────────────────────────
+/**
+ * Reduce the engine's heuristic classification to the same `EnrichmentSet`
+ * shape (§7.1). Consumes both the classifier output (`ClassifiedModel` — shape,
+ * display/natural key, per-column semantics + PII flags) and the source
+ * `DatabaseModel` (identifier names for humanization, declared enum values,
+ * inferred relations). Emitting only pure-Zod/pure-TS engine data keeps the
+ * heuristic→EnrichmentSet mapping inside `@adminium/llm` with no engine→llm edge.
+ */
+export function normalizeHeuristicBaseline(model, classified) {
+    const columnsByTable = new Map(model.tables.map((t) => [t.id, new Map(t.columns.map((c) => [c.name, c]))]));
+    const enumValuesById = new Map(model.enums.map((e) => [e.id, e.values]));
+    const tables = {};
+    const enums = {};
+    for (const ct of classified.tables) {
+        const modelColumns = columnsByTable.get(ct.tableId);
+        const columns = {};
+        for (const cc of ct.columns) {
+            columns[cc.column] = {
+                label: { en_US: humanize(cc.column) },
+                pii: heuristicPii(cc.semantics.flags.pii, cc.semantics.confidence),
+            };
+            const kind = cc.semantics.primary === 'status-workflow'
+                ? 'workflow'
+                : cc.semantics.primary === 'category-enum'
+                    ? 'category'
+                    : null;
+            if (kind === null)
+                continue;
+            const enumRef = modelColumns?.get(cc.column)?.enumRef ?? null;
+            const values = enumRef !== null ? enumValuesById.get(enumRef) : undefined;
+            if (values === undefined || values.length === 0)
+                continue;
+            enums[`${ct.tableId}.${cc.column}`] = {
+                table: ct.tableId,
+                column: cc.column,
+                kind,
+                order: [...values],
+                tones: enumTones(values),
+                reason: 'Heuristic enum classification from column semantics and declared values.',
+                confidence: HEURISTIC_CONFIDENCE,
+            };
+        }
+        tables[ct.tableId] = {
+            label: { en_US: humanize(ct.tableId) },
+            icon: SHAPE_ICONS[ct.shape.kind] ?? 'table',
+            displayColumn: ct.displayColumn,
+            naturalKey: ct.naturalKey !== null ? [ct.naturalKey] : null,
+            templates: [],
+            columns,
+            confidence: HEURISTIC_CONFIDENCE,
+        };
+    }
+    const inferredRelations = [];
+    for (const rel of model.relations) {
+        if (rel.kind === 'inferred-name' || rel.kind === 'inferred-join-table') {
+            inferredRelations.push(toInferredRelation(rel));
+        }
+    }
+    return {
+        source: 'heuristic',
+        tables,
+        enums,
+        inferredRelations,
+        suppressedRelations: [],
+        navGroups: [],
+        dashboards: [],
+    };
+}
+// ─── Local mirrors of the two engine heuristics the classifier doesn't persist ─
+/**
+ * Mirror of `@adminium/widgets/generate` `registry/candidates.ts#humanize`
+ * (byte-identical twin of the engine's `generate/util.ts#humanize`):
+ * `order_details` → `Order Details`; `public.orders` → `Orders`. Kept
+ * byte-faithful so the heuristic baseline labels match what the generator
+ * emits.
+ */
+function humanize(name) {
+    const bare = name.includes('.') ? (name.split('.').pop() ?? name) : name;
+    return bare
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+/**
+ * Mirror of `@adminium/widgets/generate` `generate/crud-body.ts#enumTones`
+ * (§7.1 rule-7 tone map), narrowed to the `Tone` union. The generator map
+ * never emits `accent`.
+ */
+const TONE_POS = /^(active|paid|done|completed?|closed|approved|healthy|shipped|delivered)$/i;
+const TONE_WARN = /^(pending|trial|review|in_review|draft|queued|on_hold|paused|open|new)$/i;
+const TONE_DANGER = /^(failed|rejected|churned|overdue|blocked|cancell?ed|error)$/i;
+function enumTones(values) {
+    const tones = {};
+    for (const value of values) {
+        if (TONE_POS.test(value))
+            tones[value] = 'pos';
+        else if (TONE_WARN.test(value))
+            tones[value] = 'warn';
+        else if (TONE_DANGER.test(value))
+            tones[value] = 'danger';
+        else
+            tones[value] = 'muted';
+    }
+    return tones;
+}
+/** Mirror of the generator's nav-icon-per-shape map (09 §2.2 / generate/index.ts). */
+const SHAPE_ICONS = {
+    people: 'users',
+    workflow: 'kanban-square',
+    events: 'calendar',
+    catalog: 'package',
+    log: 'scroll-text',
+    settings: 'settings',
+    geo: 'map',
+    join: 'link',
+    generic: 'table',
+};
+/**
+ * Map the engine's PII kind (§7.2) onto the LLM contract's PII vocabulary (§6.1)
+ * with a sensible default masking, so a heuristic PII flag normalizes into the
+ * same `PiiSuggestion` shape the LLM emits. Masking is a display default; the
+ * diff treats a heuristic flag as "considers this PII" and compares confirm vs
+ * reject, not masking strategy.
+ */
+const PII_KIND_MAP = {
+    email: { kind: 'email', masking: 'mask-email' },
+    phone: { kind: 'phone', masking: 'mask-partial' },
+    ip: { kind: 'ip', masking: 'mask-partial' },
+    'person-name': { kind: 'name', masking: 'mask-partial' },
+    address: { kind: 'address', masking: 'redact' },
+    dob: { kind: 'dob', masking: 'redact' },
+    'gov-id': { kind: 'gov-id', masking: 'last4' },
+    'payment-id': { kind: 'financial', masking: 'last4' },
+    'geo-precise': { kind: 'location', masking: 'redact' },
+};
+function heuristicPii(kind, confidence) {
+    if (kind === null)
+        return null;
+    const mapped = PII_KIND_MAP[kind];
+    return {
+        kind: mapped.kind,
+        masking: mapped.masking,
+        reason: `Heuristic PII flag (${kind}).`,
+        confidence,
+    };
+}
+function toInferredRelation(rel) {
+    const kind = rel.cardinality === 'one-to-one'
+        ? 'one-to-one'
+        : rel.cardinality === 'many-to-many'
+            ? 'many-to-many-via'
+            : 'many-to-one';
+    const inferred = {
+        fromTable: rel.from.tableId,
+        fromColumns: [...rel.from.columns],
+        toTable: rel.to.tableId,
+        toColumns: [...rel.to.columns],
+        kind,
+        evidence: 'Heuristic-inferred relation from the engine classifier.',
+        confidence: rel.confidence,
+    };
+    if (rel.through !== null)
+        inferred.viaTable = rel.through.tableId;
+    return inferred;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/apply/normalize.js.map

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

package/dist/apply/plan.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The PURE apply-planner (06-llm-assist.md §8.3).
+ *
+ * Turns a reviewed {@link SuggestionDiff}[] plus the set of accepted suggestion
+ * ids into an ordered, serializable {@link ApplyPlan} of WRITE DESCRIPTORS — one
+ * per accepted suggestion, each mapped to its §8.3 apply target. A descriptor
+ * names its target table/column/field + value; it is NOT SQL. The server-side
+ * executor (T10b, `apps/server`) turns descriptors into transactional Kysely
+ * writes against `adminium_schema_overrides` / `adminium_pages` and owns
+ * upsert idempotency at write time.
+ *
+ * Browser-safe (01-architecture.md §2.3): this module imports only pure-TS types
+ * from within `@adminium/llm`; it never touches `@adminium/meta` or a DB driver.
+ * Provider network calls happen server-side only — the dashboard imports this
+ * planner purely to preview the write set in the review confirmation modal.
+ *
+ * Provenance (§8.3, user > llm > heuristic) is enforced IN THE PLAN:
+ *  - suggestions whose diff row is `user-locked` (an existing `source: 'user'`
+ *    override) are EXCLUDED — applying an LLM run never touches a user edit;
+ *  - a `rejects-heuristic` acceptance produces the correct SUPPRESSION
+ *    descriptor (`pii` value `null`, or `relation_suppressed`) rather than a
+ *    positive override.
+ *
+ * Idempotency: `buildApplyPlan` is a pure function of `(diff, acceptedIds, opts)`
+ * — no `Date.now` / `Math.random`, `acceptedIds` order is irrelevant (it is
+ * consumed as a set), and the output is emitted in the diff's own stable
+ * (category, id) order — so re-planning the same run yields an identical plan.
+ * Write-time upsert idempotency (no duplicate rows/pages) is T10b's concern.
+ */
+import type { LocaleCode } from '../response/schema.js';
+import type { SuggestionDiff } from './diff.js';
+/**
+ * The `adminium_schema_overrides` fields an accepted suggestion can target. The
+ * table-`label` value bundles `label` + `description` + `icon` together (the
+ * §8.1 accept unit "table label+description+icon bundle", mirroring the meta
+ * `table.label` op which stores the icon inline) — there is no standalone icon
+ * descriptor. The executor maps each field onto a concrete override op.
+ */
+export type OverrideField = 'label' | 'key' | 'pii' | 'copy' | 'enum_semantics' | 'virtual_relation' | 'relation_suppressed';
+/** A write against `adminium_schema_overrides` (§8.3). */
+export interface OverrideWrite {
+    target: 'override';
+    /** The originating §8.1 suggestion id (accept/reject trace + idempotency key). */
+    suggestionId: string;
+    field: OverrideField;
+    /** Qualified `"schema.table"`. */
+    table: string;
+    /** Column name for column-scoped fields; `null` for table-scoped fields. */
+    column: string | null;
+    /**
+     * Field-specific value json (localized maps where applicable), or `null` for
+     * an explicit clear — a `rejects-heuristic` PII rejection writes `pii: null`.
+     */
+    value: Record<string, unknown> | null;
+    /** Always `'llm'` — the executor never lets an LLM write shadow a user edit. */
+    source: 'llm';
+    confidence: number;
+}
+/** One grid item on a planned dashboard page (04-widget-registry.md §6.1). */
+export interface PlannedLayoutItem {
+    /** Deterministic instance id = the widget's §8.1 suggestion id. */
+    i: string;
+    /** Registry widget id. */
+    widget: string;
+    x: number;
+    y: number;
+    /** Width in grid columns — the §5 span heuristic (KPI 3, donut/funnel 4, bar/table 6, line/area 8). */
+    w: number;
+    /** Height in half-row (40px) units — KPI 3, everything else 8. */
+    h: number;
+    config: {
+        title: string;
+        binding: Record<string, unknown>;
+    };
+}
+/** A planned dashboard grid (`config.layout`), matching `pageLayoutSchema`. */
+export interface PlannedLayout {
+    version: 1;
+    items: PlannedLayoutItem[];
+}
+/**
+ * Assign `nav_group` + `nav_order` to each member table's page rows (§8.3
+ * `group`). The executor stamps the group/order onto every table in `tables`.
+ */
+export interface NavGroupWrite {
+    target: 'page';
+    kind: 'nav-group';
+    suggestionId: string;
+    /** Group slug (kebab-case). */
+    group: string;
+    navOrder: number;
+    /** Localized group label. */
+    label: Partial<Record<LocaleCode, string>>;
+    icon: string;
+    /** Qualified table names this nav placement applies to. */
+    tables: string[];
+    source: 'llm';
+    confidence: number;
+}
+/**
+ * A new template page row for a table (§8.3 `template`): `{ type: template,
+ * table, config, enabled: true, source: 'llm' }`. The executor generates the
+ * template body from the active snapshot and skips the write if an identical
+ * page already exists — the planner does not dedupe against DB state.
+ */
+export interface TemplatePageWrite {
+    target: 'page';
+    kind: 'template-page';
+    suggestionId: string;
+    /** Page-template id, e.g. `page-queue-inbox`. */
+    template: string;
+    /** Qualified `"schema.table"` this page is generated for. */
+    table: string;
+    /** Recommendation rank (1 = best) — the executor derives nav ordering from it. */
+    rank: number;
+    /** Minimal data-scope seed; the executor expands it into the full page body. */
+    config: {
+        source: {
+            connectionId: string;
+            table: string;
+        };
+    };
+    source: 'llm';
+    confidence: number;
+}
+/**
+ * A new `page-dashboard` row whose `config.layout.items[]` carry the accepted,
+ * bound widgets (§8.3 `dashboard` + `widget`). Widgets are NOT standalone
+ * descriptors — each accepted widget folds into its dashboard's layout; an
+ * accepted widget whose dashboard was not accepted produces nothing (a widget
+ * cannot exist without its container page).
+ */
+export interface DashboardPageWrite {
+    target: 'page';
+    kind: 'dashboard-page';
+    suggestionId: string;
+    /** Dashboard slug. */
+    dashboard: string;
+    domain: string;
+    label: Partial<Record<LocaleCode, string>>;
+    navOrder: number;
+    /** Qualified table names the dashboard spans. */
+    tables: string[];
+    /** `config.layout` — items carry the query-descriptor binding + span-heuristic w/h. */
+    layout: PlannedLayout;
+    /** The accepted widget suggestion ids folded into this page (bound layout items). */
+    widgetIds: string[];
+    source: 'llm';
+    confidence: number;
+}
+export type PageWrite = NavGroupWrite | TemplatePageWrite | DashboardPageWrite;
+export type WriteDescriptor = OverrideWrite | PageWrite;
+/** An ordered, serializable plan of write descriptors (§8.3). */
+export interface ApplyPlan {
+    /** The connection every write targets (also stamped into widget bindings). */
+    connectionId: string;
+    /** The run this plan derives from — provenance recorded on every applied row. */
+    llmRunId?: string;
+    /**
+     * Write descriptors in the diff's stable (category, id) order: labels, keys,
+     * enum semantics, relations, PII, template pages, nav groups, dashboard
+     * pages, micro-copy. Deterministic — re-planning the same run is identical.
+     */
+    writes: WriteDescriptor[];
+    /** Accepted ids skipped because their target is a `source: 'user'` override (locked). */
+    excludedUserLocked: string[];
+}
+export interface ApplyPlanOptions {
+    /** The connection these writes target; stamped into query-descriptor bindings. */
+    connectionId: string;
+    /** The run this plan derives from — provenance recorded on the plan. */
+    llmRunId?: string;
+}
+/**
+ * Build the ordered {@link ApplyPlan} for the accepted subset of a reviewed diff
+ * (§8.3). Emits one descriptor per accepted suggestion (widgets fold into their
+ * dashboard), excludes `user-locked` targets (provenance), and turns
+ * `rejects-heuristic` acceptances into suppression descriptors.
+ */
+export declare function buildApplyPlan(diff: readonly SuggestionDiff[], acceptedIds: Iterable<string>, opts: ApplyPlanOptions): ApplyPlan;
+export interface ApplyPlanSummary {
+    totalWrites: number;
+    overrides: number;
+    pages: number;
+    labels: number;
+    keys: number;
+    pii: number;
+    enums: number;
+    /** virtual relations + suppressions. */
+    relations: number;
+    microcopy: number;
+    navGroups: number;
+    templatePages: number;
+    dashboardPages: number;
+    /** Total bound layout items across all dashboard pages. */
+    widgets: number;
+    /**
+     * English fallback sentence ("Creates 1 dashboard page, 3 template pages;
+     * updates 41 labels…") for the confirmation modal. UI surfaces localize from
+     * the numeric counts above; this package carries no i18n runtime.
+     */
+    text: string;
+}
+/** Human counts for the review confirmation modal (§10.3, task step 3). */
+export declare function applyPlanSummary(plan: ApplyPlan): ApplyPlanSummary;
+//# sourceMappingURL=plan.d.ts.map

package/dist/apply/plan.d.ts.map

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