@kaelio/ktx 0.14.0 → 0.15.0

package/dist/context/ingest/adapters/sigma/local-sigma.adapter.js

@@ -0,0 +1,41 @@
+import { resolveKtxConfigReference } from '../../../core/config-reference.js';
+import { DEFAULT_SIGMA_CLIENT_CONFIG, DefaultSigmaClient } from './client.js';
+import { SigmaSourceAdapter } from './sigma.adapter.js';
+function stringField(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+export function sigmaRuntimeConfigFromLocalConnection(connectionId, connection, env = process.env) {
+    if (!connection || String(connection.driver).toLowerCase() !== 'sigma') {
+        throw new Error(`Connection "${connectionId}" is not a Sigma connection`);
+    }
+    const apiUrl = stringField(connection.api_url) ?? 'https://api.sigmacomputing.com';
+    const clientId = stringField(connection.client_id);
+    const literalSecret = stringField(connection.client_secret);
+    const secretRef = stringField(connection.client_secret_ref);
+    const clientSecret = literalSecret ?? (secretRef ? (resolveKtxConfigReference(secretRef, env) ?? null) : null);
+    if (!clientId) {
+        throw new Error(`Connection "${connectionId}" is missing Sigma client_id`);
+    }
+    if (!clientSecret) {
+        throw new Error(`Connection "${connectionId}" is missing Sigma client_secret or client_secret_ref`);
+    }
+    return { apiUrl, clientId, clientSecret };
+}
+class LocalSigmaClientFactory {
+    project;
+    options;
+    constructor(project, options) {
+        this.project = project;
+        this.options = options;
+    }
+    createClient(config, _ctx) {
+        const runtimeConfig = sigmaRuntimeConfigFromLocalConnection(config.sigmaConnectionId, this.project.config.connections[config.sigmaConnectionId], this.options.env);
+        return new DefaultSigmaClient(runtimeConfig, this.options.defaultClientConfig ?? DEFAULT_SIGMA_CLIENT_CONFIG);
+    }
+}
+export function createLocalSigmaSourceAdapter(project, options = {}) {
+    return new SigmaSourceAdapter({
+        clientFactory: new LocalSigmaClientFactory(project, options),
+        ...(options.logger ? { logger: options.logger } : {}),
+    });
+}

package/dist/context/ingest/adapters/sigma/project.d.ts

@@ -0,0 +1,8 @@
+import type { SemanticLayerService } from '../../../../context/sl/semantic-layer.service.js';
+import type { DeterministicProjectionContext, ProjectionResult } from '../../types.js';
+type SlService = Pick<SemanticLayerService, 'writeSource'> & {
+    forWorktree(workdir: string): Pick<SemanticLayerService, 'writeSource'>;
+};
+/** @internal */
+export declare function projectSigmaDataModels(ctx: DeterministicProjectionContext, slService: SlService): Promise<ProjectionResult>;
+export {};

package/dist/context/ingest/adapters/sigma/project.js

@@ -0,0 +1,186 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { sigmaProjectionConfigSchema, stagedDataModelFileSchema, STAGED_FILES } from './types.js';
+async function readProjectionConfig(stagedDir) {
+    try {
+        const body = await readFile(join(stagedDir, STAGED_FILES.projectionConfig), 'utf-8');
+        return sigmaProjectionConfigSchema.parse(JSON.parse(body)).connectionMappings;
+    }
+    catch {
+        return {};
+    }
+}
+const SIGMA_AUTHOR = { name: 'Sigma', email: 'system@kaelio.dev' };
+// Best-effort schema for the raw spec blob stored in staged data model files.
+const warehouseTableSourceSchema = z.object({
+    kind: z.literal('warehouse-table'),
+    connectionId: z.string(),
+    path: z.array(z.string()),
+});
+const specColumnSchema = z
+    .object({
+    id: z.string(),
+    formula: z.string().optional(),
+    name: z.string().optional(),
+    hidden: z.boolean().optional(),
+    description: z.string().optional(),
+    format: z.object({ kind: z.string() }).passthrough().optional(),
+})
+    .passthrough();
+const specElementSchema = z
+    .object({
+    id: z.string(),
+    kind: z.string().optional(),
+    name: z.string().optional(),
+    hidden: z.boolean().optional(),
+    source: z.object({ kind: z.string() }).passthrough().optional(),
+    columns: z.array(specColumnSchema).optional(),
+})
+    .passthrough();
+const specPageSchema = z
+    .object({
+    id: z.string(),
+    name: z.string().optional(),
+    elements: z.array(specElementSchema).optional(),
+})
+    .passthrough();
+const sigmaSpecSchema = z
+    .object({
+    name: z.string().optional(),
+    pages: z.array(specPageSchema).optional(),
+})
+    .passthrough();
+/** Extract the column name from a bracket formula like `[TABLE/Column Name]` or `[Column]`. */
+function extractColumnName(formula) {
+    const match = /\[(?:[^\]/]+\/)?([^\]]+)\]/.exec(formula.trim());
+    return match?.[1] ?? null;
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function inferColumnType(col) {
+    const kind = col.format?.kind;
+    if (kind === 'datetime' || kind === 'date')
+        return 'time';
+    if (kind === 'number' || kind === 'currency' || kind === 'percent')
+        return 'number';
+    return 'string';
+}
+function buildSourceFromElement(dataModelName, elementName, elementId, warehousePath, columns) {
+    const table = warehousePath.join('.');
+    if (!table)
+        return null;
+    const modelSlug = slugify(dataModelName || elementId);
+    const elemSlug = elementName ? slugify(elementName) : '';
+    const sourceName = elemSlug && elemSlug !== modelSlug ? `${modelSlug}_${elemSlug}` : modelSlug;
+    if (!sourceName)
+        return null;
+    const slColumns = [];
+    for (const col of columns) {
+        if (col.hidden)
+            continue;
+        if (!col.formula)
+            continue;
+        // Aggregation formulas (Sum, Count, etc.) are Sigma-specific expressions that don't map to
+        // warehouse columns — skip them silently. The sigma_ingest skill surfaces them as wiki candidates.
+        if (/^[A-Za-z]+\(/.test(col.formula.trim()))
+            continue;
+        const displayName = col.name ?? extractColumnName(col.formula);
+        if (!displayName)
+            continue;
+        const colSlug = slugify(displayName);
+        if (!colSlug)
+            continue;
+        slColumns.push({
+            name: colSlug,
+            type: inferColumnType(col),
+            ...(col.description ? { descriptions: { user: col.description } } : {}),
+        });
+    }
+    const source = {
+        name: sourceName,
+        table,
+        grain: [],
+        columns: slColumns,
+        joins: [],
+        measures: [],
+    };
+    if (dataModelName) {
+        source.descriptions = { user: dataModelName };
+    }
+    return source;
+}
+/** @internal */
+export async function projectSigmaDataModels(ctx, slService) {
+    const svc = ctx.workdir ? slService.forWorktree(ctx.workdir) : slService;
+    const warnings = [];
+    const errors = [];
+    const touchedSources = [];
+    const connectionMappings = await readProjectionConfig(ctx.stagedDir);
+    const dmDir = join(ctx.stagedDir, STAGED_FILES.dataModelsDir);
+    let entries;
+    try {
+        entries = await readdir(dmDir);
+    }
+    catch {
+        return { warnings, errors, touchedSources, changedWikiPageKeys: [] };
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        let stagedFile;
+        try {
+            const body = await readFile(join(dmDir, entry), 'utf-8');
+            stagedFile = stagedDataModelFileSchema.parse(JSON.parse(body));
+        }
+        catch {
+            warnings.push(`Skipping malformed staged file: ${entry}`);
+            continue;
+        }
+        if (!stagedFile.spec)
+            continue;
+        let spec;
+        try {
+            spec = sigmaSpecSchema.parse(stagedFile.spec);
+        }
+        catch {
+            warnings.push(`Skipping unparseable spec for data model "${stagedFile.name}"`);
+            continue;
+        }
+        for (const page of spec.pages ?? []) {
+            for (const element of page.elements ?? []) {
+                if (element.hidden)
+                    continue;
+                const warehouseSource = warehouseTableSourceSchema.safeParse(element.source);
+                if (!warehouseSource.success)
+                    continue;
+                const source = buildSourceFromElement(stagedFile.name, element.name, element.id, warehouseSource.data.path, element.columns ?? []);
+                if (!source)
+                    continue;
+                // Only write SL sources for elements whose Sigma connection is mapped to a warehouse connection.
+                // Writing under an unmapped connection produces gate failures because the Sigma connection
+                // is not a warehouse connection and cannot be validated.
+                const targetConnectionId = connectionMappings[warehouseSource.data.connectionId];
+                if (!targetConnectionId) {
+                    warnings.push(`Skipping SL source for "${stagedFile.name}" / "${element.name ?? element.id}": ` +
+                        `no connectionMappings entry for Sigma connection ${warehouseSource.data.connectionId}. ` +
+                        `Add a connectionMappings entry in ktx.yaml to enable SL projection for this element.`);
+                    continue;
+                }
+                try {
+                    const result = await svc.writeSource(targetConnectionId, source, SIGMA_AUTHOR.name, SIGMA_AUTHOR.email, `Sigma: import data model "${stagedFile.name}"`);
+                    touchedSources.push({ connectionId: targetConnectionId, sourceName: source.name });
+                    warnings.push(...result.warnings);
+                }
+                catch (err) {
+                    errors.push(`Failed to write source "${source.name}": ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    return { warnings, errors, touchedSources, changedWikiPageKeys: [] };
+}

package/dist/context/ingest/adapters/sigma/sigma.adapter.d.ts

@@ -0,0 +1,18 @@
+import type { ChunkResult, DeterministicProjectionContext, DiffSet, FetchContext, ProjectionResult, SourceAdapter } from '../../types.js';
+import type { SigmaClientFactory } from './client-port.js';
+import { type SigmaFetchLogger } from './fetch.js';
+export interface SigmaSourceAdapterDeps {
+    clientFactory: SigmaClientFactory;
+    logger?: SigmaFetchLogger;
+}
+export declare class SigmaSourceAdapter implements SourceAdapter {
+    private readonly deps;
+    readonly source = "sigma";
+    readonly skillNames: string[];
+    constructor(deps: SigmaSourceAdapterDeps);
+    detect(stagedDir: string): Promise<boolean>;
+    fetch(pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
+    chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+    listTargetConnectionIds(stagedDir: string): Promise<string[]>;
+    project(ctx: DeterministicProjectionContext): Promise<ProjectionResult>;
+}

package/dist/context/ingest/adapters/sigma/sigma.adapter.js

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { chunkSigmaStagedDir } from './chunk.js';
+import { detectSigmaStagedDir } from './detect.js';
+import { fetchSigmaBundle } from './fetch.js';
+import { projectSigmaDataModels } from './project.js';
+import { sigmaProjectionConfigSchema, STAGED_FILES } from './types.js';
+export class SigmaSourceAdapter {
+    deps;
+    source = 'sigma';
+    skillNames = ['sigma_ingest'];
+    constructor(deps) {
+        this.deps = deps;
+    }
+    detect(stagedDir) {
+        return detectSigmaStagedDir(stagedDir);
+    }
+    async fetch(pullConfig, stagedDir, ctx) {
+        await fetchSigmaBundle({
+            pullConfig,
+            stagedDir,
+            ctx,
+            clientFactory: this.deps.clientFactory,
+            ...(this.deps.logger ? { logger: this.deps.logger } : {}),
+        });
+    }
+    chunk(stagedDir, diffSet) {
+        return chunkSigmaStagedDir(stagedDir, { diffSet });
+    }
+    async listTargetConnectionIds(stagedDir) {
+        try {
+            const body = await readFile(join(stagedDir, STAGED_FILES.projectionConfig), 'utf-8');
+            const config = sigmaProjectionConfigSchema.parse(JSON.parse(body));
+            return [...new Set(Object.values(config.connectionMappings))].sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    project(ctx) {
+        return projectSigmaDataModels(ctx, ctx.semanticLayerService);
+    }
+}

package/dist/context/ingest/adapters/sigma/types.d.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/** Filters applied when listing workbooks. Shared with ListWorkbooksOptions in client-port.ts. */
+declare const workbookFilterSchema: z.ZodObject<{
+    includeArchived: z.ZodDefault<z.ZodBoolean>;
+    includeExplorations: z.ZodDefault<z.ZodBoolean>;
+    updatedSince: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Input shape for listWorkbooks — all fields optional since the client applies its own defaults. */
+export type WorkbookFilterInput = z.input<typeof workbookFilterSchema>;
+/** The lean config the adapter needs at `fetch()` time, stored in the ingest job's `bundleRef.config`. */
+declare const sigmaPullConfigSchema: z.ZodObject<{
+    sigmaConnectionId: z.ZodString;
+    connectionMappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workbookFilter: z.ZodDefault<z.ZodObject<{
+        includeArchived: z.ZodDefault<z.ZodBoolean>;
+        includeExplorations: z.ZodDefault<z.ZodBoolean>;
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    dataModelFilter: z.ZodOptional<z.ZodObject<{
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SigmaPullConfig = z.infer<typeof sigmaPullConfigSchema>;
+export declare function parseSigmaPullConfig(raw: unknown): SigmaPullConfig;
+/** Written to stagedDir during fetch() and read back by project(), listTargetConnectionIds(), and the sigma_ingest skill. */
+export declare const sigmaProjectionConfigSchema: z.ZodObject<{
+    connectionMappings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workbookFilter: z.ZodDefault<z.ZodObject<{
+        includeArchived: z.ZodDefault<z.ZodBoolean>;
+        includeExplorations: z.ZodDefault<z.ZodBoolean>;
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SigmaProjectionConfig = z.infer<typeof sigmaProjectionConfigSchema>;
+/**
+ * A staged data model file, one per `data-models/<id>.json`.
+ * Stores the summary metadata plus the raw spec blob from GET /v2/dataModels/{id}/spec.
+ */
+export declare const stagedDataModelFileSchema: z.ZodObject<{
+    sigmaId: z.ZodString;
+    name: z.ZodString;
+    path: z.ZodString;
+    latestVersion: z.ZodNumber;
+    updatedAt: z.ZodString;
+    isArchived: z.ZodDefault<z.ZodBoolean>;
+    dataModelUrlId: z.ZodOptional<z.ZodString>;
+    spec: z.ZodUnknown;
+}, z.core.$strip>;
+export type StagedDataModelFile = z.infer<typeof stagedDataModelFileSchema>;
+/** The manifest written once per `fetch()`. Presence acts as the detect() sentinel. */
+export declare const sigmaManifestSchema: z.ZodObject<{
+    sigmaConnectionId: z.ZodString;
+    fetchedAt: z.ZodString;
+    dataModelCount: z.ZodNumber;
+    workbookCount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SigmaManifest = z.infer<typeof sigmaManifestSchema>;
+/**
+ * A staged workbook file, one per `workbooks/<id>.json`.
+ * Stores the summary metadata from GET /v2/workbooks (no separate spec endpoint).
+ */
+export declare const stagedWorkbookFileSchema: z.ZodObject<{
+    sigmaId: z.ZodString;
+    name: z.ZodString;
+    path: z.ZodString;
+    latestVersion: z.ZodNumber;
+    updatedAt: z.ZodString;
+    isArchived: z.ZodDefault<z.ZodBoolean>;
+    workbookUrlId: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StagedWorkbookFile = z.infer<typeof stagedWorkbookFileSchema>;
+/** Filenames inside stagedDir. Centralized so chunk() + fetch() + detect() all agree. */
+export declare const STAGED_FILES: {
+    readonly manifest: "sigma-manifest.json";
+    readonly projectionConfig: "sigma-projection-config.json";
+    readonly dataModelsDir: "data-models";
+    readonly workbooksDir: "workbooks";
+};
+export {};

package/dist/context/ingest/adapters/sigma/types.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+const sigmaLocalConnectionIdSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/);
+/** Filters applied when listing workbooks. Shared with ListWorkbooksOptions in client-port.ts. */
+const workbookFilterSchema = z.object({
+    includeArchived: z.boolean().default(false),
+    includeExplorations: z.boolean().default(false),
+    /** ISO 8601 date string. Only workbooks updated on or after this date are included. */
+    updatedSince: z.string().optional(),
+});
+const dataModelFilterSchema = z.object({
+    /** ISO 8601 date string. Only data models updated on or after this date are fetched. */
+    updatedSince: z.string().optional(),
+});
+/** The lean config the adapter needs at `fetch()` time, stored in the ingest job's `bundleRef.config`. */
+const sigmaPullConfigSchema = z.object({
+    /** The ktx connection ID for the Sigma instance being swept. */
+    sigmaConnectionId: sigmaLocalConnectionIdSchema,
+    /**
+     * Maps Sigma internal connection UUIDs (source.connectionId in data model specs)
+     * to ktx warehouse connection IDs. When present, projected semantic-layer sources
+     * are written under the mapped warehouse connection rather than the Sigma connection.
+     */
+    connectionMappings: z.record(z.string(), z.string()).optional(),
+    /** Filters applied when listing workbooks. Defaults exclude archived and exploration workbooks. */
+    workbookFilter: workbookFilterSchema.default({ includeArchived: false, includeExplorations: false }),
+    /** Filters applied when listing data models. */
+    dataModelFilter: dataModelFilterSchema.optional(),
+});
+export function parseSigmaPullConfig(raw) {
+    return sigmaPullConfigSchema.parse(raw);
+}
+/** Written to stagedDir during fetch() and read back by project(), listTargetConnectionIds(), and the sigma_ingest skill. */
+export const sigmaProjectionConfigSchema = z.object({
+    connectionMappings: z.record(z.string(), z.string()).default({}),
+    /** Filters that were active when workbooks were last fetched. Tells the skill what the staged set covers. */
+    workbookFilter: workbookFilterSchema.default({ includeArchived: false, includeExplorations: false }),
+});
+/**
+ * A staged data model file, one per `data-models/<id>.json`.
+ * Stores the summary metadata plus the raw spec blob from GET /v2/dataModels/{id}/spec.
+ */
+export const stagedDataModelFileSchema = z.object({
+    sigmaId: z.string(),
+    name: z.string(),
+    /** Full path in Sigma, e.g. "Finance/Revenue Model". */
+    path: z.string(),
+    latestVersion: z.number(),
+    updatedAt: z.string(),
+    isArchived: z.boolean().default(false),
+    /** URL-safe slug Sigma uses in the web UI (dataModelUrlId from the API). */
+    dataModelUrlId: z.string().optional(),
+    /** Raw spec from GET /v2/dataModels/{id}/spec (JSON format). */
+    spec: z.unknown(),
+});
+/** The manifest written once per `fetch()`. Presence acts as the detect() sentinel. */
+export const sigmaManifestSchema = z.object({
+    sigmaConnectionId: sigmaLocalConnectionIdSchema,
+    fetchedAt: z.string(),
+    dataModelCount: z.number().int(),
+    workbookCount: z.number().int().default(0),
+});
+/**
+ * A staged workbook file, one per `workbooks/<id>.json`.
+ * Stores the summary metadata from GET /v2/workbooks (no separate spec endpoint).
+ */
+export const stagedWorkbookFileSchema = z.object({
+    sigmaId: z.string(),
+    name: z.string(),
+    path: z.string(),
+    latestVersion: z.number(),
+    updatedAt: z.string(),
+    isArchived: z.boolean().default(false),
+    workbookUrlId: z.string().optional(),
+    description: z.string().optional(),
+});
+/** Filenames inside stagedDir. Centralized so chunk() + fetch() + detect() all agree. */
+export const STAGED_FILES = {
+    manifest: 'sigma-manifest.json',
+    projectionConfig: 'sigma-projection-config.json',
+    dataModelsDir: 'data-models',
+    workbooksDir: 'workbooks',
+};

package/dist/context/ingest/local-adapters.d.ts

@@ -7,6 +7,7 @@ import { type LookerMappingClient, type LookerTableIdentifierParser } from './ad
 import type { LookerRuntimeClient } from './adapters/looker/fetch.js';
 import type { MetabaseClientLogger } from './adapters/metabase/client.js';
 import type { MetabaseFetchLogger } from './adapters/metabase/fetch.js';
+import type { SigmaFetchLogger } from './adapters/sigma/fetch.js';
 import type { NotionFetchLogger } from './adapters/notion/fetch.js';
 import type { SourceAdapter } from './types.js';
 export interface DefaultLocalIngestAdaptersOptions {
@@ -29,7 +30,7 @@ export interface DefaultLocalIngestAdaptersOptions {
     };
     logger?: LocalIngestOperationalLogger;
 }
-type LocalIngestOperationalLogger = MetabaseClientLogger & MetabaseFetchLogger & LookerClientLogger & NotionFetchLogger;
+type LocalIngestOperationalLogger = MetabaseClientLogger & MetabaseFetchLogger & LookerClientLogger & NotionFetchLogger & SigmaFetchLogger;
 export declare function createDefaultLocalIngestAdapters(project: KtxLocalProject, options?: DefaultLocalIngestAdaptersOptions): SourceAdapter[];
 export declare function localPullConfigForAdapter(project: KtxLocalProject, adapter: SourceAdapter, connectionId: string, options?: DefaultLocalIngestAdaptersOptions): Promise<unknown>;
 export {};

package/dist/context/ingest/local-adapters.js

@@ -22,6 +22,7 @@ import { buildLookerPullConfigFromInputs, } from './adapters/looker/mapping.js';
 import { LookmlSourceAdapter } from './adapters/lookml/lookml.adapter.js';
 import { pullConfigFromIntegrationConfig } from './adapters/lookml/pull-config.js';
 import { createLocalMetabaseSourceAdapter } from './adapters/metabase/local-metabase.adapter.js';
+import { createLocalSigmaSourceAdapter } from './adapters/sigma/local-sigma.adapter.js';
 import { MetricflowSourceAdapter } from './adapters/metricflow/metricflow.adapter.js';
 import { pullConfigFromMetricflowIntegration } from './adapters/metricflow/pull-config.js';
 import { LocalNotionRuntimeStore } from './adapters/notion/local-state-store.js';
@@ -51,6 +52,9 @@ export function createDefaultLocalIngestAdapters(project, options = {}) {
         createLocalMetabaseSourceAdapter(project, {
             ...(options.logger ? { logger: options.logger } : {}),
         }),
+        createLocalSigmaSourceAdapter(project, {
+            ...(options.logger ? { logger: options.logger } : {}),
+        }),
         new GdriveSourceAdapter(),
         new LookerSourceAdapter({
             clientFactory: {
@@ -183,6 +187,24 @@ export async function localPullConfigForAdapter(project, adapter, connectionId,
     if (adapter.source === 'metabase') {
         throw new Error('Metabase scheduled pulls fan out by mapping. Call runLocalMetabaseIngest() or use `ktx ingest <metabase-source-id>` from the CLI.');
     }
+    if (adapter.source === 'sigma') {
+        const sigmaConn = project.config.connections[connectionId];
+        const connectionMappings = sigmaConn && 'connectionMappings' in sigmaConn && sigmaConn.connectionMappings != null
+            ? sigmaConn.connectionMappings
+            : undefined;
+        const workbookFilter = sigmaConn && 'workbookFilter' in sigmaConn && sigmaConn.workbookFilter != null
+            ? sigmaConn.workbookFilter
+            : undefined;
+        const dataModelFilter = sigmaConn && 'dataModelFilter' in sigmaConn && sigmaConn.dataModelFilter != null
+            ? sigmaConn.dataModelFilter
+            : undefined;
+        return {
+            sigmaConnectionId: connectionId,
+            ...(connectionMappings ? { connectionMappings } : {}),
+            ...(workbookFilter ? { workbookFilter } : {}),
+            ...(dataModelFilter ? { dataModelFilter } : {}),
+        };
+    }
     const connection = project.config.connections[connectionId];
     if (adapter.source === HISTORIC_SQL_SOURCE_KEY) {
         if (options.historicSqlPullConfigOverride) {

package/dist/context/project/config.d.ts

@@ -223,6 +223,21 @@ declare const connectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         path: z.ZodOptional<z.ZodString>;
         auth_token_ref: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"sigma">;
+    api_url: z.ZodDefault<z.ZodString>;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    client_secret_ref: z.ZodOptional<z.ZodString>;
+    connectionMappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workbookFilter: z.ZodOptional<z.ZodObject<{
+        includeArchived: z.ZodDefault<z.ZodBoolean>;
+        includeExplorations: z.ZodDefault<z.ZodBoolean>;
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    dataModelFilter: z.ZodOptional<z.ZodObject<{
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$loose>], "driver">;
 declare const ktxProjectConfigSchema: z.ZodObject<{
     setup: z.ZodOptional<z.ZodObject<{
@@ -347,6 +362,21 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodString>;
             auth_token_ref: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>;
+    }, z.core.$loose>, z.ZodObject<{
+        driver: z.ZodLiteral<"sigma">;
+        api_url: z.ZodDefault<z.ZodString>;
+        client_id: z.ZodString;
+        client_secret: z.ZodOptional<z.ZodString>;
+        client_secret_ref: z.ZodOptional<z.ZodString>;
+        connectionMappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        workbookFilter: z.ZodOptional<z.ZodObject<{
+            includeArchived: z.ZodDefault<z.ZodBoolean>;
+            includeExplorations: z.ZodDefault<z.ZodBoolean>;
+            updatedSince: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        dataModelFilter: z.ZodOptional<z.ZodObject<{
+            updatedSince: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$loose>], "driver">>>;
     storage: z.ZodPrefault<z.ZodObject<{
         state: z.ZodDefault<z.ZodEnum<{

package/dist/context/project/driver-schemas.d.ts

@@ -118,4 +118,19 @@ export declare const connectionConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
         path: z.ZodOptional<z.ZodString>;
         auth_token_ref: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>;
+}, z.core.$loose>, z.ZodObject<{
+    driver: z.ZodLiteral<"sigma">;
+    api_url: z.ZodDefault<z.ZodString>;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    client_secret_ref: z.ZodOptional<z.ZodString>;
+    connectionMappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workbookFilter: z.ZodOptional<z.ZodObject<{
+        includeArchived: z.ZodDefault<z.ZodBoolean>;
+        includeExplorations: z.ZodDefault<z.ZodBoolean>;
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    dataModelFilter: z.ZodOptional<z.ZodObject<{
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$loose>], "driver">;

package/dist/context/project/driver-schemas.js

@@ -218,6 +218,44 @@ const metricflowConnectionSchema = z
         .describe('Nested MetricFlow configuration block.'),
 })
     .describe('MetricFlow / SL context-source connection.');
+const sigmaConnectionSchema = z
+    .looseObject({
+    driver: z.literal('sigma'),
+    api_url: z
+        .string()
+        .url()
+        .default('https://api.sigmacomputing.com')
+        .describe('Sigma API base URL. Defaults to the GCP US endpoint; change for other regions.'),
+    client_id: z.string().min(1).describe('Sigma API client ID.'),
+    client_secret: z.string().min(1).optional().describe('Literal Sigma client secret. Prefer client_secret_ref.'),
+    client_secret_ref: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Reference to Sigma client secret (e.g. env:SIGMA_CLIENT_SECRET).'),
+    connectionMappings: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Maps Sigma internal connection UUIDs to ktx warehouse connection IDs. ' +
+        'When set, projected semantic-layer sources land under the mapped warehouse connection ' +
+        'instead of the Sigma connection, enabling sl_validate. ' +
+        'Find UUIDs in data model specs under source.connectionId.'),
+    workbookFilter: z
+        .object({
+        includeArchived: z.boolean().default(false),
+        includeExplorations: z.boolean().default(false),
+        updatedSince: z.string().optional().describe('ISO 8601 date string. Only workbooks updated on or after this date are ingested.'),
+    })
+        .optional()
+        .describe('Filters applied when listing workbooks during ingest. Defaults exclude archived and exploration workbooks.'),
+    dataModelFilter: z
+        .object({
+        updatedSince: z.string().optional().describe('ISO 8601 date string. Only data models updated on or after this date are fetched.'),
+    })
+        .optional()
+        .describe('Filters applied when listing data models during ingest.'),
+})
+    .describe('Sigma Computing API connection for ingesting data models.');
 export const connectionConfigSchema = z.discriminatedUnion('driver', [
     ...warehouseConnectionSchemas,
     mongodbConnectionSchema,
@@ -228,4 +266,5 @@ export const connectionConfigSchema = z.discriminatedUnion('driver', [
     gdriveConnectionSchema,
     dbtConnectionSchema,
     metricflowConnectionSchema,
+    sigmaConnectionSchema,
 ]);

package/dist/public-ingest.js

@@ -21,6 +21,7 @@ const sourceAdapterByDriver = new Map([
     ['metricflow', 'metricflow'],
     ['dbt', 'dbt'],
     ['lookml', 'lookml'],
+    ['sigma', 'sigma'],
 ]);
 export function publicProgressMessage(message, target) {
     let current = message;

package/dist/setup-sources.d.ts

@@ -3,7 +3,7 @@ import { type KtxProjectConnectionConfig } from './context/project/config.js';
 import type { KtxCliIo } from './cli-runtime.js';
 import { pickNotionRootPages } from './notion-page-picker.js';
 import { type KtxSetupPromptOption } from './setup-prompts.js';
-export type KtxSetupSourceType = 'dbt' | 'metricflow' | 'metabase' | 'looker' | 'lookml' | 'notion' | 'gdrive';
+export type KtxSetupSourceType = 'dbt' | 'metricflow' | 'metabase' | 'looker' | 'lookml' | 'notion' | 'sigma' | 'gdrive';
 export interface KtxSetupSourcesArgs {
     projectDir: string;
     inputMode: 'auto' | 'disabled';
@@ -99,6 +99,7 @@ export interface KtxSetupSourcesDeps {
     validateLooker?: (projectDir: string, connectionId: string) => Promise<SourceValidationResult>;
     validateLookml?: (connection: KtxProjectConnectionConfig) => Promise<SourceValidationResult>;
     validateNotion?: (connection: KtxProjectConnectionConfig) => Promise<SourceValidationResult>;
+    validateSigma?: (connection: KtxProjectConnectionConfig) => Promise<SourceValidationResult>;
     validateGdrive?: (connection: KtxProjectConnectionConfig) => Promise<SourceValidationResult>;
     pickNotionRootPages?: typeof pickNotionRootPages;
     discoverMetabaseDatabases?: (args: {