diff --git a/docs/component-interface-analysis.md b/docs/component-interface-analysis.md new file mode 100644 index 00000000..85b002b8 --- /dev/null +++ b/docs/component-interface-analysis.md @@ -0,0 +1,166 @@ +# Multi-Agent Chat Platform: Component Interface and Testing Strategy Analysis + +## 1. Architectural Components Public Interface Methods + +### 1.1 Personality Data Manager +#### Public Methods: +- `loadProfile(id: string)`: Retrieve a specific personality profile + - Input: Profile ID (string) + - Output: Fully detailed PersonalityProfile + - Error Scenarios: + * Profile not found + * Invalid profile ID format + * Insufficient access permissions + +- `validateProfile(profile: PersonalityProfile)`: Validate profile structure and content + - Input: Complete personality profile object + - Output: Validation result with potential error details + - Validation Checks: + * Required field completeness + * Field length constraints + * Semantic validations (e.g., tone appropriateness) + +- `saveProfile(profile: PersonalityProfile)`: Create or update a personality profile + - Input: Complete or partial profile object + - Output: Saved profile ID or success confirmation + - Error Scenarios: + * Duplicate profile + * Version conflict + * Storage limitations + +- `listProfiles(options?)`: Retrieve multiple personality profiles + - Input: Optional filtering and pagination parameters + - Output: List of profile metadata + - Supported Filters: + * Search by name/description + * Pagination + * Sorting options + +### 1.2 Conversation Orchestrator +#### Public Methods: +- `startSession(agents: PersonalityProfile[])`: Initialize a new conversation session + - Input: Array of participating agent profiles + - Output: Unique session identifier + - Error Scenarios: + * Maximum concurrent sessions exceeded + * Agent profile validation failures + * Resource allocation issues + +- `handleMessage(sessionId: string, message: string)`: Process user message in a conversation + - Input: Session ID and user message + - Output: Array of agent responses with metadata + - Processing Steps: + * Message routing + * Agent selection + * Response generation + - Error Scenarios: + * Invalid session + * Agent unavailability + * Message processing failures + +- `getSessionHistory(sessionId: string, options?)`: Retrieve conversation history + - Input: Session ID with optional pagination + - Output: Chronological message list + - Error Scenarios: + * Session not found + * Access restrictions + * Large history handling + +## 2. Comprehensive Unit Test Scenarios + +### 2.1 Personality Data Manager Test Scenarios +1. Profile Loading + - Successful profile retrieval + - Non-existent profile handling + - Partial profile loading + - Performance with large profile collections + +2. Profile Validation + - Complete valid profile + - Profile with missing required fields + - Invalid field formats + - Edge case input variations + +3. Profile Saving + - New profile creation + - Existing profile update + - Version conflict resolution + - Unique identifier generation + +4. Profile Listing + - Retrieving all profiles + - Filtered profile retrieval + - Pagination handling + - Search functionality + +### 2.2 Conversation Orchestrator Test Scenarios +1. Session Management + - Session initialization with single/multiple agents + - Session timeout handling + - Concurrent session limits + - Session state preservation + +2. Message Processing + - Single agent response + - Multi-agent dialogue routing + - Complex conversation context maintenance + - Message history tracking + +3. Error and Edge Cases + - Agent unavailability scenarios + - Partial agent response handling + - Malformed input processing + - Resource constraint simulations + +## 3. Test Coverage Recommendations + +### Coverage Targets +- Unit Tests: ≥ 80% code coverage +- Critical Path Coverage: 100% +- Branch Coverage: ≥ 75% + +### Coverage Dimensions +1. Functional Coverage + - All public method scenarios + - Expected and unexpected inputs + - Error path validation + +2. Performance Coverage + - Response time measurements + - Resource utilization tracking + - Scalability stress testing + +3. Security Coverage + - Input sanitization + - Access control verification + - Potential injection points + +### Recommended Testing Approach +- Unit Testing: Jest/Vitest +- Mocking: Sinon +- Test Data Generation: Faker +- Coverage Reporting: Istanbul + +## 4. Error Handling Strategy +- Standardized error codes +- Comprehensive error metadata +- Graceful degradation mechanisms +- Detailed logging for diagnostic purposes + +## 5. Performance and Scalability Considerations +- Horizontal scaling support +- Efficient resource management +- Caching strategies +- Minimal overhead in message routing + +## 6. Security Recommendations +- Input validation at each interface +- Role-based access controls +- Encryption of sensitive metadata +- Audit logging for critical operations + +## Appendix: Recommended Future Enhancements +- Machine learning-based agent selection +- Advanced conversation context tracking +- Dynamic personality profile generation +- Intelligent error recovery mechanisms diff --git a/docs/error-handling-strategy.md b/docs/error-handling-strategy.md new file mode 100644 index 00000000..0dfff3b1 --- /dev/null +++ b/docs/error-handling-strategy.md @@ -0,0 +1,48 @@ +# Error Handling and Edge Case Strategy + +## Personality Data Manager Error Scenarios + +### Profile Validation Errors +1. `INVALID_PROFILE_SCHEMA`: Profile does not match required structure +2. `DUPLICATE_PROFILE_ID`: Attempt to create profile with existing ID +3. `VERSION_CONFLICT`: Outdated profile version + +### Profile Management Errors +1. `PROFILE_NOT_FOUND`: Requested profile does not exist +2. `INSUFFICIENT_PERMISSIONS`: Unauthorized profile modification +3. `STORAGE_LIMIT_EXCEEDED`: Maximum number of profiles reached + +## Conversation Orchestrator Error Scenarios + +### Session Management Errors +1. `SESSION_INITIALIZATION_FAILED`: Unable to create conversation session +2. `MAX_SESSIONS_EXCEEDED`: Limit on concurrent sessions reached +3. `INVALID_SESSION_ID`: Attempted operation on non-existent session + +### Message Processing Errors +1. `AGENT_UNAVAILABLE`: Selected agent cannot process message +2. `MESSAGE_ROUTING_FAILED`: Unable to route message between agents +3. `CONVERSATION_TIMEOUT`: Session exceeded maximum duration + +## General Error Handling Principles +- Provide clear, actionable error messages +- Include error codes for programmatic handling +- Log comprehensive error details for debugging +- Implement graceful degradation strategies + +## Recommended Error Response Structure +```typescript +interface ErrorResponse { + code: string; + message: string; + details?: any; + timestamp: number; + requestId?: string; +} +``` + +## Logging and Monitoring +- Centralized error logging +- Error severity classification +- Performance impact tracking +- Automated alert mechanisms diff --git a/docs/interface-schemas.json b/docs/interface-schemas.json new file mode 100644 index 00000000..086c210b --- /dev/null +++ b/docs/interface-schemas.json @@ -0,0 +1,123 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "definitions": { + "PersonalityProfile": { + "type": "object", + "required": ["id", "name", "description", "tone", "version"], + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "pattern": "^[a-z0-9_-]+$", + "description": "Unique, URL-friendly identifier for the profile" + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "Display name of the personality" + }, + "description": { + "type": "string", + "minLength": 10, + "maxLength": 500, + "description": "Detailed description of the personality's characteristics" + }, + "tone": { + "type": "string", + "enum": [ + "Zealous", + "Contemplative", + "Compassionate", + "Analytical", + "Skeptical", + "Empathetic" + ], + "description": "Emotional and communication tone of the personality" + }, + "samplePrompts": { + "type": "array", + "items": { + "type": "string", + "minLength": 5, + "maxLength": 200 + }, + "minItems": 1, + "maxItems": 10, + "description": "Sample conversation starters or typical dialogue prompts" + }, + "version": { + "type": "integer", + "minimum": 1, + "description": "Version of the personality profile for tracking changes" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "description": "Additional configurable metadata for the personality" + } + }, + "additionalProperties": false + }, + "ChatMessage": { + "type": "object", + "required": ["id", "sender", "content", "timestamp"], + "properties": { + "id": { + "type": "string", + "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$", + "description": "Unique identifier for the message (UUID v4)" + }, + "sender": { + "type": "object", + "required": ["profileId", "name"], + "properties": { + "profileId": { + "type": "string", + "description": "Reference to the sender's personality profile" + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "Display name of the message sender" + } + }, + "additionalProperties": false + }, + "content": { + "type": "string", + "minLength": 1, + "maxLength": 1000, + "description": "Actual text content of the message" + }, + "timestamp": { + "type": "number", + "minimum": 0, + "description": "Unix timestamp of message creation" + }, + "metadata": { + "type": "object", + "properties": { + "confidence": { + "type": "number", + "minimum": 0, + "maximum": 1, + "description": "Confidence score of the message generation" + }, + "context": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Contextual tags or references" + } + }, + "additionalProperties": true + } + }, + "additionalProperties": false + } + } +} \ No newline at end of file diff --git a/docs/test-coverage-strategy.md b/docs/test-coverage-strategy.md new file mode 100644 index 00000000..52cf4a25 --- /dev/null +++ b/docs/test-coverage-strategy.md @@ -0,0 +1,89 @@ +# Comprehensive Test Coverage Strategy + +## 1. Overall Testing Objectives +- Achieve ≥ 80% code coverage across all components +- Ensure 100% coverage of critical paths and error handling +- Validate system reliability and robustness + +## 2. Coverage Metrics Breakdown + +### 2.1 Unit Test Coverage Targets +- Personality Data Manager: 85% coverage +- Conversation Orchestrator: 85% coverage +- Error Handling Module: 90% coverage +- Interface Validation: 95% coverage + +### 2.2 Coverage Dimensions +1. Functional Coverage +2. Error Path Coverage +3. Edge Case Handling +4. Performance Boundary Testing + +## 3. Detailed Test Scenario Matrix + +### 3.1 Personality Data Manager Test Scenarios +#### Positive Test Cases +- Successful profile creation +- Complete profile retrieval +- Comprehensive profile listing +- Pagination and filtering + +#### Negative Test Cases +- Invalid profile data +- Duplicate profile handling +- Access permission violations +- Resource constraint scenarios + +### 3.2 Conversation Orchestrator Test Scenarios +#### Session Management Tests +- Session initialization +- Concurrent session handling +- Session timeout mechanisms +- Maximum session limit enforcement + +#### Message Processing Tests +- Single agent response generation +- Multi-agent dialogue routing +- Complex conversation context maintenance +- Message history preservation + +## 4. Error Handling Verification +- Comprehensive error code coverage +- Detailed error message validation +- Graceful degradation testing +- Exception propagation mechanisms + +## 5. Performance and Scalability Testing +- Response time measurements +- Resource utilization tracking +- Stress testing with large datasets +- Horizontal scaling simulation + +## 6. Security Testing Considerations +- Input validation comprehensiveness +- Access control verification +- Potential injection point identification +- Sensitive data protection + +## 7. Testing Tools and Frameworks +- Primary Testing Framework: Jest +- Mocking Library: Sinon +- Test Data Generation: Faker +- Coverage Reporting: Istanbul + +## 8. Recommended Testing Workflow +1. Unit Test Development +2. Integration Testing +3. Error Scenario Simulation +4. Performance Benchmarking +5. Continuous Coverage Monitoring + +## 9. Reporting and Monitoring +- Automated coverage reports +- Trend analysis of test metrics +- Continuous improvement recommendations + +## 10. Future Testing Enhancements +- Machine learning-based test generation +- Chaos engineering integration +- Advanced mutation testing diff --git a/package.json b/package.json new file mode 100644 index 00000000..3c3a720f --- /dev/null +++ b/package.json @@ -0,0 +1,20 @@ +{ + "name": "multi-agent-chat-platform", + "version": "0.1.0", + "description": "Multi-agent interactive chat platform", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "test": "jest", + "lint": "eslint . --ext .ts" + }, + "devDependencies": { + "@types/jest": "^29.5.3", + "@typescript-eslint/eslint-plugin": "^6.0.0", + "@typescript-eslint/parser": "^6.0.0", + "eslint": "^8.44.0", + "jest": "^29.6.1", + "ts-jest": "^29.1.1", + "typescript": "^5.1.6" + } +} \ No newline at end of file diff --git a/src/interfaces/chat.interface.ts b/src/interfaces/chat.interface.ts new file mode 100644 index 00000000..451484d5 --- /dev/null +++ b/src/interfaces/chat.interface.ts @@ -0,0 +1,47 @@ +import { PersonalityProfile } from './personality.interface'; +import { MultiAgentError, ErrorCodes } from './errors'; + +export interface ChatMessage { + id: string; + sender: { + profileId: string; + name: string; + }; + content: string; + timestamp: number; +} + +export interface ConversationOrchestrator { + /** + * Start a new conversation session + * @throws {MultiAgentError} SESSION_INITIALIZATION_FAILED if session creation fails + * @throws {MultiAgentError} MAX_SESSIONS_EXCEEDED if session limit reached + */ + startSession(agents: PersonalityProfile[]): Promise; + + /** + * Handle an incoming user message + * @throws {MultiAgentError} INVALID_SESSION_ID for non-existent sessions + * @throws {MultiAgentError} AGENT_UNAVAILABLE if routing fails + */ + handleMessage( + sessionId: string, + message: string + ): Promise<{ + agentId: string; + response: string; + confidence: number; + }[]>; + + /** + * Get conversation history for a session + * @throws {MultiAgentError} INVALID_SESSION_ID for non-existent sessions + */ + getSessionHistory( + sessionId: string, + options?: { + limit?: number; + offset?: number; + } + ): Promise; +} \ No newline at end of file diff --git a/src/interfaces/errors.ts b/src/interfaces/errors.ts new file mode 100644 index 00000000..125d2926 --- /dev/null +++ b/src/interfaces/errors.ts @@ -0,0 +1,33 @@ +export enum ErrorCodes { + // Personality Data Manager Errors + INVALID_PROFILE_SCHEMA = 'PDME001', + DUPLICATE_PROFILE_ID = 'PDME002', + PROFILE_NOT_FOUND = 'PDME003', + + // Conversation Orchestrator Errors + SESSION_INITIALIZATION_FAILED = 'COE001', + MAX_SESSIONS_EXCEEDED = 'COE002', + INVALID_SESSION_ID = 'COE003', + AGENT_UNAVAILABLE = 'COE004' +} + +export class MultiAgentError extends Error { + public code: ErrorCodes; + public details?: any; + + constructor(code: ErrorCodes, message: string, details?: any) { + super(message); + this.code = code; + this.details = details; + this.name = 'MultiAgentError'; + } + + toJSON() { + return { + code: this.code, + message: this.message, + details: this.details, + timestamp: Date.now() + }; + } +} \ No newline at end of file diff --git a/src/interfaces/personality.interface.ts b/src/interfaces/personality.interface.ts new file mode 100644 index 00000000..0dc762de --- /dev/null +++ b/src/interfaces/personality.interface.ts @@ -0,0 +1,44 @@ +import { MultiAgentError, ErrorCodes } from './errors'; + +export interface PersonalityProfile { + id: string; + name: string; + description: string; + tone: 'Zealous' | 'Contemplative' | 'Compassionate' | 'Analytical'; + samplePrompts: string[]; + version: number; +} + +export interface ProfileValidationResult { + isValid: boolean; + errors?: MultiAgentError[]; +} + +export interface PersonalityDataManager { + /** + * Load a personality profile by its unique identifier + * @throws {MultiAgentError} PROFILE_NOT_FOUND if profile doesn't exist + */ + loadProfile(id: string): Promise; + + /** + * Validate a personality profile + * @throws {MultiAgentError} INVALID_PROFILE_SCHEMA for structural issues + */ + validateProfile(profile: PersonalityProfile): ProfileValidationResult; + + /** + * Save a new or updated personality profile + * @throws {MultiAgentError} DUPLICATE_PROFILE_ID if profile already exists + */ + saveProfile(profile: PersonalityProfile): Promise; + + /** + * List all available personality profiles with optional filtering + */ + listProfiles(options?: { + limit?: number; + offset?: number; + searchTerm?: string; + }): Promise[]>; +} \ No newline at end of file diff --git a/src/tests/personality.test.ts b/src/tests/personality.test.ts new file mode 100644 index 00000000..89c730ed --- /dev/null +++ b/src/tests/personality.test.ts @@ -0,0 +1,104 @@ +import { PersonalityProfile, PersonalityDataManager } from '../interfaces/personality.interface'; +import { MultiAgentError, ErrorCodes } from '../interfaces/errors'; + +describe('Personality Profile Management', () => { + const validProfile: PersonalityProfile = { + id: 'disciple_peter', + name: 'Peter', + description: 'Passionate disciple of Jesus', + tone: 'Zealous', + samplePrompts: [ + 'Tell me about your experience walking on water', + 'What did you learn from Jesus?' + ], + version: 1 + }; + + const mockDataManager: PersonalityDataManager = { + async loadProfile(id: string) { + if (id === 'disciple_peter') return validProfile; + throw new MultiAgentError( + ErrorCodes.PROFILE_NOT_FOUND, + 'Profile not found' + ); + }, + + validateProfile(profile: PersonalityProfile) { + const errors: MultiAgentError[] = []; + + if (!profile.name) { + errors.push(new MultiAgentError( + ErrorCodes.INVALID_PROFILE_SCHEMA, + 'Name is required' + )); + } + + return { + isValid: errors.length === 0, + errors: errors.length > 0 ? errors : undefined + }; + }, + + async saveProfile(profile: PersonalityProfile) { + if (profile.id === 'existing_profile') { + throw new MultiAgentError( + ErrorCodes.DUPLICATE_PROFILE_ID, + 'Profile already exists' + ); + } + return profile.id; + }, + + async listProfiles() { + return [ + { + id: validProfile.id, + name: validProfile.name, + description: validProfile.description, + tone: validProfile.tone, + version: validProfile.version + } + ]; + } + }; + + it('should successfully load an existing profile', async () => { + const profile = await mockDataManager.loadProfile('disciple_peter'); + expect(profile).toEqual(validProfile); + }); + + it('should throw error for non-existent profile', async () => { + await expect(mockDataManager.loadProfile('non_existent')) + .rejects + .toThrow(MultiAgentError); + }); + + it('should validate a complete profile', () => { + const result = mockDataManager.validateProfile(validProfile); + expect(result.isValid).toBe(true); + expect(result.errors).toBeUndefined(); + }); + + it('should detect invalid profile', () => { + const invalidProfile = { ...validProfile, name: '' }; + const result = mockDataManager.validateProfile(invalidProfile); + + expect(result.isValid).toBe(false); + expect(result.errors).toBeDefined(); + expect(result.errors?.[0].code).toBe(ErrorCodes.INVALID_PROFILE_SCHEMA); + }); + + it('should prevent duplicate profile creation', async () => { + const duplicateProfile = { ...validProfile, id: 'existing_profile' }; + + await expect(mockDataManager.saveProfile(duplicateProfile)) + .rejects + .toThrow(MultiAgentError); + }); + + it('should list personality profiles', async () => { + const profiles = await mockDataManager.listProfiles(); + expect(profiles.length).toBeGreaterThan(0); + expect(profiles[0].id).toBe('disciple_peter'); + }); +}); \ No newline at end of file diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 00000000..aa8d2992 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,14 @@ +{ + "compilerOptions": { + "target": "es2020", + "module": "commonjs", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "outDir": "./dist", + "rootDir": "./src" + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "**/*.spec.ts"] +} \ No newline at end of file