@naniteninja/profile-comparison-lib 0.0.1 → 1.0.0

package/README.md

@@ -1,314 +1,193 @@
-# 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.
+# Profile Comparison Library
+
+Angular library that renders a side-by-side profile comparison (two profile images, a central draggable shape, and aligned interest lists). It is a **thin client**: you provide a backend URL; the library sends user config to your backend and displays the payload it returns. No API keys or key-entry modals in the library.
+
+**You need a backend** that implements the profile comparison API (e.g. the **profile-comparison-server** repo). Provide its base URL via `PROFILE_COMPARISON_API_BASE_URL`. If not provided, the component shows **"Configure backend"**.
+
+---
+
+## Quickstart
+
+1. **Install the package**
+
+   ```bash
+   npm install profile-comparison-lib
+   ```
+
+2. **Provide the backend URL**
+
+   In `app.config.ts` (or `AppModule`):
+
+   ```typescript
+   import { PROFILE_COMPARISON_API_BASE_URL } from 'profile-comparison-lib';
+
+   providers: [
+     { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'https://your-backend.com/api' },
+   ]
+   ```
+
+   Or with a factory (e.g. runtime toggle between backends):
+
+   ```typescript
+   providers: [{
+     provide: PROFILE_COMPARISON_API_BASE_URL,
+     useFactory: (backendUrl: BackendUrlService) => () => backendUrl.getBaseUrl(),
+     deps: [BackendUrlService],
+   }]
+   ```
+
+3. **Use the component**
+
+   Import the module and add the component to a template:
+
+   ```typescript
+   import { ProfileComparisonLibModule } from 'profile-comparison-lib';
+   ```
+
+   ```html
+   <lib-profile-comparison [config]="config"></lib-profile-comparison>
+   ```
+
+---
+
+## What the element looks like
+
+When you use `<lib-profile-comparison>` in another Angular app you get:
+
+- **Side-by-side profile comparison**: two profile images (left and right) with a central draggable “shape” and aligned interest lists between them.
+- **Main regions**: left image, right image, center shape with text, loading indicator when a request is in progress.
+- **Action**: “View Profile” on each side; the component emits `viewProfileClick` with `{ side: 'left' | 'right' }` so the host can route or act.
+
+No key-entry modals or API key inputs appear in the library; all keys and third-party API calls live on your backend.
+
+---
+
+## Full setup (copy-paste)
+
+1. Create or open an Angular app (Angular ^20.0.0).
+
+2. Install the library and peer dependencies:
+
+   ```bash
+   npm install profile-comparison-lib @angular/core@^20 @angular/common@^20
+   ```
+
+3. Add the backend URL provider in `app.config.ts`:
+
+   ```typescript
+   import { ApplicationConfig } from '@angular/core';
+   import { provideHttpClient } from '@angular/common/http';
+   import { PROFILE_COMPARISON_API_BASE_URL } from 'profile-comparison-lib';
+
+   export const appConfig: ApplicationConfig = {
+     providers: [
+       provideHttpClient(),
+       { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'https://your-backend.com/api' },
+     ],
+   };
+   ```
+
+   Or in `AppModule`:
+
+   ```typescript
+   import { PROFILE_COMPARISON_API_BASE_URL } from 'profile-comparison-lib';
+
+   @NgModule({
+     providers: [
+       { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'https://your-backend.com/api' },
+     ],
+   })
+   export class AppModule {}
+   ```
+
+4. Import the module where you use the component:
+
+   ```typescript
+   import { ProfileComparisonLibModule } from 'profile-comparison-lib';
+
+   @NgModule({
+     imports: [ProfileComparisonLibModule, ...],
+   })
+   export class YourModule {}
+   ```
+
+5. Add the component to a template with required `[config]`:
+
+   ```html
+   <lib-profile-comparison
+     [config]="config"
+     [fadeAllEdges]="fadeAllEdges"
+     (matrixDataChange)="onMatrixData($event)"
+     (rawLLMOutputChange)="onRawLLMOutput($event)"
+     (viewProfileClick)="onViewProfile($event)"
+   ></lib-profile-comparison>
+   ```
+
+6. Run the app and ensure your backend is reachable at the URL you provided.
+
+---
+
+## Inputs and outputs
+
+### Inputs
+
+- **`config`** (required) — `IProfileConfig`:
+
+  ```json
+  {
+    "person1Interests": ["Gaming", "Programming", "AI/ML"],
+    "person2Interests": ["AI machine learning", "Mobile Games", "Data Science"],
+    "person3Interests": ["Board Games", "Machine Learning"],
+    "user1Image": "data:image/jpeg;base64,...",
+    "user2Image": "data:image/jpeg;base64,..."
+  }
+  ```
+
+  `user1Image` and `user2Image` can be data URLs or URLs; the library sends them to the backend as needed.
+
+- **`fadeAllEdges`** (optional) — `boolean`, default `false`. When true, fades the outer edges of the profile area.
+
+### Outputs
+
+- **`matrixDataChange`** — `IMatrixData`: legend, headers, and rows for the similarity matrix.
+
+  Example payload:
+
+  ```json
+  {
+    "legend": [{ "abbr": "Gam", "full": "Gaming" }, { "abbr": "Pro", "full": "Programming" }],
+    "headers": ["Gam", "Pro", "AI/ML"],
+    "rows": [
+      { "label": "Gam", "values": ["1.00", "0.2", "0.5"] },
+      { "label": "Pro", "values": ["0.2", "1.00", "0.8"] }
+    ]
+  }
+  ```
+
+- **`rawLLMOutputChange`** — `string`: raw LLM output from the backend (if any).
+
+- **`viewProfileClick`** — `{ side: 'left' | 'right' }`: emitted when the user clicks “View Profile” on the left or right side. Use this to navigate or open a profile page.
+
+  Example:
+
+  ```typescript
+  onViewProfile(payload: { side: 'left' | 'right' }) {
+    this.router.navigate(['/profile', payload.side]);
+  }
+  ```
+
+---
+
+## Backend API contract
+
+The library calls your backend at `POST {baseUrl}/profile/compare-full` with body `{ config: IProfileConfig }`. The backend should return a display payload (face results, aligned lists, center item, matrix data, raw LLM output). See the **profile-comparison-server** repo and the lib interface `IComparisonPayload` for the response shape.
+
+---
+
+## Building the library
+
+```bash
+ng build profile-comparison-lib
+```
+
+Output is in `dist/profile-comparison-lib/` (FESM, typings, package.json). Peer dependencies: Angular `^20.0.0` only.