@naniteninja/profile-comparison-lib 1.0.3 → 1.0.6

package/README.md

@@ -1,272 +1,167 @@
-# 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"**.
-
----
-
-## Quick start (copy-paste)
-
-### 1. Install
-
-```bash
-npm install @naniteninja/profile-comparison-lib @tensorflow/tfjs @tensorflow-models/universal-sentence-encoder
-```
-
-### 2. Wire up the module and backend URL
-
-```typescript
-import { NgModule } from '@angular/core';
-import { HttpClientModule } from '@angular/common/http';
-import {
-  ProfileComparisonLibModule,
-  PROFILE_COMPARISON_API_BASE_URL,
-} from '@naniteninja/profile-comparison-lib';
-
-@NgModule({
-  imports: [HttpClientModule, ProfileComparisonLibModule],
-  providers: [
-    { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'http://localhost:3000/api' },
-  ],
-})
-export class AppModule {}
-```
-
-### 3. Add the component to a template
-
-```html
-<lib-profile-comparison
-  [config]="profileConfig"
-  [fadeAllEdges]="false"
-  (matrixDataChange)="onMatrixData($event)"
-  (rawLLMOutputChange)="onRawLLM($event)"
-  (viewProfileClick)="onViewProfile($event)"
-></lib-profile-comparison>
-```
-
-### 4. Provide config data in the component
-
-```typescript
-import { IProfileConfig } from '@naniteninja/profile-comparison-lib';
-
-profileConfig: IProfileConfig = {
-  person1Interests: [
-    'Gaming', 'Programming', 'AI/ML', 'Startups',
-    'Blockchain', 'Cybersecurity', 'Web Development', 'Data Science',
-  ],
-  person2Interests: [
-    'AI machine learning', 'Mobile Games', 'Hardware',
-    'Data Science', 'Entrepreneurship', 'Design Thinking', 'Blockchain',
-  ],
-  person3Interests: ['Board Games', 'Machine Learning'],
-  user1Image: './assets/user1.jpg',   // data URL or asset path
-  user2Image: './assets/user2.jpg',
-};
-
-onMatrixData(data: any) { console.log('Matrix:', data); }
-onRawLLM(raw: string)   { console.log('LLM:', raw); }
-onViewProfile(e: { side: 'left' | 'right' }) {
-  console.log('View profile:', e.side);
-}
-```
-
-### 5. Start the backend and run
-
-```bash
-# Terminal 1 — backend (profile-comparison-server repo)
-cd ../profile-comparison-server && npm install && npm start
-
-# Terminal 2 — your app
-ng serve
-```
-
-The component renders two profile images with a draggable center shape, semantically aligned interest lists on each side, and a "View Profile" link per side. If the backend is unreachable, a **"Configure backend"** message appears instead.
-
----
-
-## Quickstart
-
-1. **Install the package and peer dependencies** (including TensorFlow; required for Vite and other bundlers):
-
-   ```bash
-   npm install @naniteninja/profile-comparison-lib @angular/core@^20 @angular/common@^20 @tensorflow/tfjs @tensorflow-models/universal-sentence-encoder
-   ```
-
-2. **Provide the backend URL**
-
-   In `app.config.ts` (or `AppModule`):
-
-   ```typescript
-   import { PROFILE_COMPARISON_API_BASE_URL } from '@naniteninja/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 '@naniteninja/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 (TensorFlow is required for dependency optimization in Vite etc.):
-
-   ```bash
-   npm install @naniteninja/profile-comparison-lib @angular/core@^20 @angular/common@^20 @tensorflow/tfjs @tensorflow-models/universal-sentence-encoder
-   ```
-
-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 '@naniteninja/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 '@naniteninja/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 '@naniteninja/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` and TensorFlow (`@tensorflow/tfjs`, `@tensorflow-models/universal-sentence-encoder`).
+# Profile Comparison Library
+
+Angular library that renders a side-by-side profile comparison (two profile images, a central draggable shape, and semantically aligned interest lists). It is a **thin client** — the library sends user config to a backend and displays the payload it returns. No API keys or key-entry modals live in the library.
+
+**You need a backend** that implements the profile comparison API (e.g. the **profile-comparison-server** repo). By default the component points at the real deployed backend. Set `[backendMode]="BackendMode.Mock"` to use `localhost:3000` during development.
+
+---
+
+## Quick start (copy-paste)
+
+### 1. Install
+
+```bash
+npm install @naniteninja/profile-comparison-lib
+```
+
+### 2. Wire up the module
+
+```typescript
+import { NgModule } from '@angular/core';
+import { HttpClientModule } from '@angular/common/http';
+import { ProfileComparisonLibModule } from '@naniteninja/profile-comparison-lib';
+
+@NgModule({
+  imports: [HttpClientModule, ProfileComparisonLibModule],
+})
+export class AppModule {}
+```
+
+### 3. Add the component to a template
+
+Minimal — uses the real deployed backend with all edges faded:
+
+```html
+<lib-profile-comparison [config]="profileConfig"></lib-profile-comparison>
+```
+
+During development, point at a local backend:
+
+```html
+<lib-profile-comparison
+  [config]="profileConfig"
+  [backendMode]="BackendMode.Mock"
+></lib-profile-comparison>
+```
+
+Or supply a fully custom URL (overrides `backendMode`):
+
+```html
+<lib-profile-comparison
+  [config]="profileConfig"
+  [backendUrl]="'https://my-custom-api.example.com/api'"
+></lib-profile-comparison>
+```
+
+Full example with all inputs and outputs:
+
+```html
+<lib-profile-comparison
+  [config]="profileConfig"
+  [backendMode]="backendMode"
+  [backendUrl]="customUrl"
+  [fadeAllEdges]="true"
+  (matrixDataChange)="onMatrixData($event)"
+  (rawLLMOutputChange)="onRawLLM($event)"
+  (viewProfileClick)="onViewProfile($event)"
+></lib-profile-comparison>
+```
+
+### 4. Component class
+
+```typescript
+import { Component } from '@angular/core';
+import { IProfileConfig, IMatrixData, BackendMode } from '@naniteninja/profile-comparison-lib';
+
+@Component({ /* ... */ })
+export class AppComponent {
+  readonly BackendMode = BackendMode; // expose enum to template
+
+  backendMode = BackendMode.Real;
+  customUrl: string | null = null;
+
+  profileConfig: IProfileConfig = {
+    person1Interests: [
+      'Gaming', 'Programming', 'AI/ML', 'Startups',
+      'Blockchain', 'Cybersecurity', 'Web Development', 'Data Science',
+    ],
+    person2Interests: [
+      'AI machine learning', 'Mobile Games', 'Hardware',
+      'Data Science', 'Entrepreneurship', 'Design Thinking', 'Blockchain',
+    ],
+    person3Interests: ['Board Games', 'Machine Learning'],
+    user1Image: './assets/user1.jpg',   // data-URL or asset path
+    user2Image: './assets/user2.jpg',
+  };
+
+  onMatrixData(data: IMatrixData) { console.log('Matrix:', data); }
+  onRawLLM(raw: string)          { console.log('LLM:', raw); }
+  onViewProfile(e: { side: 'left' | 'right' }) {
+    console.log('View profile:', e.side);
+  }
+}
+```
+
+### 5. Run
+
+```bash
+ng serve
+```
+
+If using `BackendMode.Mock`, start the local backend first:
+
+```bash
+cd ../profile-comparison-server && npm install && npm start   # listens on :3000
+```
+
+---
+
+## Inputs
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `config` | `IProfileConfig` | *required* | Profile data (interests, images) for the comparison. |
+| `backendMode` | `BackendMode` | `BackendMode.Real` (0) | `Real` = deployed backend, `Mock` = `localhost:3000`. |
+| `backendUrl` | `string \| null` | `null` | When non-empty, overrides `backendMode` entirely. |
+| `fadeAllEdges` | `boolean` | `true` | Fade the outer edges of the profile area. |
+
+## Outputs
+
+All outputs are optional — bind only what you need.
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `matrixDataChange` | `IMatrixData` | Legend, headers, and rows for the similarity matrix. |
+| `rawLLMOutputChange` | `string` | Raw LLM output from the backend (if any). |
+| `viewProfileClick` | `{ side: 'left' \| 'right' }` | Emitted when the user clicks "View Profile". |
+
+## BackendMode enum
+
+```typescript
+import { BackendMode } from '@naniteninja/profile-comparison-lib';
+
+BackendMode.Real  // 0 — deployed backend (default)
+BackendMode.Mock  // 1 — localhost:3000
+```
+
+### URL resolution priority
+
+1. `backendUrl` input (if non-empty)
+2. `backendMode` enum mapping
+3. Legacy `PROFILE_COMPARISON_API_BASE_URL` injection token (backward compatible)
+
+---
+
+## Backend API contract
+
+The library calls `POST {baseUrl}/profile/compare-full` with body `{ config: IProfileConfig }`. The backend returns a display payload (face results, aligned lists, center item, matrix data, raw LLM output). See the **profile-comparison-server** repo and the `IComparisonPayload` interface for the response shape.
+
+---
+
+## Building the library
+
+```bash
+ng build profile-comparison-lib
+```
+
+Output is in `dist/profile-comparison-lib/` (FESM bundles, typings, package.json). Peer dependencies: Angular `^20.0.0`.