Readme + frontend graphs

README.md

@@ -1,5 +1,5 @@
 ---
-title: Pay Equity For Eu
+title: Pay Equity For EU
 emoji: 🐨
 colorFrom: purple
 colorTo: indigo
@@ -9,90 +9,106 @@ python_version: '3.12'
 app_file: main.py
 pinned: false
 license: apache-2.0
-short_description: Multilingual AI assistant to guarantee fair pay
+short_description: Know what you should earn, and what the law says you can ask.
+tags:
+  - build-small-hackathon
+  - backyard-ai
+  - gradio
+  - rag
+  - multilingual
+  - tiny-model
+  - tiny-titan
+  - off-brand
+  - nemotron
+  - pay-equity
+  - legal-tech
+  - denmark
 ---
 
 # Pay Equity for EU
 
-Multilingual Gradio Space for Danish users: **expected pay** (IDA lønstatistik)
-and **pay-transparency rights** (EU Directive 2023/970), grounded with citations.
+A grounded, multilingual chat assistant that answers two questions Danish
+graduates ask every job offer: **"What pay should I expect?"** and **"What does
+the law actually let me ask for?"**
 
-## Quick start
+## The problem
 
-```bash
-uv sync
-uv run python main.py
-```
+In Denmark, salary negotiation is famously opaque. New graduates rarely know
+what the market pays, and the data that *does* exist sits behind union paywalls
+in long PDFs. On top of that, the EU recently passed the **Pay Transparency
+Directive (2023/970)**, which gives every employee the right to ask their
+employer for pay information, gender pay-gap reports, and more. The catch: it's
+80 pages of legalese, in 24 languages, and almost no one has read it. So people
+sign offers without knowing either the number or the rights they already have.
 
-Requires a built vector index at `data/processed/index/` (see below). Backend
-details: [`src/backend/README.md`](src/backend/README.md).
+This app fixes both, in one chat.
 
-## Build the vector index
+## What it does
 
-Embed the corpus once (directive articles + IDA salary rows), then commit the
-output:
+- **Expected pay** — deterministic lookup over parsed IDA *lønstatistik*
+  (salary statistics from the engineers' union), broken down by sector,
+  experience, and role. No hallucinations: numbers come straight from the
+  union's published tables.
+- **Your rights** — RAG over the EU Pay Transparency Directive in EN / DA / FR,
+  with article-level citations on every claim (e.g. *"You can request the
+  average pay for your role broken down by gender (Art. 7(1))"*).
+- **Private document review** — session-only upload of a contract or payslip,
+  never persisted, never sent to a third-party API.
 
-```bash
-uv run python scripts/build_index.py   # GPU / ZeroGPU Space admin button
-```
-
-Produces `data/processed/index/index.faiss` + `chunks.jsonl`.
+Currently scoped to **IDA** (engineers / software graduates — the author and
+his friends). Djøf (law, business, economics, social science) is the obvious
+next union, with the same plumbing.
 
-### Refresh metadata only (no re-embed)
+## Hackathon track
 
-After changing `Chunk.metadata` mapping in `src/backend/indexing/ingest.py`:
-
-```bash
-uv run python scripts/refresh_metadata.py
-```
+**Backyard AI** — practical, problem-solving, runs on hardware you own, built
+for a real circle of people (Danish graduates job-hunting right now).
 
-Rewrites `chunks.jsonl` only; vectors stay unchanged. Re-embed if chunk ids or
-order changed.
+## Tech stack
 
-## Run the RAG benchmark
+| Layer | Choice | Why |
+|---|---|---|
+| Generation LLM | **Cohere Tiny Aya 3B** | Multilingual (EN/DA/FR), under the Tiny Titan 4B cap |
+| Swap-in LLM | OpenBMB MiniCPM3-4B | One-line swap via `LLMClient` interface |
+| Embeddings | **NVIDIA Nemotron-Embed 1B v2** | Strong multilingual retrieval, ungated |
+| Retrieval | FAISS IndexFlatIP + per-source top-k + Reciprocal Rank Fusion | Keeps salary numbers and legal text from drowning each other |
+| Runtime | Gradio Server + ZeroGPU on HF Spaces | Single `main.py`, FastAPI-style endpoints exposed alongside the chat UI |
+| Theme | Custom Scandinavian sage palette via `gr.themes.Soft` + Bricolage Grotesque / Inter | Goes well beyond default Gradio look |
 
-Offline evaluation of retrieval (and lightweight generation checks) against
-15 ground-truth questions in `scripts/eval/benchmark_questions.json`.
+All model revisions are pinned by SHA in `configs/models.yaml`. No `latest`.
 
-**Prerequisites:** committed `chunks.jsonl` plus a local `index.faiss`. If
-`index.faiss` is missing or a Git LFS pointer, rebuild it from the committed
-chunks (CPU-only, ~few minutes):
+Total parameter footprint: **~4B** (Tiny Aya 3B + Nemotron-Embed 1B), well
+under the 32B cap.
 
-```bash
-uv run python scripts/eval/build_local_index.py
-```
+## Why small models matter here
 
-**Run the benchmark:**
+Legal advice and salary numbers are exactly the domain where you don't want a
+big confident model to free-associate. Grounding the small model on parsed
+union tables and article-chunked directive text means every answer can be
+checked against a citation. A small, transparent stack is the *right* tool for
+"does this sentence come from the law or did the model make it up?"
 
-```bash
-# Full run: retrieval metrics + generation fact/citation checks (default k=5)
-uv run python scripts/eval/run_benchmark.py
+## Demo video
 
-# Retrieval only (faster)
-uv run python scripts/eval/run_benchmark.py --no-generation
+[Watch the demo](TODO_YOUTUBE_URL)
 
-# Custom top-k
-uv run python scripts/eval/run_benchmark.py --k 10
-```
+## Social post
 
-**Output:** human-readable summary on stdout + JSON report at
-`scripts/eval/results/benchmark_YYYYMMDD_HHMMSS.json`.
+[Read the post](TODO_SOCIAL_URL)
 
-**Metrics:** Recall@k, MRR, NDCG@k (retrieval); fact coverage and citation
-presence (generation). See [`scripts/eval/BENCHMARK_FINDINGS.md`](scripts/eval/BENCHMARK_FINDINGS.md)
-for the latest scored run and failure analysis.
+## Run it locally
 
-> **Note:** The benchmark script uses a single global FAISS top-k search, not
-> the production per-source + RRF fusion in `rag.py`. Use it to track embedding
-> quality; for end-to-end production behaviour, test via the Gradio UI or
-> `/chat` API.
+```bash
+uv sync
+uv run python main.py
+```
 
-## Data
+Requires a built vector index at `data/processed/index/`. See
+[`src/backend/README.md`](src/backend/README.md) for the RAG pipeline and
+[`scripts/eval/`](scripts/eval/) for the offline benchmark.
 
-| Path | Contents |
-|---|---|
-| `data/processed/directive/` | Parsed EU Directive 2023/970 |
-| `data/processed/lonstatistik/` | IDA + Djøf salary statistics ([README](data/processed/lonstatistik/README.md)) |
-| `data/processed/index/` | FAISS index + aligned `chunks.jsonl` |
+## Disclaimer
 
-Raw PDFs live under `data/raw/` (gitignored).
+This app surfaces public salary statistics and the published text of EU
+Directive 2023/970. It is **not legal advice**. For binding interpretation,
+talk to your union or a lawyer.

src/frontend/static/app.js

@@ -666,13 +666,13 @@ function bellCurveSVG(cell, ug, floor) {
     </div>`;
 }
 
-function gaugeSVG(pct) {
-  if (pct == null) return "";
-  const S = 150, r = 56, cx = S / 2, cy = S / 2, C = 2 * Math.PI * r;
-  const frac = Math.max(0, Math.min(100, pct)) / 100;
-  return `
-    <div class="chart-card chart-gauge">
-      <h4 class="chart-title">Your standing</h4>
+function standingCard(pct, target) {
+  if (pct == null && target == null) return "";
+  let inner = "";
+  if (pct != null) {
+    const S = 150, r = 56, cx = S / 2, cy = S / 2, C = 2 * Math.PI * r;
+    const frac = Math.max(0, Math.min(100, pct)) / 100;
+    inner += `
       <svg viewBox="0 0 ${S} ${S}" class="chart" role="img">
         <circle cx="${cx}" cy="${cy}" r="${r}" class="ga-track" />
         <circle cx="${cx}" cy="${cy}" r="${r}" class="ga-fill"
@@ -683,8 +683,17 @@ function gaugeSVG(pct) {
       </svg>
       <p class="chart-cap">Out of 100 comparable engineers, about <strong>${Math.round(
         pct
-      )}</strong> earn less than you.</p>
-    </div>`;
+      )}</strong> earn less than you.</p>`;
+  }
+  if (target != null) {
+    inner += `
+      <div class="standing-ask">
+        <div class="standing-ask-lbl">Typical pay to ask (2026)</div>
+        <div class="standing-ask-big">${dkk(target)}</div>
+        <div class="standing-ask-sub">based on IDA's expected pay rises</div>
+      </div>`;
+  }
+  return `<div class="chart-card chart-gauge"><h4 class="chart-title">Your standing</h4>${inner}</div>`;
 }
 
 function barsSVG(d, ug) {
@@ -739,14 +748,9 @@ function renderVisualDash(d) {
 
   html += `<div class="chart-grid">`;
   if (curveCell) html += bellCurveSVG(curveCell, ug, d.recommended_floor);
-  if (pct != null) html += gaugeSVG(pct);
+  html += standingCard(pct, d.projected_negotiation_target);
   html += `</div>`;
   html += barsSVG(d, ug);
-
-  if (d.projected_negotiation_target != null)
-    html += `<p class="chart-cap chart-cap-wide">A fair ask for 2026: <strong>${dkk(
-      d.projected_negotiation_target
-    )}</strong> — based on IDA's expected pay rises.</p>`;
   return html;
 }
 

src/frontend/static/styles.css

@@ -479,6 +479,12 @@ section { padding: var(--section-padding-y) 0; }
 .ga-big { fill: var(--color-ink); font-size: 30px; font-weight: 700; font-family: var(--font-display); }
 .ga-sub { fill: var(--color-text-muted); font-size: 12px; font-family: var(--font-sans); }
 
+/* highlighted "typical pay to ask" inside the standing card */
+.standing-ask { margin-top: var(--space-5); width: 100%; background: var(--color-sage-light); border: 1px solid var(--color-sage-deep); border-radius: var(--radius-md); padding: var(--space-4) var(--space-5); }
+.standing-ask-lbl { font-size: var(--text-xs); font-weight: var(--font-semibold); color: var(--color-text-secondary); text-transform: uppercase; letter-spacing: 0.04em; }
+.standing-ask-big { font-family: var(--font-display); font-size: var(--text-2xl); font-weight: var(--font-bold); color: var(--color-accent-dark); letter-spacing: -0.01em; line-height: 1.15; }
+.standing-ask-sub { font-size: var(--text-xs); color: var(--color-text-muted); }
+
 /* horizontal comparison bars */
 .vbar-wrap { position: relative; display: flex; flex-direction: column; gap: var(--space-4); padding-top: var(--space-5); }
 .vbar-row { display: flex; flex-direction: column; gap: 4px; }