@naniteninja/profile-comparison-lib 0.0.1

package/README.md

@@ -0,0 +1,314 @@
+# Profile Comparison Library
+
+A powerful Angular 20 library for comparing user profiles using advanced AI-powered semantic similarity analysis and face detection capabilities.
+
+## Features
+
+- **Semantic Text Similarity**: Uses TensorFlow.js Universal Sentence Encoder for intelligent text comparison
+- **Face Detection & Alignment**: Integrates with API Ninjas Face Detection API for facial analysis
+- **Interest Matching**: Smart alignment of interests between profiles with similarity scoring
+- **TypeScript Support**: Fully typed interfaces and services
+- **Observable-based**: Reactive programming with RxJS observables
+
+## Installation
+
+```bash
+npm install profile-comparison-lib-test
+```
+
+## Dependencies
+
+The library requires the following peer dependencies:
+
+```bash
+npm install @tensorflow/tfjs @tensorflow-models/universal-sentence-encoder
+```
+
+## Setup
+
+### 1. Import the Module
+
+```typescript
+import { ProfileComparisonLibModule } from "profile-comparison-lib-test";
+
+@NgModule({
+  imports: [
+    ProfileComparisonLibModule,
+    // ... other imports
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Environment Configuration
+
+Add your API Ninjas API key to your environment configuration:
+
+```typescript
+// environment.ts
+export const environment = {
+  production: false,
+  apiNinjasKey: "your-api-ninjas-key-here",
+};
+```
+
+**⚠️ Security Note**: Never hardcode API keys in your source code. Always use environment variables or secure configuration management.
+
+## API Reference
+
+### Services
+
+#### EmbeddingService
+
+Provides semantic similarity analysis using TensorFlow.js Universal Sentence Encoder.
+
+**Methods:**
+
+- `getEmbedding(text: string): Observable<Float32Array>`
+  - Generates embedding vector for a single text
+- `calculateSimilarity(primaryText: string, comparisonText: string): Observable<number>`
+  - Calculates cosine similarity between two texts (returns value between -1 and 1)
+- `alignLists(listA: string[], listB: string[]): Observable<IWordAlignment[]>`
+  - Aligns words from listA with most similar words in listB
+- `findBestMatchingPairs(listA: string[], listB: string[], threshold?: number): Observable<IWordPair[]>`
+  - Finds best matching pairs between two lists above similarity threshold (default: 0.15)
+
+#### ProfileService
+
+Handles API integration for text similarity and face detection.
+
+**Methods:**
+
+- `compareInterests(text_1: string, text_2: string, apiKey: string): Observable<any>`
+  - Compares two text strings using API Ninjas Text Similarity API
+- `detectFace(file: File, apiKey: string): Observable<FaceDetectionResult>`
+  - Detects faces in uploaded image files
+
+### Interfaces
+
+#### IProfileConfig
+
+```typescript
+interface IProfileConfig {
+  person1Interests: string[];
+  person2Interests: string[];
+  person3Interests: string[];
+  user1Image: string;
+  user2Image: string;
+}
+```
+
+#### FaceDetectionResult
+
+```typescript
+interface FaceDetectionResult {
+  imageUrl: string;
+  faces: { x: number; y: number; width: number; height: number }[];
+}
+```
+
+#### BoundingBox
+
+```typescript
+interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+```
+
+#### Point
+
+```typescript
+interface Point {
+  x: number;
+  y: number;
+}
+```
+
+#### IWordAlignment
+
+```typescript
+interface IWordAlignment {
+  word: string;
+  alignedWith: string | null;
+  score: number;
+  index: number;
+}
+```
+
+#### IWordPair
+
+```typescript
+interface IWordPair {
+  wordA: string;
+  wordB: string;
+  score: number;
+}
+```
+
+## Usage Examples
+
+### Basic Text Similarity
+
+```typescript
+import { EmbeddingService } from 'profile-comparison-lib-test';
+
+constructor(private embeddingService: EmbeddingService) {}
+
+compareTexts() {
+  this.embeddingService.calculateSimilarity('I love traveling', 'I enjoy journeys')
+    .subscribe(similarity => {
+      console.log(`Similarity: ${(similarity * 100).toFixed(1)}%`);
+    });
+}
+```
+
+### Interest Matching
+
+```typescript
+import { EmbeddingService } from 'profile-comparison-lib-test';
+
+constructor(private embeddingService: EmbeddingService) {}
+
+matchInterests() {
+  const interests1 = ['traveling', 'photography', 'cooking'];
+  const interests2 = ['journeys', 'cameras', 'baking'];
+
+  this.embeddingService.findBestMatchingPairs$(interests1, interests2, 0.2)
+    .subscribe(pairs => {
+      pairs.forEach(pair => {
+        console.log(`${pair.wordA} ↔ ${pair.wordB} (${(pair.score * 100).toFixed(1)}%)`);
+      });
+    });
+}
+```
+
+### Face Detection
+
+```typescript
+import { ProfileService } from 'profile-comparison-lib-test';
+import { environment } from '../environments/environment';
+
+constructor(private profileService: ProfileService) {}
+
+detectFaces(imageFile: File) {
+  this.profileService.detectFace(imageFile, environment.apiNinjasKey)
+    .subscribe(result => {
+      console.log(`Found ${result.faces.length} faces`);
+      result.faces.forEach((face, index) => {
+        console.log(`Face ${index + 1}: x=${face.x}, y=${face.y}, width=${face.width}, height=${face.height}`);
+      });
+    });
+}
+```
+
+### Complete Profile Comparison
+
+```typescript
+import { EmbeddingService, ProfileService, IProfileConfig } from "profile-comparison-lib-test";
+import { environment } from "../environments/environment";
+
+export class ProfileComparisonComponent {
+  constructor(private embeddingService: EmbeddingService, private profileService: ProfileService) {}
+
+  compareProfiles(config: IProfileConfig) {
+    // Compare interests between person1 and person2
+    this.embeddingService.findBestMatchingPairs(
+      config.person1Interests,
+      config.person2Interests,
+      0.15
+    ).subscribe(matches => {
+      console.log("Interest matches:", matches);
+
+      // Sort by similarity score
+      const sortedMatches = matches.sort((a, b) => b.score - a.score);
+
+      // Display top matches
+      sortedMatches.slice(0, 5).forEach((match) => {
+        console.log(`${match.wordA} matches ${match.wordB} (${(match.score * 100).toFixed(1)}%)`);
+      });
+    });
+  }
+}
+```
+
+## Component Usage
+
+The library includes a basic component that can be used as a starting point:
+
+```html
+<lib-profile-comparison-lib></lib-profile-comparison-lib>
+```
+
+## Building the Library
+
+```bash
+ng build profile-comparison-lib-test
+```
+
+## Running Tests
+
+```bash
+ng test profile-comparison-lib-test
+```
+
+## API Keys Required
+
+This library requires an API key from [API Ninjas](https://api.api-ninjas.com/) for:
+
+- Text similarity comparison
+- Face detection functionality
+
+Sign up at API Ninjas to get your free API key.
+
+## Browser Compatibility
+
+- Chrome 119+
+- Firefox 115+
+- Safari 16.4+
+- Edge 119+
+
+Angular 20 requires modern browsers with ES2022+ support. TensorFlow.js requires WebGL support for optimal performance.
+
+## Performance Considerations
+
+- The Universal Sentence Encoder model (~25MB) is loaded lazily on first use
+- Model loading is cached for subsequent operations
+- Face detection API calls count against your API Ninjas quota
+- Consider implementing caching for repeated similarity calculations
+
+## Error Handling
+
+All service methods return observables with proper error handling. Wrap calls in try-catch blocks or use RxJS error operators:
+
+```typescript
+this.embeddingService
+  .calculateSimilarity('text1', 'text2')
+  .pipe(
+    catchError((error) => {
+      console.error("Similarity calculation failed:", error);
+      return of(0); // Return default similarity
+    })
+  )
+  .subscribe((similarity) => {
+    // Handle successful result
+  });
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License.
+
+## Support
+
+For issues and questions, please create an issue in the GitHub repository.