rax-flow-core 0.1.4 → 2.0.0

package/src/governance/rbac-engine.ts

@@ -0,0 +1,244 @@
+export type Role = "admin" | "user" | "viewer";
+export type Permission = 
+  | "workflow:read"
+  | "workflow:write"
+  | "workflow:execute"
+  | "workflow:delete"
+  | "config:read"
+  | "config:write"
+  | "metrics:read"
+  | "audit:read"
+  | "memory:read"
+  | "memory:write"
+  | "plugins:manage"
+  | "providers:configure";
+
+export interface User {
+  id: string;
+  name: string;
+  email?: string;
+  role: Role;
+  permissions?: Permission[];
+  metadata?: Record<string, unknown>;
+  createdAt: number;
+}
+
+export interface RoleDefinition {
+  name: Role;
+  permissions: Permission[];
+  inherits?: Role;
+  description: string;
+}
+
+const DEFAULT_ROLES: RoleDefinition[] = [
+  {
+    name: "admin",
+    description: "Full system access",
+    permissions: [
+      "workflow:read", "workflow:write", "workflow:execute", "workflow:delete",
+      "config:read", "config:write",
+      "metrics:read", "audit:read",
+      "memory:read", "memory:write",
+      "plugins:manage", "providers:configure"
+    ]
+  },
+  {
+    name: "user",
+    description: "Standard user with execution capabilities",
+    permissions: [
+      "workflow:read", "workflow:write", "workflow:execute",
+      "config:read",
+      "metrics:read",
+      "memory:read", "memory:write"
+    ]
+  },
+  {
+    name: "viewer",
+    description: "Read-only access",
+    permissions: [
+      "workflow:read",
+      "metrics:read"
+    ]
+  }
+];
+
+export class RBACEngine {
+  private roles: Map<Role, RoleDefinition> = new Map();
+  private users: Map<string, User> = new Map();
+  private customPermissions: Map<string, Permission[]> = new Map();
+
+  constructor(roles: RoleDefinition[] = DEFAULT_ROLES) {
+    for (const role of roles) {
+      this.roles.set(role.name, role);
+    }
+  }
+
+  createAdminUser(id: string, name: string, email?: string): User {
+    return this.createUser(id, name, "admin", email);
+  }
+
+  createUser(id: string, name: string, role: Role, email?: string): User {
+    const user: User = {
+      id,
+      name,
+      email,
+      role,
+      createdAt: Date.now()
+    };
+    this.users.set(id, user);
+    return user;
+  }
+
+  getUser(id: string): User | undefined {
+    return this.users.get(id);
+  }
+
+  updateUserRole(userId: string, role: Role): boolean {
+    const user = this.users.get(userId);
+    if (!user) return false;
+    user.role = role;
+    this.customPermissions.delete(userId);
+    return true;
+  }
+
+  grantPermission(userId: string, permission: Permission): boolean {
+    const user = this.users.get(userId);
+    if (!user) return false;
+
+    const existing = this.customPermissions.get(userId) || [];
+    if (!existing.includes(permission)) {
+      this.customPermissions.set(userId, [...existing, permission]);
+    }
+    return true;
+  }
+
+  revokePermission(userId: string, permission: Permission): boolean {
+    const user = this.users.get(userId);
+    if (!user) return false;
+
+    const existing = this.customPermissions.get(userId) || [];
+    const filtered = existing.filter(p => p !== permission);
+    this.customPermissions.set(userId, filtered);
+    return true;
+  }
+
+  hasPermission(userId: string, permission: Permission): boolean {
+    const user = this.users.get(userId);
+    if (!user) return false;
+
+    const customPerms = this.customPermissions.get(userId);
+    if (customPerms?.includes(permission)) return true;
+
+    const roleDef = this.roles.get(user.role);
+    if (!roleDef) return false;
+
+    if (roleDef.permissions.includes(permission)) return true;
+
+    if (roleDef.inherits) {
+      const parentRole = this.roles.get(roleDef.inherits);
+      return parentRole?.permissions.includes(permission) ?? false;
+    }
+
+    return false;
+  }
+
+  checkPermission(userId: string, permission: Permission): { allowed: boolean; reason?: string } {
+    if (this.hasPermission(userId, permission)) {
+      return { allowed: true };
+    }
+
+    const user = this.users.get(userId);
+    if (!user) {
+      return { allowed: false, reason: "User not found" };
+    }
+
+    return { allowed: false, reason: `Role '${user.role}' does not have permission '${permission}'` };
+  }
+
+  getUserPermissions(userId: string): Permission[] {
+    const user = this.users.get(userId);
+    if (!user) return [];
+
+    const roleDef = this.roles.get(user.role);
+    const rolePerms = roleDef?.permissions || [];
+    const customPerms = this.customPermissions.get(userId) || [];
+
+    return [...new Set([...rolePerms, ...customPerms])];
+  }
+
+  getRolePermissions(role: Role): Permission[] {
+    const roleDef = this.roles.get(role);
+    return roleDef?.permissions || [];
+  }
+
+  addRole(definition: RoleDefinition): void {
+    this.roles.set(definition.name, definition);
+  }
+
+  removeRole(role: Role): boolean {
+    if (["admin", "user", "viewer"].includes(role)) {
+      return false;
+    }
+    return this.roles.delete(role);
+  }
+
+  listRoles(): RoleDefinition[] {
+    return Array.from(this.roles.values());
+  }
+
+  listUsers(): User[] {
+    return Array.from(this.users.values());
+  }
+
+  deleteUser(userId: string): boolean {
+    this.customPermissions.delete(userId);
+    return this.users.delete(userId);
+  }
+
+  validateAccess(userId: string, resource: string, action: string): { allowed: boolean; reason?: string } {
+    const permission = `${resource}:${action}` as Permission;
+    return this.checkPermission(userId, permission);
+  }
+
+  canExecuteWorkflow(userId: string): boolean {
+    return this.hasPermission(userId, "workflow:execute");
+  }
+
+  canModifyConfig(userId: string): boolean {
+    return this.hasPermission(userId, "config:write");
+  }
+
+  canViewMetrics(userId: string): boolean {
+    return this.hasPermission(userId, "metrics:read");
+  }
+
+  canManagePlugins(userId: string): boolean {
+    return this.hasPermission(userId, "plugins:manage");
+  }
+
+  canConfigureProviders(userId: string): boolean {
+    return this.hasPermission(userId, "providers:configure");
+  }
+
+  exportState(): { users: User[]; customPermissions: Record<string, Permission[]> } {
+    return {
+      users: Array.from(this.users.values()),
+      customPermissions: Object.fromEntries(this.customPermissions)
+    };
+  }
+
+  importState(state: { users: User[]; customPermissions?: Record<string, Permission[]> }): void {
+    this.users.clear();
+    this.customPermissions.clear();
+
+    for (const user of state.users) {
+      this.users.set(user.id, user);
+    }
+
+    if (state.customPermissions) {
+      for (const [userId, perms] of Object.entries(state.customPermissions)) {
+        this.customPermissions.set(userId, perms);
+      }
+    }
+  }
+}

package/src/index.ts

@@ -1,7 +1,8 @@
 export * from "./types/contracts.js";
 export * from "./orchestrator/core-orchestrator.js";
 export * from "./orchestrator/routing.js";
-export * from "./orchestrator/decomposition.js";
+export { Decomposition, Subtask, TaskChunk, decomposeTask } from "./orchestrator/decomposition-engine.js";
+export * from "./orchestrator/task-decomposer.js";
 export * from "./orchestrator/default-workflow.js";
 export * from "./orchestrator/verify-fix.js";
 export * from "./orchestrator/kernel-bridge.js";
@@ -20,6 +21,8 @@ export * from "./memory/local-vector-store.js";
 export * from "./memory/graph-memory.js";
 export * from "./memory/memory-manager.js";
 export * from "./plugins/long-term-memory-plugin.js";
-
 export * from "./plugins/governance-plugin.js";
 export * from "./governance/policies/pii-policy.js";
+export * from "./governance/rbac-engine.js";
+export * from "./governance/audit-trail.js";
+export * from "./governance/policy-engine.js";

package/src/memory/embeddings-service.ts

@@ -0,0 +1,322 @@
+/**
+ * EmbeddingsService: Convert text/outputs to vector embeddings.
+ * Supports OpenAI, Cohere, or local models.
+ * Used to feed the LocalVectorStore with semantic vectors.
+ */
+
+export interface EmbeddingProvider {
+    name: string;
+    embed(text: string): Promise<number[]>;
+    batchEmbed(texts: string[]): Promise<number[][]>;
+    getDimensions(): number;
+}
+
+/**
+ * OpenAI embeddings provider
+ */
+export class OpenAIEmbeddingProvider implements EmbeddingProvider {
+    name = "openai";
+    private dimension = 1536;
+
+    constructor(private apiKey: string, private model: string = "text-embedding-3-small") {}
+
+    async embed(text: string): Promise<number[]> {
+        const results = await this.batchEmbed([text]);
+        return results[0];
+    }
+
+    async batchEmbed(texts: string[]): Promise<number[][]> {
+        try {
+            const response = await fetch("https://api.openai.com/v1/embeddings", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${this.apiKey}`
+                },
+                body: JSON.stringify({
+                    model: this.model,
+                    input: texts
+                })
+            });
+
+            if (!response.ok) {
+                throw new Error(`OpenAI API error: ${response.statusText}`);
+            }
+
+            const data = await response.json() as any;
+            return data.data.sort((a: any, b: any) => a.index - b.index).map((item: any) => item.embedding);
+        } catch (err) {
+            console.error("OpenAI embedding error:", err);
+            throw err;
+        }
+    }
+
+    getDimensions(): number {
+        return this.dimension;
+    }
+}
+
+/**
+ * Cohere embeddings provider
+ */
+export class CohereEmbeddingProvider implements EmbeddingProvider {
+    name = "cohere";
+    private dimension = 4096;
+
+    constructor(private apiKey: string, private model: string = "embed-english-v3.0") {}
+
+    async embed(text: string): Promise<number[]> {
+        const results = await this.batchEmbed([text]);
+        return results[0];
+    }
+
+    async batchEmbed(texts: string[]): Promise<number[][]> {
+        try {
+            const response = await fetch("https://api.cohere.ai/v1/embed", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": `Bearer ${this.apiKey}`
+                },
+                body: JSON.stringify({
+                    texts,
+                    model: this.model,
+                    input_type: "search_document"
+                })
+            });
+
+            if (!response.ok) {
+                throw new Error(`Cohere API error: ${response.statusText}`);
+            }
+
+            const data = await response.json() as any;
+            return data.embeddings;
+        } catch (err) {
+            console.error("Cohere embedding error:", err);
+            throw err;
+        }
+    }
+
+    getDimensions(): number {
+        return this.dimension;
+    }
+}
+
+/**
+ * Mock local embeddings provider (for testing/offline)
+ * Generates pseudo-random vectors based on text hash
+ */
+export class LocalEmbeddingProvider implements EmbeddingProvider {
+    name = "local";
+    private dimension = 384;
+
+    constructor() {}
+
+    async embed(text: string): Promise<number[]> {
+        return this.textToVector(text);
+    }
+
+    async batchEmbed(texts: string[]): Promise<number[][]> {
+        return texts.map(text => this.textToVector(text));
+    }
+
+    getDimensions(): number {
+        return this.dimension;
+    }
+
+    private textToVector(text: string): number[] {
+        // Simple hash-based deterministic vector generation
+        const hash = this.simpleHash(text);
+        const vector: number[] = [];
+        let seed = hash;
+
+        for (let i = 0; i < this.dimension; i++) {
+            seed = (seed * 9301 + 49297) % 233280;
+            vector.push((seed / 233280) * 2 - 1); // Normalize to [-1, 1]
+        }
+
+        // Normalize to unit vector
+        const magnitude = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
+        return vector.map(v => magnitude > 0 ? v / magnitude : 0);
+    }
+
+    private simpleHash(str: string): number {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return Math.abs(hash);
+    }
+}
+
+/**
+ * Embeddings Service: Orchestrates embedding generation and caching
+ */
+export class EmbeddingsService {
+    private provider: EmbeddingProvider;
+    private cache: Map<string, number[]> = new Map();
+    private cacheHits = 0;
+    private cacheMisses = 0;
+
+    constructor(provider: EmbeddingProvider | string = "local") {
+        if (typeof provider === "string") {
+            this.provider = this.getDefaultProvider(provider);
+        } else {
+            this.provider = provider;
+        }
+    }
+
+    /**
+     * Get a default provider by name
+     */
+    private getDefaultProvider(name: string): EmbeddingProvider {
+        const apiKey = process.env[`${name.toUpperCase()}_API_KEY`] || "";
+        
+        switch (name.toLowerCase()) {
+            case "openai":
+                return new OpenAIEmbeddingProvider(apiKey);
+            case "cohere":
+                return new CohereEmbeddingProvider(apiKey);
+            case "local":
+            default:
+                return new LocalEmbeddingProvider();
+        }
+    }
+
+    /**
+     * Embed a single text, with caching
+     */
+    async embed(text: string, useCache = true): Promise<number[]> {
+        const cacheKey = this.getCacheKey(text);
+
+        if (useCache && this.cache.has(cacheKey)) {
+            this.cacheHits++;
+            return this.cache.get(cacheKey)!;
+        }
+
+        this.cacheMisses++;
+        const vector = await this.provider.embed(text);
+        this.cache.set(cacheKey, vector);
+        return vector;
+    }
+
+    /**
+     * Embed multiple texts
+     */
+    async batchEmbed(texts: string[], useCache = true): Promise<number[][]> {
+        const results: number[][] = [];
+        const missingIndices: number[] = [];
+        const missingTexts: string[] = [];
+
+        // Check cache first
+        for (let i = 0; i < texts.length; i++) {
+            const cacheKey = this.getCacheKey(texts[i]);
+            if (useCache && this.cache.has(cacheKey)) {
+                results[i] = this.cache.get(cacheKey)!;
+                this.cacheHits++;
+            } else {
+                missingIndices.push(i);
+                missingTexts.push(texts[i]);
+            }
+        }
+
+        // Embed missing texts
+        if (missingTexts.length > 0) {
+            this.cacheMisses += missingTexts.length;
+            const vectors = await this.provider.batchEmbed(missingTexts);
+            
+            for (let i = 0; i < missingTexts.length; i++) {
+                const cacheKey = this.getCacheKey(missingTexts[i]);
+                results[missingIndices[i]] = vectors[i];
+                this.cache.set(cacheKey, vectors[i]);
+            }
+        }
+
+        return results;
+    }
+
+    /**
+     * Clear cache and reset stats
+     */
+    clearCache(): void {
+        this.cache.clear();
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+    }
+
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        const total = this.cacheHits + this.cacheMisses;
+        return {
+            cacheHits: this.cacheHits,
+            cacheMisses: this.cacheMisses,
+            hitRate: total > 0 ? (this.cacheHits / total * 100).toFixed(2) + "%" : "N/A",
+            cacheSize: this.cache.size,
+            provider: this.provider.name,
+            dimensions: this.provider.getDimensions()
+        };
+    }
+
+    /**
+     * Set embeddings provider
+     */
+    setProvider(provider: EmbeddingProvider): void {
+        this.provider = provider;
+        this.clearCache();
+    }
+
+    /**
+     * Get current provider
+     */
+    getProvider(): EmbeddingProvider {
+        return this.provider;
+    }
+
+    /**
+     * Get dimensions of embedding vectors
+     */
+    getDimensions(): number {
+        return this.provider.getDimensions();
+    }
+
+    /**
+     * Cache key generation (simple MD5 alternative)
+     */
+    private getCacheKey(text: string): string {
+        // Simple deterministic hash for caching
+        return Buffer.from(text).toString("base64");
+    }
+
+    /**
+     * Pre-warm cache with common prompts/outputs
+     */
+    async warmCache(documents: string[]): Promise<void> {
+        await this.batchEmbed(documents, false);
+    }
+}
+
+/**
+ * Create embeddings service from environment or config
+ */
+export function createEmbeddingsService(config?: {
+    provider?: "openai" | "cohere" | "local";
+    apiKey?: string;
+}): EmbeddingsService {
+    const providerName = config?.provider || process.env.EMBEDDINGS_PROVIDER || "local";
+    
+    if (providerName === "openai") {
+        const apiKey = config?.apiKey || process.env.OPENAI_API_KEY;
+        if (!apiKey) throw new Error("OPENAI_API_KEY not set");
+        return new EmbeddingsService(new OpenAIEmbeddingProvider(apiKey));
+    } else if (providerName === "cohere") {
+        const apiKey = config?.apiKey || process.env.COHERE_API_KEY;
+        if (!apiKey) throw new Error("COHERE_API_KEY not set");
+        return new EmbeddingsService(new CohereEmbeddingProvider(apiKey));
+    } else {
+        return new EmbeddingsService(new LocalEmbeddingProvider());
+    }
+}