@naniteninja/profile-comparison-lib 1.0.2 → 1.0.4

package/README.md

@@ -1,186 +1,160 @@
 # 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.
+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). Provide its base URL via `PROFILE_COMPARISON_API_BASE_URL`. If not provided, the component shows **"Configure backend"**.
+**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.
 
 ---
 
-## Quickstart
+## Quick start (copy-paste)
 
-1. **Install the package and peer dependencies** (including TensorFlow; required for Vite and other bundlers):
+### 1. Install
 
-   ```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.
-
----
+```bash
+npm install @naniteninja/profile-comparison-lib
+```
 
-## Full setup (copy-paste)
+### 2. Wire up the module
 
-1. Create or open an Angular app (Angular ^20.0.0).
+```typescript
+import { NgModule } from '@angular/core';
+import { HttpClientModule } from '@angular/common/http';
+import { ProfileComparisonLibModule } from '@naniteninja/profile-comparison-lib';
 
-2. Install the library and peer dependencies (TensorFlow is required for dependency optimization in Vite etc.):
+@NgModule({
+  imports: [HttpClientModule, ProfileComparisonLibModule],
+})
+export class AppModule {}
+```
 
-   ```bash
-   npm install @naniteninja/profile-comparison-lib @angular/core@^20 @angular/common@^20 @tensorflow/tfjs @tensorflow-models/universal-sentence-encoder
-   ```
+### 3. Add the component to a template
 
-3. Add the backend URL provider in `app.config.ts`:
+Minimal — uses the real deployed backend with all edges faded:
 
-   ```typescript
-   import { ApplicationConfig } from '@angular/core';
-   import { provideHttpClient } from '@angular/common/http';
-   import { PROFILE_COMPARISON_API_BASE_URL } from '@naniteninja/profile-comparison-lib';
+```html
+<lib-profile-comparison [config]="profileConfig"></lib-profile-comparison>
+```
 
-   export const appConfig: ApplicationConfig = {
-     providers: [
-       provideHttpClient(),
-       { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'https://your-backend.com/api' },
-     ],
-   };
-   ```
+During development, point at a local backend:
 
-   Or in `AppModule`:
+```html
+<lib-profile-comparison
+  [config]="profileConfig"
+  [backendMode]="BackendMode.Mock"
+></lib-profile-comparison>
+```
 
-   ```typescript
-   import { PROFILE_COMPARISON_API_BASE_URL } from '@naniteninja/profile-comparison-lib';
+Or supply a fully custom URL (overrides `backendMode`):
 
-   @NgModule({
-     providers: [
-       { provide: PROFILE_COMPARISON_API_BASE_URL, useValue: 'https://your-backend.com/api' },
-     ],
-   })
-   export class AppModule {}
-   ```
+```html
+<lib-profile-comparison
+  [config]="profileConfig"
+  [backendUrl]="'https://my-custom-api.example.com/api'"
+></lib-profile-comparison>
+```
 
-4. Import the module where you use the component:
+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>
+```
 
-   ```typescript
-   import { ProfileComparisonLibModule } from '@naniteninja/profile-comparison-lib';
+### 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);
+  }
+}
+```
 
-   @NgModule({
-     imports: [ProfileComparisonLibModule, ...],
-   })
-   export class YourModule {}
-   ```
+### 5. Run
 
-5. Add the component to a template with required `[config]`:
+```bash
+ng serve
+```
 
-   ```html
-   <lib-profile-comparison
-     [config]="config"
-     [fadeAllEdges]="fadeAllEdges"
-     (matrixDataChange)="onMatrixData($event)"
-     (rawLLMOutputChange)="onRawLLMOutput($event)"
-     (viewProfileClick)="onViewProfile($event)"
-   ></lib-profile-comparison>
-   ```
+If using `BackendMode.Mock`, start the local backend first:
 
-6. Run the app and ensure your backend is reachable at the URL you provided.
+```bash
+cd ../profile-comparison-server && npm install && npm start   # listens on :3000
+```
 
 ---
 
-## Inputs and outputs
-
-### Inputs
+## Inputs
 
-- **`config`** (required) — `IProfileConfig`:
+| 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. |
 
-  ```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,..."
-  }
-  ```
+## Outputs
 
-  `user1Image` and `user2Image` can be data URLs or URLs; the library sends them to the backend as needed.
+All outputs are optional — bind only what you need.
 
-- **`fadeAllEdges`** (optional) — `boolean`, default `false`. When true, fades the outer edges of the profile area.
+| 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". |
 
-### Outputs
+## BackendMode enum
 
-- **`matrixDataChange`** — `IMatrixData`: legend, headers, and rows for the similarity matrix.
+```typescript
+import { BackendMode } from '@naniteninja/profile-comparison-lib';
 
-  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.
+BackendMode.Real  // 0 — deployed backend (default)
+BackendMode.Mock  // 1 — localhost:3000
+```
 
-  Example:
+### URL resolution priority
 
-  ```typescript
-  onViewProfile(payload: { side: 'left' | 'right' }) {
-    this.router.navigate(['/profile', payload.side]);
-  }
-  ```
+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 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.
+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.
 
 ---
 
@@ -190,4 +164,4 @@ The library calls your backend at `POST {baseUrl}/profile/compare-full` with bod
 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`).
+Output is in `dist/profile-comparison-lib/` (FESM bundles, typings, package.json). Peer dependencies: Angular `^20.0.0`.