Viney Claude Opus 5 (1M context) commited on
Commit
64054ca
·
1 Parent(s): 2369ff0

docs: prospection plan, tasks 7-9

Browse files

Paid provider adapters (Explorium MCP handoff, Dropcontact, LinkedIn),
expiring intent signals, public holdings extraction with human confirmation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016XzekHxqiXutBW4gw3Arsx

docs/superpowers/plans/2026-08-29-prospection-buyside.md CHANGED
@@ -1619,4 +1619,825 @@ git commit -m "feat(prospection): cost-ordered enrichment waterfall with MX-only
1619
 
1620
  ---
1621
 
1622
- *(Le plan continue avec les tâches 7 à 14. Elles sont écrites dans la seconde moitié du document.)*
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1619
 
1620
  ---
1621
 
1622
+ ### Task 7 : adaptateurs des providers payants
1623
+
1624
+ **Files:**
1625
+ - Create: `prospection/enrich/explorium.py`, `prospection/enrich/dropcontact.py`, `prospection/enrich/linkedin.py`, `prospection/enrich/registry.py`
1626
+ - Test: `tests/test_prospection_providers.py`
1627
+
1628
+ **Interfaces:**
1629
+ - Consumes: `ContactProvider`, `ContactRecord` (tâche 6), `config.provider_enabled`.
1630
+ - Produces: `ExploriumProvider(handoff_path: Path | None = None)` (`cost_rank = 1`), `DropcontactProvider(client=None)` (`cost_rank = 2`), `LinkedInProvider(client=None)` (`cost_rank = 3`), `build_providers() -> list[ContactProvider]`, `TARGET_JOB_TITLES: tuple[str, ...]`.
1631
+
1632
+ **Note d'architecture — pourquoi Explorium est un adaptateur « handoff ».** Vibe Prospecting / Explorium n'est pas une API HTTP appelable depuis Python : c'est un serveur MCP piloté par l'agent. Un module Python ne peut pas l'invoquer. `ExploriumProvider` écrit donc une **demande** (`data/prospection_cache/explorium_requests/<no_amf>.json`) et lit une **réponse** déposée au même endroit par l'agent après exécution des outils MCP. Le provider ne fabrique aucune donnée : sans fichier de réponse, il renvoie `[]`. C'est le seul montage honnête, et il garde le pipeline testable hors ligne.
1633
+
1634
+ - [ ] **Step 1: Écrire le test qui échoue**
1635
+
1636
+ ```python
1637
+ # tests/test_prospection_providers.py
1638
+ """tests/test_prospection_providers.py — adaptateurs payants, tous opt-in."""
1639
+ from __future__ import annotations
1640
+
1641
+ import json
1642
+
1643
+ import pytest
1644
+
1645
+ from prospection.enrich import registry
1646
+ from prospection.enrich.dropcontact import DropcontactProvider
1647
+ from prospection.enrich.explorium import ExploriumProvider
1648
+ from prospection.enrich.linkedin import LinkedInProvider
1649
+
1650
+
1651
+ def _account(**overrides) -> dict:
1652
+ base = {"id": 1, "no_amf": "GP-19990001", "nom": "Boutique Gestion SAS",
1653
+ "site": "https://boutique-gestion.fr", "dirigeants": ["Marie Durand"]}
1654
+ return {**base, **overrides}
1655
+
1656
+
1657
+ @pytest.fixture(autouse=True)
1658
+ def all_providers_off(monkeypatch):
1659
+ for var in ("PROSPECTION_EXPLORIUM_ENABLED", "PROSPECTION_DROPCONTACT_ENABLED",
1660
+ "PROSPECTION_LINKEDIN_ENABLED"):
1661
+ monkeypatch.delenv(var, raising=False)
1662
+
1663
+
1664
+ def test_build_providers_yields_only_pattern_when_everything_is_off():
1665
+ providers = [p for p in registry.build_providers() if p.enabled()]
1666
+ assert [p.name for p in providers] == ["pattern"]
1667
+
1668
+
1669
+ def test_providers_are_ordered_by_cost():
1670
+ ranks = [p.cost_rank for p in registry.build_providers()]
1671
+ assert ranks == sorted(ranks)
1672
+ assert ranks[0] == 0
1673
+
1674
+
1675
+ def test_explorium_writes_a_request_and_returns_nothing_without_a_response(tmp_path):
1676
+ provider = ExploriumProvider(handoff_path=tmp_path)
1677
+ assert provider.find(_account()) == []
1678
+ request = json.loads((tmp_path / "GP-19990001.request.json").read_text(encoding="utf-8"))
1679
+ assert request["company_name"] == "Boutique Gestion SAS"
1680
+ assert request["country_code"] == "FR"
1681
+ assert "Head of Research" in request["job_titles"]
1682
+
1683
+
1684
+ def test_explorium_reads_an_agent_supplied_response(tmp_path):
1685
+ (tmp_path / "GP-19990001.response.json").write_text(json.dumps([{
1686
+ "prenom": "Marie", "nom": "Durand", "titre": "Directrice de la gestion",
1687
+ "email": "marie.durand@boutique-gestion.fr", "email_status": "verified",
1688
+ "linkedin_url": "https://www.linkedin.com/in/mdurand",
1689
+ }]), encoding="utf-8")
1690
+ records = ExploriumProvider(handoff_path=tmp_path).find(_account())
1691
+ assert len(records) == 1
1692
+ assert records[0].email_status == "verified"
1693
+ assert records[0].source == "explorium"
1694
+ assert records[0].is_generic == 0
1695
+
1696
+
1697
+ def test_dropcontact_maps_payload_to_contact_records():
1698
+ class _Client:
1699
+ def post(self, url, json=None, headers=None):
1700
+ class _R:
1701
+ status_code = 200
1702
+
1703
+ def raise_for_status(self):
1704
+ return None
1705
+
1706
+ def json(self):
1707
+ return {"data": [{"email": [{"email": "marie.durand@boutique-gestion.fr",
1708
+ "qualification": "nominative@pro"}],
1709
+ "first_name": "Marie", "last_name": "Durand",
1710
+ "job": "Gérante"}]}
1711
+ return _R()
1712
+
1713
+ records = DropcontactProvider(client=_Client()).find(_account())
1714
+ assert records[0].email == "marie.durand@boutique-gestion.fr"
1715
+ assert records[0].email_status == "verified"
1716
+ assert records[0].source == "dropcontact"
1717
+
1718
+
1719
+ def test_dropcontact_returns_empty_on_http_error():
1720
+ class _Client:
1721
+ def post(self, url, json=None, headers=None):
1722
+ raise RuntimeError("503")
1723
+
1724
+ assert DropcontactProvider(client=_Client()).find(_account()) == []
1725
+
1726
+
1727
+ def test_linkedin_provider_never_returns_an_email():
1728
+ class _Client:
1729
+ def get(self, url, params=None, headers=None):
1730
+ class _R:
1731
+ def raise_for_status(self):
1732
+ return None
1733
+
1734
+ def json(self):
1735
+ return {"members": [{"first_name": "Marie", "last_name": "Durand",
1736
+ "title": "Directrice de la gestion",
1737
+ "url": "https://www.linkedin.com/in/mdurand"}]}
1738
+ return _R()
1739
+
1740
+ records = LinkedInProvider(client=_Client()).find(_account())
1741
+ assert records[0].email is None
1742
+ assert records[0].email_status == "unknown"
1743
+ assert records[0].linkedin_url.startswith("https://www.linkedin.com/")
1744
+ ```
1745
+
1746
+ - [ ] **Step 2: Lancer le test pour vérifier qu'il échoue**
1747
+
1748
+ Run: `python -m pytest tests/test_prospection_providers.py -v`
1749
+ Expected: FAIL avec `ModuleNotFoundError: No module named 'prospection.enrich.registry'`
1750
+
1751
+ - [ ] **Step 3: Écrire `explorium.py`**
1752
+
1753
+ ```python
1754
+ # prospection/enrich/explorium.py
1755
+ """prospection/enrich/explorium.py — passerelle vers le MCP Vibe Prospecting.
1756
+
1757
+ Explorium n'est pas une API HTTP : c'est un serveur MCP piloté par l'agent.
1758
+ Ce provider écrit une demande sur disque et lit la réponse que l'agent y
1759
+ dépose après exécution des outils MCP. Sans réponse, il ne renvoie rien —
1760
+ il ne fabrique jamais de contact.
1761
+ """
1762
+ from __future__ import annotations
1763
+
1764
+ import json
1765
+ from datetime import datetime
1766
+ from pathlib import Path
1767
+
1768
+ from prospection import config
1769
+ from prospection.enrich.base import ContactProvider, ContactRecord
1770
+
1771
+ TARGET_JOB_TITLES = (
1772
+ "Chief Investment Officer", "Head of Research", "Directeur de la gestion",
1773
+ "Gérant de portefeuille", "Chief Operating Officer",
1774
+ )
1775
+
1776
+ _DEFAULT_HANDOFF = config.CACHE_DIR / "explorium"
1777
+
1778
+
1779
+ class ExploriumProvider(ContactProvider):
1780
+ name = "explorium"
1781
+ cost_rank = 1
1782
+
1783
+ def __init__(self, handoff_path: Path | None = None):
1784
+ self._path = Path(handoff_path or _DEFAULT_HANDOFF)
1785
+
1786
+ def find(self, account: dict) -> list[ContactRecord]:
1787
+ self._path.mkdir(parents=True, exist_ok=True)
1788
+ key = account["no_amf"]
1789
+ (self._path / f"{key}.request.json").write_text(
1790
+ json.dumps({
1791
+ "no_amf": key,
1792
+ "company_name": account.get("nom"),
1793
+ "company_domain": account.get("site"),
1794
+ "country_code": "FR",
1795
+ "job_titles": list(TARGET_JOB_TITLES),
1796
+ "contact_types": ["email"],
1797
+ }, ensure_ascii=False, indent=2),
1798
+ encoding="utf-8",
1799
+ )
1800
+
1801
+ response_file = self._path / f"{key}.response.json"
1802
+ if not response_file.exists():
1803
+ return []
1804
+
1805
+ now = datetime.utcnow().isoformat(timespec="seconds")
1806
+ records = []
1807
+ for entry in json.loads(response_file.read_text(encoding="utf-8")):
1808
+ status = entry.get("email_status", "unknown")
1809
+ records.append(ContactRecord(
1810
+ prenom=entry.get("prenom"), nom=entry.get("nom"),
1811
+ titre=entry.get("titre"), seniorite=entry.get("seniorite"),
1812
+ email=entry.get("email"), email_status=status,
1813
+ telephone=None, linkedin_url=entry.get("linkedin_url"),
1814
+ source=self.name, confidence=status, retrieved_at=now,
1815
+ is_generic=0,
1816
+ ))
1817
+ return records
1818
+ ```
1819
+
1820
+ - [ ] **Step 4: Écrire `dropcontact.py` et `linkedin.py`**
1821
+
1822
+ ```python
1823
+ # prospection/enrich/dropcontact.py
1824
+ """prospection/enrich/dropcontact.py — enrichissement algorithmique, RGPD-natif.
1825
+
1826
+ Dropcontact ne revend pas de base : il déduit et vérifie l'adresse à partir
1827
+ du nom et du domaine. La qualification `nominative@pro` est la seule qui
1828
+ autorise `verified`.
1829
+ """
1830
+ from __future__ import annotations
1831
+
1832
+ import os
1833
+ from datetime import datetime
1834
+
1835
+ from prospection.enrich.base import ContactProvider, ContactRecord
1836
+ from prospection.enrich.pattern import domain_of
1837
+
1838
+ API_URL = "https://api.dropcontact.io/batch"
1839
+
1840
+
1841
+ class DropcontactProvider(ContactProvider):
1842
+ name = "dropcontact"
1843
+ cost_rank = 2
1844
+
1845
+ def __init__(self, client=None):
1846
+ self._client = client
1847
+
1848
+ def _http(self):
1849
+ if self._client is not None:
1850
+ return self._client
1851
+ import httpx
1852
+
1853
+ return httpx.Client(timeout=60.0)
1854
+
1855
+ def find(self, account: dict) -> list[ContactRecord]:
1856
+ domain = domain_of(account.get("site"))
1857
+ names = account.get("dirigeants") or []
1858
+ if not (domain and names):
1859
+ return []
1860
+
1861
+ payload = {"data": [
1862
+ {"first_name": n.split()[0], "last_name": n.split()[-1], "website": domain}
1863
+ for n in names if len(n.split()) >= 2
1864
+ ], "siren": False, "language": "fr"}
1865
+
1866
+ try:
1867
+ response = self._http().post(
1868
+ API_URL, json=payload,
1869
+ headers={"X-Access-Token": os.getenv("PROSPECTION_DROPCONTACT_API_KEY", ""),
1870
+ "Content-Type": "application/json"},
1871
+ )
1872
+ response.raise_for_status()
1873
+ rows = response.json().get("data") or []
1874
+ except Exception:
1875
+ return []
1876
+
1877
+ now = datetime.utcnow().isoformat(timespec="seconds")
1878
+ records = []
1879
+ for row in rows:
1880
+ emails = row.get("email") or []
1881
+ if not emails:
1882
+ continue
1883
+ best = emails[0]
1884
+ status = "verified" if best.get("qualification") == "nominative@pro" else "probable"
1885
+ records.append(ContactRecord(
1886
+ prenom=row.get("first_name"), nom=row.get("last_name"),
1887
+ titre=row.get("job"), seniorite=None, email=best.get("email"),
1888
+ email_status=status, telephone=None, linkedin_url=row.get("linkedin"),
1889
+ source=self.name, confidence=status, retrieved_at=now, is_generic=0,
1890
+ ))
1891
+ return records
1892
+ ```
1893
+
1894
+ ```python
1895
+ # prospection/enrich/linkedin.py
1896
+ """prospection/enrich/linkedin.py — identification de personnes, jamais d'email.
1897
+
1898
+ Adaptateur optionnel et remplaçable (Coresignal ou Scrapingdog selon
1899
+ PROSPECTION_LINKEDIN_PROVIDER). Proxycurl a fermé le 4 juillet 2025 après
1900
+ le procès LinkedIn : aucune dépendance dure n'est acceptable ici. Ce
1901
+ provider sert uniquement à trouver *qui* occupe le poste ; l'adresse vient
1902
+ d'un autre étage du waterfall.
1903
+ """
1904
+ from __future__ import annotations
1905
+
1906
+ import os
1907
+ from datetime import datetime
1908
+
1909
+ from prospection.enrich.base import ContactProvider, ContactRecord
1910
+ from prospection.enrich.pattern import domain_of
1911
+
1912
+ _ENDPOINTS = {
1913
+ "coresignal": "https://api.coresignal.com/cdapi/v1/linkedin/member/search/filter",
1914
+ "scrapingdog": "https://api.scrapingdog.com/linkedin",
1915
+ }
1916
+
1917
+
1918
+ class LinkedInProvider(ContactProvider):
1919
+ name = "linkedin"
1920
+ cost_rank = 3
1921
+
1922
+ def __init__(self, client=None):
1923
+ self._client = client
1924
+
1925
+ def _http(self):
1926
+ if self._client is not None:
1927
+ return self._client
1928
+ import httpx
1929
+
1930
+ return httpx.Client(timeout=45.0)
1931
+
1932
+ def find(self, account: dict) -> list[ContactRecord]:
1933
+ vendor = os.getenv("PROSPECTION_LINKEDIN_PROVIDER", "").strip().lower()
1934
+ url = _ENDPOINTS.get(vendor)
1935
+ domain = domain_of(account.get("site"))
1936
+ if not (url and domain):
1937
+ return []
1938
+
1939
+ try:
1940
+ response = self._http().get(
1941
+ url,
1942
+ params={"company_website": domain, "country": "France"},
1943
+ headers={"Authorization": f"Bearer {os.getenv('PROSPECTION_LINKEDIN_API_KEY', '')}"},
1944
+ )
1945
+ response.raise_for_status()
1946
+ members = response.json().get("members") or []
1947
+ except Exception:
1948
+ return []
1949
+
1950
+ now = datetime.utcnow().isoformat(timespec="seconds")
1951
+ return [
1952
+ ContactRecord(
1953
+ prenom=m.get("first_name"), nom=m.get("last_name"),
1954
+ titre=m.get("title"), seniorite=None,
1955
+ email=None, email_status="unknown", telephone=None,
1956
+ linkedin_url=m.get("url"), source=self.name,
1957
+ confidence="unknown", retrieved_at=now, is_generic=0,
1958
+ )
1959
+ for m in members
1960
+ ]
1961
+ ```
1962
+
1963
+ - [ ] **Step 5: Écrire `registry.py`**
1964
+
1965
+ ```python
1966
+ # prospection/enrich/registry.py
1967
+ """prospection/enrich/registry.py — assemblage du waterfall dans l'ordre de coût."""
1968
+ from __future__ import annotations
1969
+
1970
+ from prospection.enrich.dropcontact import DropcontactProvider
1971
+ from prospection.enrich.explorium import ExploriumProvider
1972
+ from prospection.enrich.linkedin import LinkedInProvider
1973
+ from prospection.enrich.pattern import PatternProvider
1974
+
1975
+
1976
+ def build_providers() -> list:
1977
+ providers = [PatternProvider(), ExploriumProvider(), DropcontactProvider(),
1978
+ LinkedInProvider()]
1979
+ return sorted(providers, key=lambda p: p.cost_rank)
1980
+ ```
1981
+
1982
+ - [ ] **Step 6: Lancer les tests**
1983
+
1984
+ Run: `python -m pytest tests/test_prospection_providers.py tests/test_prospection_waterfall.py -v`
1985
+ Expected: PASS, 15 tests
1986
+
1987
+ - [ ] **Step 7: Commit**
1988
+
1989
+ ```bash
1990
+ git add prospection/enrich/ tests/test_prospection_providers.py
1991
+ git commit -m "feat(prospection): opt-in Explorium handoff, Dropcontact and LinkedIn adapters"
1992
+ ```
1993
+
1994
+ ---
1995
+
1996
+ ### Task 8 : signaux d'intention
1997
+
1998
+ **Files:**
1999
+ - Create: `prospection/sources/signals.py`
2000
+ - Test: `tests/test_prospection_signals.py`
2001
+
2002
+ **Interfaces:**
2003
+ - Consumes: `config.SIGNAL_WEIGHTS`, `prospects_db.add_signal`.
2004
+ - Produces: `signal_row(account_id: int, kind: str, label: str, url: str, observed_on: date) -> dict`, `licence_signal(account: dict, today: date) -> dict | None`, `scan_careers_page(account: dict, today: date, client=None) -> list[dict]`, `CAREER_PATHS: tuple[str, ...]`, `JOB_KEYWORDS: tuple[str, ...]`.
2005
+
2006
+ **Spike d'abord (bloquant, 30 minutes max).** La spec marque la couverture des SGP par l'API France Travail comme non vérifiée. Sonder avant d'écrire : si la couverture est bonne, ajouter un second collecteur dans un commit séparé ; sinon s'en tenir au repli page carrières, qui est ce que cette tâche implémente. **Le score reste calculable avec zéro signal** — la composante vaut alors 0, rien ne bloque.
2007
+
2008
+ - [ ] **Step 1: Écrire le test qui échoue**
2009
+
2010
+ ```python
2011
+ # tests/test_prospection_signals.py
2012
+ """tests/test_prospection_signals.py — signaux d'intention et leur expiration."""
2013
+ from __future__ import annotations
2014
+
2015
+ from datetime import date
2016
+
2017
+ from prospection.sources import signals
2018
+
2019
+
2020
+ def _account(**overrides) -> dict:
2021
+ base = {"id": 1, "site": "https://boutique-gestion.fr", "date_agrement": "2019-03-01"}
2022
+ return {**base, **overrides}
2023
+
2024
+
2025
+ class _FakeClient:
2026
+ def __init__(self, pages: dict):
2027
+ self._pages = pages
2028
+
2029
+ def get(self, url, headers=None, follow_redirects=True):
2030
+ class _R:
2031
+ def __init__(self, text, status):
2032
+ self.text = text
2033
+ self.status_code = status
2034
+
2035
+ def raise_for_status(self):
2036
+ if self.status_code >= 400:
2037
+ raise RuntimeError(self.status_code)
2038
+
2039
+ body = self._pages.get(url)
2040
+ return _R(body or "", 200 if body else 404)
2041
+
2042
+
2043
+ def test_signal_row_derives_expiry_from_the_configured_ttl():
2044
+ row = signals.signal_row(1, "job_posting", "Analyste data", "https://x.fr/job",
2045
+ date(2026, 8, 1))
2046
+ assert row["weight"] == 15
2047
+ assert row["expires_at"] == "2026-09-30"
2048
+
2049
+
2050
+ def test_licence_signal_fires_only_within_eighteen_months():
2051
+ recent = signals.licence_signal(_account(date_agrement="2025-06-01"), date(2026, 8, 29))
2052
+ old = signals.licence_signal(_account(date_agrement="2019-03-01"), date(2026, 8, 29))
2053
+ assert recent["type"] == "recent_licence"
2054
+ assert old is None
2055
+
2056
+
2057
+ def test_scan_careers_page_detects_a_research_hire():
2058
+ client = _FakeClient({
2059
+ "https://boutique-gestion.fr/carrieres":
2060
+ "<html><body><a href='/offres/1'>Analyste financier data</a></body></html>",
2061
+ })
2062
+ found = signals.scan_careers_page(_account(), date(2026, 8, 29), client=client)
2063
+ assert len(found) == 1
2064
+ assert found[0]["type"] == "job_posting"
2065
+ assert found[0]["url"] == "https://boutique-gestion.fr/carrieres"
2066
+
2067
+
2068
+ def test_scan_careers_page_ignores_unrelated_roles():
2069
+ client = _FakeClient({
2070
+ "https://boutique-gestion.fr/carrieres":
2071
+ "<html><body><a href='/offres/2'>Assistant administratif</a></body></html>",
2072
+ })
2073
+ assert signals.scan_careers_page(_account(), date(2026, 8, 29), client=client) == []
2074
+
2075
+
2076
+ def test_scan_careers_page_survives_every_path_missing():
2077
+ assert signals.scan_careers_page(_account(), date(2026, 8, 29),
2078
+ client=_FakeClient({})) == []
2079
+ ```
2080
+
2081
+ - [ ] **Step 2: Lancer le test pour vérifier qu'il échoue**
2082
+
2083
+ Run: `python -m pytest tests/test_prospection_signals.py -v`
2084
+ Expected: FAIL avec `ImportError: cannot import name 'signals'`
2085
+
2086
+ - [ ] **Step 3: Écrire l'implémentation minimale**
2087
+
2088
+ ```python
2089
+ # prospection/sources/signals.py
2090
+ """prospection/sources/signals.py — signaux d'intention datés et périssables.
2091
+
2092
+ Un signal absent coûte des points, il ne bloque rien : le pipeline reste
2093
+ fonctionnel avec zéro signal collecté.
2094
+ """
2095
+ from __future__ import annotations
2096
+
2097
+ import re
2098
+ from datetime import date, datetime, timedelta
2099
+
2100
+ from prospection import config
2101
+
2102
+ CAREER_PATHS = ("/carrieres", "/carriere", "/nous-rejoindre", "/recrutement", "/jobs")
2103
+
2104
+ JOB_KEYWORDS = ("analyste", "analyst", "data", "quantitatif", "quant",
2105
+ "gérant", "gerant", "research", "recherche", "esg")
2106
+
2107
+ _TAG_RE = re.compile(r"<[^>]+>")
2108
+ _RECENT_LICENCE_DAYS = 548 # 18 mois
2109
+
2110
+
2111
+ def signal_row(account_id: int, kind: str, label: str, url: str,
2112
+ observed_on: date) -> dict:
2113
+ weight, ttl_days = config.SIGNAL_WEIGHTS[kind]
2114
+ return {
2115
+ "account_id": account_id, "type": kind, "label": label, "url": url,
2116
+ "observed_at": observed_on.isoformat(), "weight": weight,
2117
+ "expires_at": (observed_on + timedelta(days=ttl_days)).isoformat(),
2118
+ }
2119
+
2120
+
2121
+ def licence_signal(account: dict, today: date) -> dict | None:
2122
+ raw = account.get("date_agrement")
2123
+ if not raw:
2124
+ return None
2125
+ try:
2126
+ granted = datetime.fromisoformat(raw).date()
2127
+ except ValueError:
2128
+ return None
2129
+ if (today - granted).days > _RECENT_LICENCE_DAYS:
2130
+ return None
2131
+ return signal_row(account["id"], "recent_licence",
2132
+ f"Agrément AMF du {raw}", account.get("site") or "", today)
2133
+
2134
+
2135
+ def scan_careers_page(account: dict, today: date, client=None) -> list[dict]:
2136
+ site = (account.get("site") or "").rstrip("/")
2137
+ if not site:
2138
+ return []
2139
+ if client is None:
2140
+ import httpx
2141
+
2142
+ client = httpx.Client(timeout=20.0)
2143
+
2144
+ for path in CAREER_PATHS:
2145
+ url = f"{site}{path}"
2146
+ try:
2147
+ response = client.get(url, headers={"User-Agent": "amplegest-prospection/1.0"},
2148
+ follow_redirects=True)
2149
+ response.raise_for_status()
2150
+ except Exception:
2151
+ continue
2152
+ text = _TAG_RE.sub(" ", response.text).lower()
2153
+ hit = next((k for k in JOB_KEYWORDS if k in text), None)
2154
+ if hit:
2155
+ return [signal_row(account["id"], "job_posting",
2156
+ f"Offre mentionnant « {hit} »", url, today)]
2157
+ return []
2158
+ ```
2159
+
2160
+ - [ ] **Step 4: Lancer le test pour vérifier qu'il passe**
2161
+
2162
+ Run: `python -m pytest tests/test_prospection_signals.py -v`
2163
+ Expected: PASS, 5 tests
2164
+
2165
+ - [ ] **Step 5: Commit**
2166
+
2167
+ ```bash
2168
+ git add prospection/sources/signals.py tests/test_prospection_signals.py
2169
+ git commit -m "feat(prospection): expiring intent signals from careers pages and licence dates"
2170
+ ```
2171
+
2172
+ ---
2173
+
2174
+ ### Task 9 : fonds gérés et positions publiques
2175
+
2176
+ **Files:**
2177
+ - Create: `prospection/sources/geco_funds.py`, `prospection/sources/holdings.py`, `prospection/sources/ticker_aliases.py`
2178
+ - Test: `tests/test_prospection_holdings.py`, `tests/fixtures/reporting_mensuel.pdf`
2179
+
2180
+ **Interfaces:**
2181
+ - Consumes: `prospects_db.upsert_holding` / `confirm_holding` / `confirmed_holdings`.
2182
+ - Produces: `has_equity_funds(account: dict) -> bool` (`geco_funds`), `discover_report_urls(account: dict, client=None) -> list[str]` , `extract_holdings(pdf_path: Path, source_url: str) -> list[dict]`, `resolve_ticker(label: str) -> str | None`, `evidence_level(account_id: int) -> str` (`holdings.py`), `ALIASES: dict[str, str]` (`ticker_aliases.py`).
2183
+
2184
+ `evidence_level` renvoie `"holdings_verified"`, `"universe_inferred"` ou `"no_evidence"` — c'est la valeur qui choisit le gabarit d'email en tâche 11.
2185
+
2186
+ **Spike d'abord (bloquant, 30 minutes max).** La spec marque l'export GECO par SGP comme non vérifié. Sonder `geco.amf-france.org` : s'il existe un export automatisable, `has_equity_funds` le consomme ; sinon il retombe sur `libelle_type_activite` du CSV AMF, déjà en base — c'est le repli que cette tâche implémente.
2187
+
2188
+ - [ ] **Step 1: Générer la fixture PDF**
2189
+
2190
+ ```bash
2191
+ python - <<'PY'
2192
+ from pathlib import Path
2193
+ from fpdf import FPDF
2194
+ pdf = FPDF()
2195
+ pdf.add_page()
2196
+ pdf.set_font("Helvetica", size=11)
2197
+ for line in ["FONDS ACTIONS INTERNATIONALES - Reporting mensuel au 31/07/2026",
2198
+ "Principales lignes du portefeuille",
2199
+ "Microsoft Corp 5,4%",
2200
+ "NVIDIA Corp 4,8%",
2201
+ "Air Liquide SA 3,1%"]:
2202
+ pdf.cell(0, 7, line, new_x="LMARGIN", new_y="NEXT")
2203
+ Path("tests/fixtures").mkdir(parents=True, exist_ok=True)
2204
+ pdf.output("tests/fixtures/reporting_mensuel.pdf")
2205
+ PY
2206
+ ```
2207
+
2208
+ - [ ] **Step 2: Écrire le test qui échoue**
2209
+
2210
+ ```python
2211
+ # tests/test_prospection_holdings.py
2212
+ """tests/test_prospection_holdings.py — positions publiques et niveau de preuve."""
2213
+ from __future__ import annotations
2214
+
2215
+ from pathlib import Path
2216
+
2217
+ import pytest
2218
+
2219
+ from prospection.sources import geco_funds, holdings
2220
+ from prospection.store import prospects_db as db
2221
+
2222
+ FIXTURE = Path(__file__).parent / "fixtures" / "reporting_mensuel.pdf"
2223
+
2224
+
2225
+ @pytest.fixture(autouse=True)
2226
+ def tmp_db(tmp_path, monkeypatch):
2227
+ monkeypatch.setattr(db, "DB_PATH", tmp_path / "prospects.db")
2228
+ monkeypatch.setattr(holdings, "DB_PATH", tmp_path / "prospects.db", raising=False)
2229
+ db.init_db()
2230
+
2231
+
2232
+ def _account_id() -> int:
2233
+ return db.upsert_account({"no_amf": "GP-19990001", "nom": "Boutique Gestion SAS",
2234
+ "site": "https://boutique-gestion.fr", "statut": "vivant",
2235
+ "independante": 1})
2236
+
2237
+
2238
+ def test_has_equity_funds_reads_the_amf_activity_label():
2239
+ assert geco_funds.has_equity_funds({"type_activite": "Actions"}) is True
2240
+ assert geco_funds.has_equity_funds({"type_activite": "Monétaire"}) is False
2241
+
2242
+
2243
+ def test_extract_holdings_reads_lines_and_weights():
2244
+ rows = holdings.extract_holdings(FIXTURE, "https://x.fr/r.pdf")
2245
+ labels = {r["raw_label"]: r["weight_pct"] for r in rows}
2246
+ assert labels["Microsoft Corp"] == 5.4
2247
+ assert labels["NVIDIA Corp"] == 4.8
2248
+
2249
+
2250
+ def test_extract_holdings_never_marks_a_row_verified():
2251
+ rows = holdings.extract_holdings(FIXTURE, "https://x.fr/r.pdf")
2252
+ assert rows
2253
+ assert all(r["confidence"] == "probable" for r in rows)
2254
+ assert all(r["confirmed_at"] is None for r in rows)
2255
+
2256
+
2257
+ def test_resolve_ticker_maps_known_labels_and_gives_up_otherwise():
2258
+ assert holdings.resolve_ticker("Microsoft Corp") == "MSFT"
2259
+ assert holdings.resolve_ticker("Air Liquide SA") is None
2260
+
2261
+
2262
+ def test_evidence_level_requires_a_confirmed_edgar_holding():
2263
+ account_id = _account_id()
2264
+ holding_id = db.upsert_holding({"account_id": account_id, "fund_name": "Fonds A",
2265
+ "raw_label": "Microsoft Corp", "ticker": "MSFT",
2266
+ "weight_pct": 5.4, "as_of": "2026-07-31",
2267
+ "source_url": "https://x.fr/r.pdf",
2268
+ "confidence": "probable"})
2269
+ assert holdings.evidence_level(account_id) == "universe_inferred"
2270
+ db.confirm_holding(holding_id, "2026-08-29T09:00:00")
2271
+ assert holdings.evidence_level(account_id) == "holdings_verified"
2272
+
2273
+
2274
+ def test_evidence_level_is_no_evidence_without_any_holding():
2275
+ assert holdings.evidence_level(_account_id()) == "no_evidence"
2276
+
2277
+
2278
+ def test_discover_report_urls_returns_empty_when_every_path_is_missing():
2279
+ class _Client:
2280
+ def get(self, url, headers=None, follow_redirects=True):
2281
+ raise RuntimeError("404")
2282
+
2283
+ assert holdings.discover_report_urls({"site": "https://x.fr"}, client=_Client()) == []
2284
+ ```
2285
+
2286
+ - [ ] **Step 3: Lancer le test pour vérifier qu'il échoue**
2287
+
2288
+ Run: `python -m pytest tests/test_prospection_holdings.py -v`
2289
+ Expected: FAIL avec `ImportError: cannot import name 'geco_funds'`
2290
+
2291
+ - [ ] **Step 4: Écrire les trois modules**
2292
+
2293
+ ```python
2294
+ # prospection/sources/ticker_aliases.py
2295
+ """prospection/sources/ticker_aliases.py — table d'alias curée, libellé -> ticker EDGAR.
2296
+
2297
+ Volontairement petite et manuelle. Une correspondance devinée produirait une
2298
+ personnalisation fausse dans un email : mieux vaut ne rien dire.
2299
+ """
2300
+ from __future__ import annotations
2301
+
2302
+ ALIASES: dict[str, str] = {
2303
+ "apple": "AAPL",
2304
+ "advanced micro devices": "AMD",
2305
+ "alphabet": "GOOGL",
2306
+ "google": "GOOGL",
2307
+ "microsoft": "MSFT",
2308
+ "nvidia": "NVDA",
2309
+ "tesla": "TSLA",
2310
+ "amazon": "AMZN",
2311
+ "meta platforms": "META",
2312
+ "broadcom": "AVGO",
2313
+ "eli lilly": "LLY",
2314
+ "visa": "V",
2315
+ "netflix": "NFLX",
2316
+ "salesforce": "CRM",
2317
+ "adobe": "ADBE",
2318
+ }
2319
+ ```
2320
+
2321
+ ```python
2322
+ # prospection/sources/geco_funds.py
2323
+ """prospection/sources/geco_funds.py — exposition actions déclarée.
2324
+
2325
+ Repli documenté : l'export GECO par SGP n'étant pas confirmé comme
2326
+ automatisable, la poche actions se lit dans `libelle_type_activite` du CSV
2327
+ AMF, déjà en base.
2328
+ """
2329
+ from __future__ import annotations
2330
+
2331
+ _EQUITY_LABELS = ("action", "diversifi", "internationa", "monde", "amérique", "amerique")
2332
+
2333
+
2334
+ def has_equity_funds(account: dict) -> bool:
2335
+ label = (account.get("type_activite") or "").lower()
2336
+ return any(marker in label for marker in _EQUITY_LABELS)
2337
+ ```
2338
+
2339
+ ```python
2340
+ # prospection/sources/holdings.py
2341
+ """prospection/sources/holdings.py — positions publiées et niveau de preuve.
2342
+
2343
+ Rien ne passe en `verified` sans confirmation humaine explicite : le
2344
+ validateur de rédaction ne voit jamais une ligne non confirmée.
2345
+ """
2346
+ from __future__ import annotations
2347
+
2348
+ import re
2349
+ from pathlib import Path
2350
+
2351
+ from prospection.sources.ticker_aliases import ALIASES
2352
+ from prospection.store import prospects_db as db
2353
+
2354
+ REPORT_PATHS = ("/reporting", "/nos-fonds", "/documentation", "/fonds", "/publications")
2355
+
2356
+ _LINE_RE = re.compile(r"^(?P<label>[A-Za-zÀ-ÿ0-9 .&'\-]{3,60}?)\s+(?P<weight>\d{1,2}[.,]\d)\s*%$")
2357
+
2358
+
2359
+ def discover_report_urls(account: dict, client=None) -> list[str]:
2360
+ site = (account.get("site") or "").rstrip("/")
2361
+ if not site:
2362
+ return []
2363
+ if client is None:
2364
+ import httpx
2365
+
2366
+ client = httpx.Client(timeout=20.0)
2367
+
2368
+ found = []
2369
+ for path in REPORT_PATHS:
2370
+ url = f"{site}{path}"
2371
+ try:
2372
+ response = client.get(url, headers={"User-Agent": "amplegest-prospection/1.0"},
2373
+ follow_redirects=True)
2374
+ response.raise_for_status()
2375
+ except Exception:
2376
+ continue
2377
+ found.append(url)
2378
+ return found
2379
+
2380
+
2381
+ def extract_holdings(pdf_path: Path, source_url: str) -> list[dict]:
2382
+ import pdfplumber
2383
+
2384
+ rows: list[dict] = []
2385
+ with pdfplumber.open(str(pdf_path)) as pdf:
2386
+ lines = [l.strip() for page in pdf.pages
2387
+ for l in (page.extract_text() or "").splitlines()]
2388
+
2389
+ for line in lines:
2390
+ match = _LINE_RE.match(line)
2391
+ if not match:
2392
+ continue
2393
+ label = match.group("label").strip()
2394
+ rows.append({
2395
+ "fund_name": None,
2396
+ "raw_label": label,
2397
+ "ticker": resolve_ticker(label),
2398
+ "weight_pct": float(match.group("weight").replace(",", ".")),
2399
+ "as_of": None,
2400
+ "source_url": source_url,
2401
+ "confidence": "probable",
2402
+ "confirmed_at": None,
2403
+ })
2404
+ return rows
2405
+
2406
+
2407
+ def resolve_ticker(label: str) -> str | None:
2408
+ lowered = label.lower()
2409
+ for alias, ticker in ALIASES.items():
2410
+ if alias in lowered:
2411
+ return ticker
2412
+ return None
2413
+
2414
+
2415
+ def evidence_level(account_id: int) -> str:
2416
+ confirmed = [h for h in db.confirmed_holdings(account_id) if h.get("ticker")]
2417
+ if confirmed:
2418
+ return "holdings_verified"
2419
+ account = next((a for a in db.list_accounts() if a["id"] == account_id), None)
2420
+ with db.connect() as conn:
2421
+ any_holding = conn.execute(
2422
+ "SELECT 1 FROM holdings WHERE account_id=? LIMIT 1", (account_id,)
2423
+ ).fetchone()
2424
+ if any_holding or (account and account.get("tier") in (1, 2)):
2425
+ return "universe_inferred"
2426
+ return "no_evidence"
2427
+ ```
2428
+
2429
+ - [ ] **Step 5: Lancer le test pour vérifier qu'il passe**
2430
+
2431
+ Run: `python -m pytest tests/test_prospection_holdings.py -v`
2432
+ Expected: PASS, 7 tests
2433
+
2434
+ - [ ] **Step 6: Commit**
2435
+
2436
+ ```bash
2437
+ git add prospection/sources/geco_funds.py prospection/sources/holdings.py prospection/sources/ticker_aliases.py tests/test_prospection_holdings.py tests/fixtures/reporting_mensuel.pdf
2438
+ git commit -m "feat(prospection): public holdings extraction gated behind human confirmation"
2439
+ ```
2440
+
2441
+ ---
2442
+
2443
+ *(Tâches 10 à 14 : suite du document.)*