From ac78bee74b705974cfc38dc66c5227ed70385524 Mon Sep 17 00:00:00 2001
From: Antoine <antoinevdp@live.fr>
Date: Mon, 1 Jun 2026 12:57:52 +0200
Subject: [PATCH] feat: add deterministic Apec query derivation

---
 src/job_research/apec/__init__.py         |  3 +++
 src/job_research/apec/query_derivation.py | 19 +++++++++++++++++
 tests/apec/test_query_derivation.py       | 26 +++++++++++++++++++++++
 3 files changed, 48 insertions(+)
 create mode 100644 src/job_research/apec/__init__.py
 create mode 100644 src/job_research/apec/query_derivation.py
 create mode 100644 tests/apec/test_query_derivation.py

diff --git a/src/job_research/apec/__init__.py b/src/job_research/apec/__init__.py
new file mode 100644
index 0000000..fd7653d
--- /dev/null
+++ b/src/job_research/apec/__init__.py
@@ -0,0 +1,3 @@
+from job_research.apec.query_derivation import derive_apec_queries
+
+__all__ = ["derive_apec_queries"]
diff --git a/src/job_research/apec/query_derivation.py b/src/job_research/apec/query_derivation.py
new file mode 100644
index 0000000..437acab
--- /dev/null
+++ b/src/job_research/apec/query_derivation.py
@@ -0,0 +1,19 @@
+from job_research.models import CandidateProfileOutput
+
+
+def derive_apec_queries(profile: CandidateProfileOutput) -> list[str]:
+    queries: list[str] = []
+    seen: set[str] = set()
+
+    for target_role in profile.target_roles:
+        query = target_role.strip()
+        if not query or query in seen:
+            continue
+
+        seen.add(query)
+        queries.append(query)
+
+        if len(queries) == 5:
+            break
+
+    return queries
diff --git a/tests/apec/test_query_derivation.py b/tests/apec/test_query_derivation.py
new file mode 100644
index 0000000..6f2f949
--- /dev/null
+++ b/tests/apec/test_query_derivation.py
@@ -0,0 +1,26 @@
+from job_research.apec.query_derivation import derive_apec_queries
+from job_research.models import CandidateProfileOutput
+
+
+def test_derive_apec_queries_preserves_order_dedupes_and_caps_at_five() -> None:
+    profile = CandidateProfileOutput(
+        target_roles=[
+            "Data Engineer",
+            "Analytics Engineer",
+            "Data Engineer",
+            "BI Engineer",
+            "Junior Data Platform Engineer",
+            "ML Engineer",
+            "Backend Engineer",
+        ]
+    )
+
+    queries = derive_apec_queries(profile)
+
+    assert queries == [
+        "Data Engineer",
+        "Analytics Engineer",
+        "BI Engineer",
+        "Junior Data Platform Engineer",
+        "ML Engineer",
+    ]