@kairos-sdk/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -67,6 +67,7 @@ interface CredentialRequirement {
 interface BuildResult {
     workflowId: string | null;
     name: string;
+    workflow: N8nWorkflow;
     credentialsNeeded: CredentialRequirement[];
     activationRequired: boolean;
     generationAttempts: number;
@@ -108,10 +109,42 @@ interface ILogger {
 }
 declare const nullLogger: ILogger;
 
+interface FailurePattern {
+    rule: number;
+    message: string;
+    occurrences: number;
+}
+type SourceKind = 'organic' | 'n8n-template' | 'imported';
+type TrustLevel = 'safe' | 'review' | 'blocked';
 interface WorkflowMetadataInput {
     description: string;
     tags?: string[];
     platform?: string;
+    failurePatterns?: Array<{
+        rule: number;
+        message: string;
+    }>;
+    sourceWorkflowIds?: string[];
+    generationMode?: 'direct' | 'reference' | 'scratch';
+    topMatchScore?: number;
+    generationAttempts?: number;
+    credentialsNeeded?: CredentialRequirement[];
+    sourceKind?: SourceKind;
+    sourceId?: string;
+    sourceUrl?: string;
+    trustLevel?: TrustLevel;
+}
+interface OutcomeData {
+    attempts: number;
+    firstTryPass: boolean;
+    failedRules: number[];
+    mode: 'direct' | 'reference';
+}
+interface OutcomeStats {
+    totalUses: number;
+    totalAttempts: number;
+    firstTryPasses: number;
+    failedRules: Record<string, number>;
 }
 interface StoredWorkflow {
     id: string;
@@ -122,6 +155,20 @@ interface StoredWorkflow {
     deployCount: number;
     createdAt: string;
     lastDeployedAt?: string;
+    failurePatterns?: FailurePattern[];
+    sourceWorkflowIds?: string[];
+    generationMode?: 'direct' | 'reference' | 'scratch';
+    topMatchScore?: number;
+    generationAttempts?: number;
+    credentialsNeeded?: CredentialRequirement[];
+    sourceKind?: SourceKind;
+    sourceId?: string;
+    sourceUrl?: string;
+    trustLevel?: TrustLevel;
+    timesRetrieved?: number;
+    timesUsedAsDirect?: number;
+    timesUsedAsReference?: number;
+    outcomeStats?: OutcomeStats;
 }
 interface WorkflowMatch {
     workflow: StoredWorkflow;
@@ -141,14 +188,15 @@ interface IWorkflowLibrary {
     search(description: string, options?: SearchOptions): Promise<WorkflowMatch[]>;
     save(workflow: N8nWorkflow, metadata: WorkflowMetadataInput): Promise<string>;
     recordDeployment(id: string): Promise<void>;
+    recordOutcome(id: string, outcome: OutcomeData): Promise<void>;
     get(id: string): Promise<StoredWorkflow | null>;
     list(filters?: LibraryFilters): Promise<StoredWorkflow[]>;
 }
 
 interface ClientOptions {
     anthropicApiKey: string;
-    n8nBaseUrl: string;
-    n8nApiKey: string;
+    n8nBaseUrl?: string;
+    n8nApiKey?: string;
     model?: string;
     logger?: ILogger;
     library?: IWorkflowLibrary;
@@ -175,10 +223,18 @@ declare class Kairos {
     private readonly library;
     private readonly logger;
     private readonly telemetry;
+    private readonly telemetryReader;
     private readonly model;
+    private saveQueue;
     constructor(options: ClientOptions);
+    private requireProvider;
+    private validateDescription;
     build(description: string, options?: BuildOptions): Promise<BuildResult>;
-    update(id: string, description: string): Promise<BuildResult>;
+    replace(id: string, description: string): Promise<BuildResult>;
+    drain(): Promise<void>;
+    private emitAttemptTelemetry;
+    private recordDeploy;
+    private saveToLibrary;
     get(id: string): Promise<N8nWorkflow>;
     list(): Promise<WorkflowListItem[]>;
     activate(id: string): Promise<void>;
@@ -234,6 +290,7 @@ declare class N8nApiClient {
     private readonly logger;
     constructor(baseUrl: string, apiKey: string, logger: ILogger);
     private request;
+    private singleRequest;
     createWorkflow(workflow: N8nWorkflow): Promise<N8nWorkflowResponse>;
     updateWorkflow(id: string, workflow: N8nWorkflow): Promise<N8nWorkflowResponse>;
     getWorkflow(id: string): Promise<N8nWorkflowResponse>;
@@ -281,25 +338,66 @@ declare class NullLibrary implements IWorkflowLibrary {
     search(_description: string, _options?: SearchOptions): Promise<WorkflowMatch[]>;
     save(_workflow: N8nWorkflow, _metadata: WorkflowMetadataInput): Promise<string>;
     recordDeployment(_id: string): Promise<void>;
+    recordOutcome(_id: string, _outcome: OutcomeData): Promise<void>;
     get(_id: string): Promise<StoredWorkflow | null>;
     list(_filters?: LibraryFilters): Promise<StoredWorkflow[]>;
 }
 
+declare function tokenize(text: string): string[];
+declare function buildSearchCorpus(w: StoredWorkflow): string;
 declare class FileLibrary implements IWorkflowLibrary {
     private readonly dir;
     private workflows;
-    private initialized;
+    private initPromise;
+    private writeQueue;
     constructor(dir?: string);
     initialize(): Promise<void>;
+    private doInitialize;
     search(description: string, options?: SearchOptions): Promise<WorkflowMatch[]>;
     save(workflow: N8nWorkflow, metadata: WorkflowMetadataInput): Promise<string>;
     recordDeployment(id: string): Promise<void>;
+    recordOutcome(id: string, outcome: OutcomeData): Promise<void>;
+    drain(): Promise<void>;
     get(id: string): Promise<StoredWorkflow | null>;
     list(filters?: LibraryFilters): Promise<StoredWorkflow[]>;
+    private deduplicateFailurePatterns;
     private persist;
 }
 
-interface ValidationIssue$1 {
+interface ScoredEntry {
+    workflow: StoredWorkflow;
+    score: number;
+    signals: {
+        tfidf: number;
+        nodeFingerprint: number;
+        outcome: number;
+        deploy: number;
+    };
+}
+declare function hybridScore(queryTokens: string[], queryDescription: string, workflows: StoredWorkflow[], docTokenArrays: string[][], idf: Map<string, number>): ScoredEntry[];
+
+interface WorkflowCluster {
+    pattern: string;
+    fingerprint: string[];
+    members: StoredWorkflow[];
+    avgFirstTryPassRate: number;
+    avgAttempts: number;
+    commonFailedRules: Array<{
+        rule: number;
+        frequency: number;
+    }>;
+}
+declare function clusterWorkflows(workflows: StoredWorkflow[]): WorkflowCluster[];
+declare function rerank(candidates: Array<{
+    workflow: StoredWorkflow;
+    score: number;
+}>, clusters: WorkflowCluster[]): Array<{
+    workflow: StoredWorkflow;
+    score: number;
+    clusterPattern?: string;
+}>;
+
+interface ValidationIssue {
     rule: number;
     severity: 'error' | 'warn';
     message: string;
@@ -307,7 +405,7 @@ interface ValidationIssue$1 {
 }
 interface ValidationResult {
     valid: boolean;
-    issues: ValidationIssue$1[];
+    issues: ValidationIssue[];
 }
 
 interface NodeDefinition {
@@ -323,7 +421,9 @@ declare class NodeRegistry {
     constructor(definitions?: NodeDefinition[]);
     get(type: string): NodeDefinition | undefined;
     isTrigger(type: string): boolean;
+    isKnown(type: string): boolean;
     isVersionSafe(type: string, version: number): boolean;
+    getRequiredParams(type: string): string[];
 }
 
 declare class N8nValidator {
@@ -352,6 +452,10 @@ declare class N8nValidator {
     private checkRule17;
     private checkRule18;
     private checkRule19;
+    private checkRule20;
+    private checkRule22;
+    private checkRule23;
+    private checkRule21;
 }
 
 declare class KairosError extends Error {
@@ -359,12 +463,6 @@ declare class KairosError extends Error {
     constructor(message: string, cause?: unknown | undefined);
 }
 
-interface ValidationIssue {
-    rule: number;
-    severity: 'error' | 'warn';
-    message: string;
-    nodeId?: string;
-}
 declare class ValidationError extends KairosError {
     readonly issues: ValidationIssue[];
     constructor(message: string, issues: ValidationIssue[]);
@@ -391,7 +489,33 @@ declare class GuardError extends KairosError {
     constructor(message: string);
 }
 
+interface SyncProgress {
+    total: number;
+    processed: number;
+    saved: number;
+    skippedPaid: number;
+    skippedDuplicate: number;
+    blocked: number;
+    reviewed: number;
+}
+
+interface SyncOptions {
+    maxTemplates?: number;
+    onProgress?: (progress: SyncProgress) => void;
+}
+declare class TemplateSyncer {
+    private readonly library;
+    private readonly validator;
+    private readonly logger;
+    constructor(library: IWorkflowLibrary, logger: ILogger);
+    sync(options?: SyncOptions): Promise<SyncProgress>;
+    private fetchTemplateIds;
+    private processTemplate;
+    private cleanDescription;
+}
+
 interface TelemetryEvent {
+    schemaVersion: number;
     timestamp: string;
     sessionId: string;
     eventType: 'build_start' | 'generation_attempt' | 'build_complete';
@@ -410,8 +534,25 @@ interface AttemptMetadata {
 declare class TelemetryCollector {
     private readonly dir;
     readonly sessionId: string;
+    private dirReady;
     constructor(dir?: string);
     emit(eventType: TelemetryEvent['eventType'], data: Record<string, unknown>): Promise<void>;
 }
 
-export { ApiError, type AttemptMetadata, type BuildOptions, type BuildResult, type ClientOptions, type CredentialRequirement, DEFAULT_REGISTRY, type DeleteOptions, type DeployResult, type ExecutionDetail, type ExecutionFilter, type ExecutionSummary, FileLibrary, GenerationError, GuardError, type ILogger, type IProvider, type IWorkflowLibrary, Kairos, KairosError, N8nApiClient, type N8nConnections, N8nFieldStripper, type N8nNode, N8nProvider, type N8nSettings, N8nValidator, type N8nWorkflow, NodeRegistry, NullLibrary, ProviderError, ResponseParseError, type StoredWorkflow, type Tag, TelemetryCollector, type TelemetryEvent, ValidationError, type ValidationIssue, type ValidationResult, type WorkflowListItem, type WorkflowMatch, nullLogger };
+interface RuleFailureRate {
+    rule: number;
+    failureCount: number;
+    totalBuilds: number;
+    rate: number;
+    commonMessage: string;
+}
+declare class TelemetryReader {
+    private readonly dir;
+    private cache;
+    private cacheTime;
+    constructor(dir?: string);
+    getFailureRates(days?: number): Promise<RuleFailureRate[]>;
+    private readRecentEvents;
+}
+
+export { ApiError, type AttemptMetadata, type BuildOptions, type BuildResult, type ClientOptions, type CredentialRequirement, DEFAULT_REGISTRY, type DeleteOptions, type DeployResult, type ExecutionDetail, type ExecutionFilter, type ExecutionSummary, type FailurePattern, FileLibrary, GenerationError, GuardError, type ILogger, type IProvider, type IWorkflowLibrary, Kairos, KairosError, N8nApiClient, type N8nConnections, N8nFieldStripper, type N8nNode, N8nProvider, type N8nSettings, N8nValidator, type N8nWorkflow, NodeRegistry, NullLibrary, type OutcomeData, type OutcomeStats, ProviderError, ResponseParseError, type RuleFailureRate, type ScoredEntry, type SourceKind, type StoredWorkflow, type SyncProgress, type Tag, TelemetryCollector, type TelemetryEvent, TelemetryReader, TemplateSyncer, type TrustLevel, ValidationError, type ValidationIssue, type ValidationResult, type WorkflowCluster, type WorkflowListItem, type WorkflowMatch, type WorkflowMetadataInput, buildSearchCorpus, clusterWorkflows, hybridScore, nullLogger, rerank, tokenize };

package/dist/index.d.ts

@@ -67,6 +67,7 @@ interface CredentialRequirement {
 interface BuildResult {
     workflowId: string | null;
     name: string;
+    workflow: N8nWorkflow;
     credentialsNeeded: CredentialRequirement[];
     activationRequired: boolean;
     generationAttempts: number;
@@ -108,10 +109,42 @@ interface ILogger {
 }
 declare const nullLogger: ILogger;
 
+interface FailurePattern {
+    rule: number;
+    message: string;
+    occurrences: number;
+}
+type SourceKind = 'organic' | 'n8n-template' | 'imported';
+type TrustLevel = 'safe' | 'review' | 'blocked';
 interface WorkflowMetadataInput {
     description: string;
     tags?: string[];
     platform?: string;
+    failurePatterns?: Array<{
+        rule: number;
+        message: string;
+    }>;
+    sourceWorkflowIds?: string[];
+    generationMode?: 'direct' | 'reference' | 'scratch';
+    topMatchScore?: number;
+    generationAttempts?: number;
+    credentialsNeeded?: CredentialRequirement[];
+    sourceKind?: SourceKind;
+    sourceId?: string;
+    sourceUrl?: string;
+    trustLevel?: TrustLevel;
+}
+interface OutcomeData {
+    attempts: number;
+    firstTryPass: boolean;
+    failedRules: number[];
+    mode: 'direct' | 'reference';
+}
+interface OutcomeStats {
+    totalUses: number;
+    totalAttempts: number;
+    firstTryPasses: number;
+    failedRules: Record<string, number>;
 }
 interface StoredWorkflow {
     id: string;
@@ -122,6 +155,20 @@ interface StoredWorkflow {
     deployCount: number;
     createdAt: string;
     lastDeployedAt?: string;
+    failurePatterns?: FailurePattern[];
+    sourceWorkflowIds?: string[];
+    generationMode?: 'direct' | 'reference' | 'scratch';
+    topMatchScore?: number;
+    generationAttempts?: number;
+    credentialsNeeded?: CredentialRequirement[];
+    sourceKind?: SourceKind;
+    sourceId?: string;
+    sourceUrl?: string;
+    trustLevel?: TrustLevel;
+    timesRetrieved?: number;
+    timesUsedAsDirect?: number;
+    timesUsedAsReference?: number;
+    outcomeStats?: OutcomeStats;
 }
 interface WorkflowMatch {
     workflow: StoredWorkflow;
@@ -141,14 +188,15 @@ interface IWorkflowLibrary {
     search(description: string, options?: SearchOptions): Promise<WorkflowMatch[]>;
     save(workflow: N8nWorkflow, metadata: WorkflowMetadataInput): Promise<string>;
     recordDeployment(id: string): Promise<void>;
+    recordOutcome(id: string, outcome: OutcomeData): Promise<void>;
     get(id: string): Promise<StoredWorkflow | null>;
     list(filters?: LibraryFilters): Promise<StoredWorkflow[]>;
 }
 
 interface ClientOptions {
     anthropicApiKey: string;
-    n8nBaseUrl: string;
-    n8nApiKey: string;
+    n8nBaseUrl?: string;
+    n8nApiKey?: string;
     model?: string;
     logger?: ILogger;
     library?: IWorkflowLibrary;
@@ -175,10 +223,18 @@ declare class Kairos {
     private readonly library;
     private readonly logger;
     private readonly telemetry;
+    private readonly telemetryReader;
     private readonly model;
+    private saveQueue;
     constructor(options: ClientOptions);
+    private requireProvider;
+    private validateDescription;
     build(description: string, options?: BuildOptions): Promise<BuildResult>;
-    update(id: string, description: string): Promise<BuildResult>;
+    replace(id: string, description: string): Promise<BuildResult>;
+    drain(): Promise<void>;
+    private emitAttemptTelemetry;
+    private recordDeploy;
+    private saveToLibrary;
     get(id: string): Promise<N8nWorkflow>;
     list(): Promise<WorkflowListItem[]>;
     activate(id: string): Promise<void>;
@@ -234,6 +290,7 @@ declare class N8nApiClient {
     private readonly logger;
     constructor(baseUrl: string, apiKey: string, logger: ILogger);
     private request;
+    private singleRequest;
     createWorkflow(workflow: N8nWorkflow): Promise<N8nWorkflowResponse>;
     updateWorkflow(id: string, workflow: N8nWorkflow): Promise<N8nWorkflowResponse>;
     getWorkflow(id: string): Promise<N8nWorkflowResponse>;
@@ -281,25 +338,66 @@ declare class NullLibrary implements IWorkflowLibrary {
     search(_description: string, _options?: SearchOptions): Promise<WorkflowMatch[]>;
     save(_workflow: N8nWorkflow, _metadata: WorkflowMetadataInput): Promise<string>;
     recordDeployment(_id: string): Promise<void>;
+    recordOutcome(_id: string, _outcome: OutcomeData): Promise<void>;
     get(_id: string): Promise<StoredWorkflow | null>;
     list(_filters?: LibraryFilters): Promise<StoredWorkflow[]>;
 }
 
+declare function tokenize(text: string): string[];
+declare function buildSearchCorpus(w: StoredWorkflow): string;
 declare class FileLibrary implements IWorkflowLibrary {
     private readonly dir;
     private workflows;
-    private initialized;
+    private initPromise;
+    private writeQueue;
     constructor(dir?: string);
     initialize(): Promise<void>;
+    private doInitialize;
     search(description: string, options?: SearchOptions): Promise<WorkflowMatch[]>;
     save(workflow: N8nWorkflow, metadata: WorkflowMetadataInput): Promise<string>;
     recordDeployment(id: string): Promise<void>;
+    recordOutcome(id: string, outcome: OutcomeData): Promise<void>;
+    drain(): Promise<void>;
     get(id: string): Promise<StoredWorkflow | null>;
     list(filters?: LibraryFilters): Promise<StoredWorkflow[]>;
+    private deduplicateFailurePatterns;
     private persist;
 }
 
-interface ValidationIssue$1 {
+interface ScoredEntry {
+    workflow: StoredWorkflow;
+    score: number;
+    signals: {
+        tfidf: number;
+        nodeFingerprint: number;
+        outcome: number;
+        deploy: number;
+    };
+}
+declare function hybridScore(queryTokens: string[], queryDescription: string, workflows: StoredWorkflow[], docTokenArrays: string[][], idf: Map<string, number>): ScoredEntry[];
+
+interface WorkflowCluster {
+    pattern: string;
+    fingerprint: string[];
+    members: StoredWorkflow[];
+    avgFirstTryPassRate: number;
+    avgAttempts: number;
+    commonFailedRules: Array<{
+        rule: number;
+        frequency: number;
+    }>;
+}
+declare function clusterWorkflows(workflows: StoredWorkflow[]): WorkflowCluster[];
+declare function rerank(candidates: Array<{
+    workflow: StoredWorkflow;
+    score: number;
+}>, clusters: WorkflowCluster[]): Array<{
+    workflow: StoredWorkflow;
+    score: number;
+    clusterPattern?: string;
+}>;
+
+interface ValidationIssue {
     rule: number;
     severity: 'error' | 'warn';
     message: string;
@@ -307,7 +405,7 @@ interface ValidationIssue$1 {
 }
 interface ValidationResult {
     valid: boolean;
-    issues: ValidationIssue$1[];
+    issues: ValidationIssue[];
 }
 
 interface NodeDefinition {
@@ -323,7 +421,9 @@ declare class NodeRegistry {
     constructor(definitions?: NodeDefinition[]);
     get(type: string): NodeDefinition | undefined;
     isTrigger(type: string): boolean;
+    isKnown(type: string): boolean;
     isVersionSafe(type: string, version: number): boolean;
+    getRequiredParams(type: string): string[];
 }
 
 declare class N8nValidator {
@@ -352,6 +452,10 @@ declare class N8nValidator {
     private checkRule17;
     private checkRule18;
     private checkRule19;
+    private checkRule20;
+    private checkRule22;
+    private checkRule23;
+    private checkRule21;
 }
 
 declare class KairosError extends Error {
@@ -359,12 +463,6 @@ declare class KairosError extends Error {
     constructor(message: string, cause?: unknown | undefined);
 }
 
-interface ValidationIssue {
-    rule: number;
-    severity: 'error' | 'warn';
-    message: string;
-    nodeId?: string;
-}
 declare class ValidationError extends KairosError {
     readonly issues: ValidationIssue[];
     constructor(message: string, issues: ValidationIssue[]);
@@ -391,7 +489,33 @@ declare class GuardError extends KairosError {
     constructor(message: string);
 }
 
+interface SyncProgress {
+    total: number;
+    processed: number;
+    saved: number;
+    skippedPaid: number;
+    skippedDuplicate: number;
+    blocked: number;
+    reviewed: number;
+}
+
+interface SyncOptions {
+    maxTemplates?: number;
+    onProgress?: (progress: SyncProgress) => void;
+}
+declare class TemplateSyncer {
+    private readonly library;
+    private readonly validator;
+    private readonly logger;
+    constructor(library: IWorkflowLibrary, logger: ILogger);
+    sync(options?: SyncOptions): Promise<SyncProgress>;
+    private fetchTemplateIds;
+    private processTemplate;
+    private cleanDescription;
+}
+
 interface TelemetryEvent {
+    schemaVersion: number;
     timestamp: string;
     sessionId: string;
     eventType: 'build_start' | 'generation_attempt' | 'build_complete';
@@ -410,8 +534,25 @@ interface AttemptMetadata {
 declare class TelemetryCollector {
     private readonly dir;
     readonly sessionId: string;
+    private dirReady;
     constructor(dir?: string);
     emit(eventType: TelemetryEvent['eventType'], data: Record<string, unknown>): Promise<void>;
 }
 
-export { ApiError, type AttemptMetadata, type BuildOptions, type BuildResult, type ClientOptions, type CredentialRequirement, DEFAULT_REGISTRY, type DeleteOptions, type DeployResult, type ExecutionDetail, type ExecutionFilter, type ExecutionSummary, FileLibrary, GenerationError, GuardError, type ILogger, type IProvider, type IWorkflowLibrary, Kairos, KairosError, N8nApiClient, type N8nConnections, N8nFieldStripper, type N8nNode, N8nProvider, type N8nSettings, N8nValidator, type N8nWorkflow, NodeRegistry, NullLibrary, ProviderError, ResponseParseError, type StoredWorkflow, type Tag, TelemetryCollector, type TelemetryEvent, ValidationError, type ValidationIssue, type ValidationResult, type WorkflowListItem, type WorkflowMatch, nullLogger };
+interface RuleFailureRate {
+    rule: number;
+    failureCount: number;
+    totalBuilds: number;
+    rate: number;
+    commonMessage: string;
+}
+declare class TelemetryReader {
+    private readonly dir;
+    private cache;
+    private cacheTime;
+    constructor(dir?: string);
+    getFailureRates(days?: number): Promise<RuleFailureRate[]>;
+    private readRecentEvents;
+}
+
+export { ApiError, type AttemptMetadata, type BuildOptions, type BuildResult, type ClientOptions, type CredentialRequirement, DEFAULT_REGISTRY, type DeleteOptions, type DeployResult, type ExecutionDetail, type ExecutionFilter, type ExecutionSummary, type FailurePattern, FileLibrary, GenerationError, GuardError, type ILogger, type IProvider, type IWorkflowLibrary, Kairos, KairosError, N8nApiClient, type N8nConnections, N8nFieldStripper, type N8nNode, N8nProvider, type N8nSettings, N8nValidator, type N8nWorkflow, NodeRegistry, NullLibrary, type OutcomeData, type OutcomeStats, ProviderError, ResponseParseError, type RuleFailureRate, type ScoredEntry, type SourceKind, type StoredWorkflow, type SyncProgress, type Tag, TelemetryCollector, type TelemetryEvent, TelemetryReader, TemplateSyncer, type TrustLevel, ValidationError, type ValidationIssue, type ValidationResult, type WorkflowCluster, type WorkflowListItem, type WorkflowMatch, type WorkflowMetadataInput, buildSearchCorpus, clusterWorkflows, hybridScore, nullLogger, rerank, tokenize };