@ixo/common 1.1.0

package/src/services/env/env-service.test.ts

@@ -0,0 +1,153 @@
+/* eslint-disable turbo/no-undeclared-env-vars -- test */
+import  z  from 'zod';
+import { EnvService } from './env.service.js';
+
+describe('EnvService', () => {
+  // Store original process.env
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    // Reset process.env before each test
+    process.env = { ...originalEnv };
+    // Reset the singleton instance
+    // @ts-expect-error accessing private static for testing
+    EnvService.instance = null;
+  });
+
+  afterAll(() => {
+    // Restore original process.env
+    process.env = originalEnv;
+  });
+
+  describe('initialization', () => {
+    it('should initialize with valid environment variables', () => {
+      // Arrange
+      const schema = z.object({
+        TEST_VAR: z.string(),
+        TEST_NUMBER: z.coerce.number(),
+      });
+      process.env.TEST_VAR = 'test';
+      process.env.TEST_NUMBER = '123';
+
+      // Act
+      const envService = EnvService.initialize(schema);
+
+      // Assert
+      expect(envService.get('TEST_VAR')).toBe('test');
+      expect(envService.get('TEST_NUMBER')).toBe(123);
+    });
+
+    it('should throw error when required environment variables are missing', () => {
+      // Arrange
+      const schema = z.object({
+        MISSING_VAR: z.string(),
+      });
+
+      // Act & Assert
+      expect(() => EnvService.initialize(schema)).toThrow();
+    });
+
+    it('should maintain singleton instance', () => {
+      // Arrange
+      const schema = z.object({
+        TEST_VAR: z.string(),
+      });
+      process.env.TEST_VAR = 'test';
+
+      // Act
+      const instance1 = EnvService.initialize(schema);
+      const instance2 = EnvService.initialize(schema);
+
+      // Assert
+      expect(instance1).toBe(instance2);
+    });
+  });
+
+  describe('getInstance', () => {
+    it('should throw error when accessing getInstance before initialization', () => {
+      // Act & Assert
+      expect(() => EnvService.getInstance()).toThrow(
+        'EnvService must be initialized with a schema first',
+      );
+    });
+
+    it('should return initialized instance', () => {
+      // Arrange
+      const schema = z.object({
+        TEST_VAR: z.string(),
+      });
+      process.env.TEST_VAR = 'test';
+      const initializedInstance = EnvService.initialize(schema);
+
+      // Act
+      const instance = EnvService.getInstance();
+
+      // Assert
+      expect(instance).toBe(initializedInstance);
+    });
+  });
+
+  describe('environment access', () => {
+    it('should return all environment variables', () => {
+      // Arrange
+      const schema = z.object({
+        TEST_VAR1: z.string(),
+        TEST_VAR2: z.string(),
+      });
+      process.env.TEST_VAR1 = 'value1';
+      process.env.TEST_VAR2 = 'value2';
+      const envService = EnvService.initialize(schema);
+
+      // Act
+      const allEnv = envService.getAll();
+
+      // Assert
+      expect(allEnv).toEqual({
+        TEST_VAR1: 'value1',
+        TEST_VAR2: 'value2',
+      });
+    });
+
+    it('should handle transformed values correctly', () => {
+      // Arrange
+      const schema = z.object({
+        NUMBER: z.string().transform(Number),
+        BOOLEAN: z.string().transform((val) => val === 'true'),
+      });
+      process.env.NUMBER = '42';
+      process.env.BOOLEAN = 'true';
+      const envService = EnvService.initialize(schema);
+
+      // Act & Assert
+      expect(envService.get('NUMBER')).toBe(42);
+      expect(envService.get('BOOLEAN')).toBe(true);
+    });
+  });
+
+  describe('validation', () => {
+    it('should validate enum values', () => {
+      // Arrange
+      const schema = z.object({
+        NODE_ENV: z.enum(['development', 'production', 'test']),
+      });
+      process.env.NODE_ENV = 'development';
+
+      // Act
+      const envService = EnvService.initialize(schema);
+
+      // Assert
+      expect(envService.get('NODE_ENV')).toBe('development');
+    });
+
+    it('should throw on invalid enum values', () => {
+      // Arrange
+      const schema = z.object({
+        NODE_ENV: z.enum(['development', 'production', 'test']),
+      });
+      process.env.NODE_ENV = 'invalid';
+
+      // Act & Assert
+      expect(() => EnvService.initialize(schema)).toThrow();
+    });
+  });
+});

package/src/services/env/env.service.ts

@@ -0,0 +1,65 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return  -- f*/
+import { Logger } from '@ixo/logger';
+import { config } from 'dotenv';
+import z from 'zod';
+
+config();
+
+export class EnvService<T extends z.ZodType> {
+  private static instance: EnvService<z.ZodType> | null = null;
+  private readonly validatedEnv: z.infer<T>;
+
+  private constructor(schema: T, onError?: (error: z.ZodError) => void) {
+    try {
+      // Parse and validate environment variables
+      this.validatedEnv = schema.parse(process.env) as z.infer<T>;
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        if (onError) {
+          onError(error);
+          return;
+        }
+        Logger.error('Environment validation failed:' + error.message);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Initialize the environment service with a schema
+   * @param schema - Zod schema to validate environment variables
+   * @returns EnvService instance
+   */
+  public static initialize<S extends z.ZodType>(schema: S): EnvService<S> {
+    if (EnvService.instance === null) {
+      EnvService.instance = new EnvService(schema);
+    }
+    return EnvService.instance as EnvService<S>;
+  }
+
+  /**
+   * Get the singleton instance of EnvService
+   * @throws Error if service hasn't been initialized
+   */
+  public static getInstance<S extends z.ZodType>(): EnvService<S> {
+    if (EnvService.instance === null) {
+      throw new Error('EnvService must be initialized with a schema first');
+    }
+    return EnvService.instance as EnvService<S>;
+  }
+
+  /**
+   * Get all validated environment variables
+   */
+  public getAll(): z.infer<T> {
+    return this.validatedEnv;
+  }
+
+  /**
+   * Get a specific environment variable
+   * @param key - The key of the environment variable
+   */
+  public get<K extends keyof z.infer<T>>(key: K): z.infer<T>[K] {
+    return this.validatedEnv[key];
+  }
+}

package/src/services/env/index.ts

@@ -0,0 +1 @@
+export { EnvService } from './env.service.js';

package/src/services/index.ts

@@ -0,0 +1,4 @@
+export * from './env/index.js';
+export * from './memory-engine/memory-engine.service.js';
+export * from './memory-engine/types.js';
+export * from './session-manager/index.js';

package/src/services/memory-engine/memory-engine.service.ts

@@ -0,0 +1,486 @@
+import { Logger } from '@ixo/logger';
+import type {
+  SearchEnhancedRequest,
+  SearchEnhancedResponse,
+  UserContextData,
+} from './types.js';
+
+export class MemoryEngineService {
+  private readonly QUERY_TIMEOUT_MS = 2500; // 2.5 seconds per query
+
+  constructor(
+    private readonly memoryEngineUrl: string,
+    private readonly memoryServiceApiKey: string,
+  ) {}
+
+  /**
+   * Wraps a promise with a timeout, returning fallback value if timeout is exceeded
+   */
+  private async withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    fallback: T,
+  ): Promise<T> {
+    return Promise.race([
+      promise,
+      new Promise<T>((resolve) =>
+        setTimeout(() => resolve(fallback), timeoutMs),
+      ),
+    ]);
+  }
+
+  /**
+   * Gather user context from Memory Engine by executing 6 parallel queries
+   */
+  async gatherUserContext(params: {
+    oracleDid: string;
+    userDid: string;
+    roomId: string;
+  }): Promise<UserContextData> {
+    const { oracleDid, userDid, roomId } = params;
+
+    Logger.info(
+      `[MemoryEngineService] Gathering user context for oracle: ${oracleDid}, room: ${roomId}`,
+    );
+
+    try {
+      // Execute all 6 queries in parallel with timeouts using Promise.allSettled
+      const results = await Promise.allSettled([
+        this.withTimeout(
+          this.queryIdentity(oracleDid, userDid, roomId),
+          this.QUERY_TIMEOUT_MS,
+          undefined,
+        ),
+        this.withTimeout(
+          this.queryWork(oracleDid, userDid, roomId),
+          this.QUERY_TIMEOUT_MS,
+          undefined,
+        ),
+        this.withTimeout(
+          this.queryGoals(oracleDid, userDid, roomId),
+          this.QUERY_TIMEOUT_MS,
+          undefined,
+        ),
+        this.withTimeout(
+          this.queryInterests(oracleDid, userDid, roomId),
+          this.QUERY_TIMEOUT_MS,
+          undefined,
+        ),
+        this.withTimeout(
+          this.queryRelationships(oracleDid, userDid, roomId),
+          this.QUERY_TIMEOUT_MS,
+          undefined,
+        ),
+        this.withTimeout(
+          this.queryRecent(oracleDid, userDid, roomId),
+          this.QUERY_TIMEOUT_MS,
+          undefined,
+        ),
+      ]);
+
+      // Extract results from Promise.allSettled outcomes
+      const identity =
+        results[0].status === 'fulfilled' ? results[0].value : undefined;
+      const work =
+        results[1].status === 'fulfilled' ? results[1].value : undefined;
+      const goals =
+        results[2].status === 'fulfilled' ? results[2].value : undefined;
+      const interests =
+        results[3].status === 'fulfilled' ? results[3].value : undefined;
+      const relationships =
+        results[4].status === 'fulfilled' ? results[4].value : undefined;
+      const recent =
+        results[5].status === 'fulfilled' ? results[5].value : undefined;
+
+      // Log any failures
+      results.forEach((result, index) => {
+        if (result.status === 'rejected') {
+          Logger.warn(
+            `[MemoryEngineService] Query ${index} failed:`,
+            result.reason,
+          );
+        }
+      });
+
+      return {
+        identity,
+        work,
+        goals,
+        interests,
+        relationships,
+        recent,
+      };
+    } catch (error) {
+      Logger.error(
+        '[MemoryEngineService] Failed to gather user context:',
+        error,
+      );
+      // Return empty context on error
+      return {};
+    }
+  }
+
+  /**
+   * Query 1: User Identity & Attributes
+   */
+  private async queryIdentity(
+    oracleDid: string,
+    userDid: string,
+    roomId: string,
+  ): Promise<SearchEnhancedResponse | undefined> {
+    const request: SearchEnhancedRequest = {
+      oracle_dids: [oracleDid],
+      query:
+        'username and nickname and age user identity traits values personality characteristics communication style beliefs preferences',
+      strategy: 'balanced',
+      max_facts: 10,
+      max_entities: 6,
+      max_episodes: 3,
+      max_communities: 2,
+      knowledge_level: 'both',
+      search_filters: {
+        node_labels: [
+          'Person',
+          'Trait',
+          'Value',
+          'Identity',
+          'Attribute',
+          'Emotion',
+          'Belief',
+          'CommunicationStyle',
+        ],
+        invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
+      },
+    };
+
+    return this.executeQuery(request, userDid, oracleDid, roomId);
+  }
+
+  /**
+   * Query 2: Work Context
+   */
+  private async queryWork(
+    oracleDid: string,
+    userDid: string,
+    roomId: string,
+  ): Promise<SearchEnhancedResponse | undefined> {
+    const request: SearchEnhancedRequest = {
+      oracle_dids: [oracleDid],
+      query:
+        'work job career projects skills organization employment role responsibilities expertise',
+      strategy: 'balanced',
+      max_facts: 10,
+      max_entities: 6,
+      max_episodes: 3,
+      max_communities: 2,
+      knowledge_level: 'both',
+      search_filters: {
+        node_labels: [
+          'Job',
+          'Project',
+          'Organization',
+          'Skill',
+          'Tool',
+          'Expertise',
+          'Task',
+        ],
+        edge_types: [
+          'EmployedAt',
+          'WorksOn',
+          'Manages',
+          'Uses',
+          'ExpertiseIn',
+          'WorksWith',
+        ],
+        invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
+      },
+    };
+
+    return this.executeQuery(request, userDid, oracleDid, roomId);
+  }
+
+  /**
+   * Query 3: Goals & Habits
+   */
+  private async queryGoals(
+    oracleDid: string,
+    userDid: string,
+    roomId: string,
+  ): Promise<SearchEnhancedResponse | undefined> {
+    const request: SearchEnhancedRequest = {
+      oracle_dids: [oracleDid],
+      query:
+        'goals aspirations objectives milestones habits routines patterns achievements progress',
+      strategy: 'balanced',
+      max_facts: 8,
+      max_entities: 4,
+      max_episodes: 3,
+      max_communities: 1,
+      knowledge_level: 'both',
+      search_filters: {
+        node_labels: [
+          'Goal',
+          'Milestone',
+          'Habit',
+          'Routine',
+          'Pattern',
+          'LearningGoal',
+        ],
+        edge_types: ['Pursuing', 'Achieved', 'Practices', 'Motivates'],
+        invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
+      },
+    };
+
+    return this.executeQuery(request, userDid, oracleDid, roomId);
+  }
+
+  /**
+   * Query 4: Interests & Preferences
+   */
+  private async queryInterests(
+    oracleDid: string,
+    userDid: string,
+    roomId: string,
+  ): Promise<SearchEnhancedResponse | undefined> {
+    const request: SearchEnhancedRequest = {
+      oracle_dids: [oracleDid],
+      query:
+        'interests hobbies passions preferences likes dislikes expertise topics content',
+      strategy: 'balanced',
+      max_facts: 8,
+      max_entities: 4,
+      max_episodes: 3,
+      max_communities: 1,
+      knowledge_level: 'both',
+      search_filters: {
+        node_labels: [
+          'Interest',
+          'Hobby',
+          'Preference',
+          'Product',
+          'Content',
+          'Expertise',
+          'Resource',
+        ],
+        edge_types: [
+          'Prefers',
+          'Likes',
+          'Dislikes',
+          'InterestedIn',
+          'ExpertiseIn',
+        ],
+        invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
+      },
+    };
+
+    return this.executeQuery(request, userDid, oracleDid, roomId);
+  }
+
+  /**
+   * Query 5: Relationships
+   */
+  private async queryRelationships(
+    oracleDid: string,
+    userDid: string,
+    roomId: string,
+  ): Promise<SearchEnhancedResponse | undefined> {
+    const request: SearchEnhancedRequest = {
+      oracle_dids: [oracleDid],
+      query:
+        'relationships people connections social network colleagues friends family contacts',
+      strategy: 'balanced',
+      max_facts: 6,
+      max_entities: 6,
+      max_episodes: 2,
+      max_communities: 1,
+      knowledge_level: 'both',
+      search_filters: {
+        node_labels: ['Person', 'Group'],
+        edge_types: [
+          'Knows',
+          'WorksWith',
+          'MemberOf',
+          'Influences',
+          'Supports',
+          'RelatesTo',
+        ],
+        invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
+      },
+    };
+
+    return this.executeQuery(request, userDid, oracleDid, roomId);
+  }
+
+  /**
+   * Query 6: Recent Context
+   */
+  private async queryRecent(
+    oracleDid: string,
+    userDid: string,
+    roomId: string,
+  ): Promise<SearchEnhancedResponse | undefined> {
+    // Calculate date 90 days ago for recent context
+    const ninetyDaysAgo = new Date();
+    ninetyDaysAgo.setDate(ninetyDaysAgo.getDate() - 90);
+    const dateString = ninetyDaysAgo.toISOString();
+
+    const request: SearchEnhancedRequest = {
+      oracle_dids: [oracleDid],
+      query:
+        'recent conversations messages discussions activities updates interactions',
+      strategy: 'recent_memory',
+      max_facts: 8,
+      max_entities: 4,
+      max_episodes: 6,
+      max_communities: 2,
+      knowledge_level: 'both',
+      search_filters: {
+        created_at: [[{ date: dateString, comparison_operator: '>=' }]],
+      },
+    };
+
+    return this.executeQuery(request, userDid, oracleDid, roomId);
+  }
+
+  /**
+   * Process conversation history by sending messages to the Memory Engine
+   */
+  async processConversationHistory({
+    messages,
+    userDid,
+    oracleDid,
+    roomId,
+  }: {
+    messages: Array<{
+      content: string;
+      role_type: 'user' | 'assistant' | 'system';
+      role?: string;
+      name?: string;
+      source_description?: string;
+    }>;
+    userDid: string;
+    oracleDid: string;
+    roomId: string;
+  }): Promise<{ success: boolean }> {
+    if (!userDid) {
+      Logger.warn(
+        `[MemoryEngineService] No user DID provided, skipping conversation processing`,
+      );
+      return { success: false };
+    }
+    if (!oracleDid) {
+      Logger.warn(
+        `[MemoryEngineService] No oracle did provided, skipping conversation processing`,
+      );
+      return { success: false };
+    }
+    if (!roomId) {
+      Logger.warn(
+        `[MemoryEngineService] No room id provided, skipping conversation processing`,
+      );
+      return { success: false };
+    }
+    if (!messages || messages.length === 0) {
+      Logger.info(
+        `[MemoryEngineService] No messages to process for room ${roomId}`,
+      );
+      return { success: true };
+    }
+
+    try {
+      const response = await fetch(`${this.memoryEngineUrl}/messages`, {
+        method: 'POST',
+        headers: {
+          'x-user-did': userDid,
+          'x-oracle-did': oracleDid,
+          'x-room-id': roomId,
+          'x-service-api-key': this.memoryServiceApiKey,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ messages }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        Logger.warn(
+          `[MemoryEngineService] Memory Engine conversation processing failed (${response.status}): ${errorText}`,
+        );
+        return { success: false };
+      }
+
+      Logger.info(
+        `[MemoryEngineService] Successfully processed ${messages.length} messages for room ${roomId}`,
+      );
+      return { success: true };
+    } catch (error) {
+      Logger.error(
+        `[MemoryEngineService] Failed to process conversation history for room ${roomId}:`,
+        error,
+      );
+      return { success: false };
+    }
+  }
+
+  /**
+   * Execute a search query against the Memory Engine API
+   */
+  private async executeQuery(
+    request: SearchEnhancedRequest,
+    userDid: string,
+    oracleDid: string,
+    roomId: string,
+  ): Promise<SearchEnhancedResponse | undefined> {
+    if (!userDid) {
+      Logger.warn(
+        `[MemoryEngineService] No user DID provided, skipping query "${request.query}"`,
+      );
+      return undefined;
+    }
+    if (!oracleDid) {
+      Logger.warn(
+        `[MemoryEngineService] No oracle did provided, skipping query "${request.query}"`,
+      );
+      return undefined;
+    }
+    if (!roomId) {
+      Logger.warn(
+        `[MemoryEngineService] No room id provided, skipping query "${request.query}"`,
+      );
+      return undefined;
+    }
+
+    try {
+      const response = await fetch(`${this.memoryEngineUrl}/search-enhanced`, {
+        method: 'POST',
+        headers: {
+          'x-user-did': userDid,
+          'x-oracle-did': oracleDid,
+          'x-room-id': roomId,
+          'x-service-api-key': this.memoryServiceApiKey,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(request),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        Logger.warn(
+          `[MemoryEngineService] Memory Engine query failed (${response.status}): ${errorText}`,
+        );
+        return undefined;
+      }
+
+      const result = (await response.json()) as SearchEnhancedResponse;
+      Logger.info(
+        `[MemoryEngineService] Query "${request.query}" returned ${result.total_results.facts} facts, ${result.total_results.entities} entities`,
+      );
+      return result;
+    } catch (error) {
+      Logger.error(
+        `[MemoryEngineService] Failed to execute query "${request.query}":`,
+        error,
+      );
+      return undefined;
+    }
+  }
+}