permisapi-client 0.4.0__tar.gz → 0.7.0__tar.gz

{permisapi_client-0.4.0 → permisapi_client-0.7.0}/.gitignore

@@ -63,3 +63,6 @@ landing/out/
 # Post-piratage rotation (contient les nouvelles cles API en clair)
 secrets_NEW_KEYS.json
 scrape-downloads/
+
+# Local handoff bundle (assembled then zipped, not committed)
+handoff-bundle/

{permisapi_client-0.4.0 → permisapi_client-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: permisapi-client
-Version: 0.4.0
+Version: 0.7.0
 Summary: Client Python officiel pour PermisAPI : permis de construire France en API REST.
 Project-URL: Homepage, https://permisapi.fr
 Project-URL: Documentation, https://permisapi.fr/docs
@@ -63,6 +63,70 @@ for p in client.permits.iter_all(dep_code="75"):
     print(p["num_pa"])
 ```
 
+## Cross-ref Pro+ (DVF, Score MDB, PLU, Géorisques)
+
+```python
+# Top 5 transactions DVF voisines (5 ans glissants)
+dvf = client.permits.dvf("PC07404021K1", limit=5)
+for m in dvf["matches"]:
+    print(m["valeur_fonciere"], "EUR a", m["distance_m"], "m")
+
+# Score Opportunite Marchand de Biens v0.1 (note 0-100 + tier)
+score = client.permits.score_mdb("PC07404021K1")
+print(f"Score: {score['score']}/100 ({score['tier']})")
+
+# Zonage urbanisme PLU (constructible vs agricole vs naturelle)
+plu = client.permits.plu("PC07404021K1")
+if plu["has_plu"]:
+    z = plu["zonage"]
+    print(f"Zone {z['code']} - constructible: {z['constructible']}")
+
+# Georisques BRGM (inondation, seisme, argile, ICPE proches)
+risks = client.permits.risks("PC07404021K1")
+print(f"Risk score: {risks['risk_score']}/100 ({risks['risk_tier']})")
+for risk in risks["risks"]:
+    print(f"- {risk['label']} (PPR: {risk['has_ppr']})")
+
+# Feedback sur le Score MDB (alimente le training V1.0 ML)
+client.permits.score_feedback(
+    num_pa="PC07404021K1",
+    score_received=78,
+    tier_received="high",
+    useful=False,
+    accuracy="too_high",
+    comment="SCI familiale, pas un MDB. Le signal SCI=90 est trop generique.",
+    recommendation="Distinguer SCI familiale via volume de permis.",
+)
+```
+
+## Export bulk CSV (Business+)
+
+```python
+# Cap par defaut : 100k Business / 1M Enterprise
+csv_bytes = client.permits.export(
+    dep_code="33",
+    permit_type="PC_LOGEMENT",
+    date_from="2024-01-01",
+    max_rows=5000,
+)
+with open("bordeaux.csv", "wb") as f:
+    f.write(csv_bytes)
+```
+
+## MCP server (Claude / ChatGPT / Cursor)
+
+Le serveur MCP officiel (package separe `permisapi-mcp`) permet a Claude
+Desktop, Cursor et Windsurf d'appeler PermisAPI en langage naturel :
+
+```bash
+pip install permisapi-mcp
+```
+
+Configure ta cle dans le client MCP, puis demande directement :
+> *"Liste les permis de logement deposes a Bordeaux ce mois avec un score MDB > 70"*
+
+Voir [permisapi.fr/mcp](https://permisapi.fr/mcp) pour le setup complet.
+
 ## Async
 
 ```python

{permisapi_client-0.4.0 → permisapi_client-0.7.0}/README.md

@@ -35,6 +35,70 @@ for p in client.permits.iter_all(dep_code="75"):
     print(p["num_pa"])
 ```
 
+## Cross-ref Pro+ (DVF, Score MDB, PLU, Géorisques)
+
+```python
+# Top 5 transactions DVF voisines (5 ans glissants)
+dvf = client.permits.dvf("PC07404021K1", limit=5)
+for m in dvf["matches"]:
+    print(m["valeur_fonciere"], "EUR a", m["distance_m"], "m")
+
+# Score Opportunite Marchand de Biens v0.1 (note 0-100 + tier)
+score = client.permits.score_mdb("PC07404021K1")
+print(f"Score: {score['score']}/100 ({score['tier']})")
+
+# Zonage urbanisme PLU (constructible vs agricole vs naturelle)
+plu = client.permits.plu("PC07404021K1")
+if plu["has_plu"]:
+    z = plu["zonage"]
+    print(f"Zone {z['code']} - constructible: {z['constructible']}")
+
+# Georisques BRGM (inondation, seisme, argile, ICPE proches)
+risks = client.permits.risks("PC07404021K1")
+print(f"Risk score: {risks['risk_score']}/100 ({risks['risk_tier']})")
+for risk in risks["risks"]:
+    print(f"- {risk['label']} (PPR: {risk['has_ppr']})")
+
+# Feedback sur le Score MDB (alimente le training V1.0 ML)
+client.permits.score_feedback(
+    num_pa="PC07404021K1",
+    score_received=78,
+    tier_received="high",
+    useful=False,
+    accuracy="too_high",
+    comment="SCI familiale, pas un MDB. Le signal SCI=90 est trop generique.",
+    recommendation="Distinguer SCI familiale via volume de permis.",
+)
+```
+
+## Export bulk CSV (Business+)
+
+```python
+# Cap par defaut : 100k Business / 1M Enterprise
+csv_bytes = client.permits.export(
+    dep_code="33",
+    permit_type="PC_LOGEMENT",
+    date_from="2024-01-01",
+    max_rows=5000,
+)
+with open("bordeaux.csv", "wb") as f:
+    f.write(csv_bytes)
+```
+
+## MCP server (Claude / ChatGPT / Cursor)
+
+Le serveur MCP officiel (package separe `permisapi-mcp`) permet a Claude
+Desktop, Cursor et Windsurf d'appeler PermisAPI en langage naturel :
+
+```bash
+pip install permisapi-mcp
+```
+
+Configure ta cle dans le client MCP, puis demande directement :
+> *"Liste les permis de logement deposes a Bordeaux ce mois avec un score MDB > 70"*
+
+Voir [permisapi.fr/mcp](https://permisapi.fr/mcp) pour le setup complet.
+
 ## Async
 
 ```python

{permisapi_client-0.4.0 → permisapi_client-0.7.0}/permisapi_client/__init__.py

@@ -30,4 +30,4 @@ __all__ = [
     "PermisAPIValidationError",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.7.0"

{permisapi_client-0.4.0 → permisapi_client-0.7.0}/permisapi_client/client.py

@@ -13,7 +13,7 @@ from permisapi_client.exceptions import error_from_response
 
 DEFAULT_BASE_URL = "https://api.permisapi.fr"
 DEFAULT_TIMEOUT = 15.0
-USER_AGENT = "permisapi-client-python/0.1.0"
+USER_AGENT = "permisapi-client-python/0.7.0"
 
 
 def _raise_for_status(resp: httpx.Response) -> None:
@@ -138,12 +138,112 @@ class _PermitsResource:
         high/premium), components (7 signaux ponderes), weights,
         version, method, dvf_matches_used, density_class}.
 
-        Algo : heuristique ponderee qui combine type permit, surface,
+        Algo : heuristique ponderee qui combine type permis, surface,
         DVF voisin €/m², activite dep, demandeur (SCI vs promoteur),
-        coherence DVF/permit, densite INSEE.
+        coherence DVF/permis, densite INSEE.
         """
         return self._c._get(f"/v1/permits/{num_pa}/score")
 
+    def risks(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/risks : Georisques BRGM (commune-level).
+
+        Plans Pro et superieurs uniquement (402 si Free / Explorer). Source :
+        API Georisques (ministere Transition Ecologique + BRGM) live, pas de
+        cache V0.1, latence 200-1000ms typique.
+
+        Retourne {num_pa, comm_code, risk_score (0-100), risk_tier (low/
+        moderate/high/critical), risks: [{code, label, has_ppr, ppr_type}],
+        icpe_proches: [{nom, regime, distance_m, activite}], fetch_errors,
+        source, fetched_at, disclaimer}.
+
+        En cas d'erreur partielle (ex: ICPE OK mais /risques 500), retourne
+        ce qui marche + liste les endpoints qui ont fail dans `fetch_errors`.
+        """
+        return self._c._get(f"/v1/permits/{num_pa}/risks")
+
+    def plu(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/plu : zonage urbanisme PLU au point geocode.
+
+        Plans Pro et superieurs uniquement (402 si Free / Explorer). Source :
+        Geoportail de l'Urbanisme via apicarto.ign.fr (live API, latence
+        200-500ms typique).
+
+        Retourne {num_pa, lat, lng, has_plu, zonage : {code (UA/UB/AU/A/N..),
+        libelle, type_zone, constructible (bool), constructible_reason,
+        plu_revision_date, plu_partition}, other_zones, source, fetched_at}.
+
+        Si la commune n'a pas digitalise son PLU sur Geoportail (~20% des
+        communes FR), `has_plu=False` avec `not_covered_reason` explicite.
+        """
+        return self._c._get(f"/v1/permits/{num_pa}/plu")
+
+    def full_view(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/360 : vue agregee 6-en-1 en 1 appel HTTP.
+
+        Combine en 1 reponse : detail + sirene + dvf + score + plu + risks.
+        Equivalent fonctionnel de 6 calls separes mais en 1 round-trip,
+        avec parallelisation cote serveur des sub-fetches lents (PLU
+        apicarto + Risks BRGM).
+
+        Cout quota : 6 unites du quota mensuel pour Pro+, 1 unite pour
+        Free / Explorer (qui recoivent juste `detail`, autres champs `null`
+        avec `plan_required_for_full="pro"`). Le header de reponse
+        `X-RateLimit-Cost` confirme le cout decompte.
+
+        Best-effort : si une sous-feature echoue (timeout, 5xx tiers),
+        son champ vaut `null` et l'erreur est listee dans `fetch_errors`.
+        Les autres sous-features ne sont pas affectees.
+
+        Latence typique 5-7s (dominee par PLU + Risks live, paralleles).
+
+        Returns:
+            dict avec cles : num_pa, detail, sirene, dvf, score, plu,
+            risks, fetch_errors (list), subfetches_billed (int).
+            Si plan Free/Explorer : `plan_required_for_full="pro"` est
+            present et toutes les sous-features sauf detail sont null.
+        """
+        return self._c._get(f"/v1/permits/{num_pa}/360")
+
+    def score_feedback(
+        self,
+        *,
+        num_pa: str,
+        score_received: int,
+        tier_received: str,
+        useful: bool,
+        accuracy: str,
+        comment: str,
+        recommendation: str | None = None,
+    ) -> dict[str, Any]:
+        """POST /v1/score/feedback : envoyer un feedback sur un Score MDB.
+
+        Plans Pro et superieurs uniquement. Le feedback est stocke en DB
+        et un email est envoye au founder pour suivi rapide.
+
+        Args:
+            num_pa: identifiant du permis concerne
+            score_received: score 0-100 que tu as recu via /score
+            tier_received: "low" | "medium" | "high" | "premium"
+            useful: True si le score t'a ete utile
+            accuracy: "correct" | "too_high" | "too_low" | "wrong_signals"
+            comment: ton retour libre (1-2000 chars)
+            recommendation: optionnel, ce qui pourrait etre ameliore (1-2000 chars)
+
+        Returns:
+            {id, num_pa, email_sent, message}
+        """
+        body: dict[str, Any] = {
+            "num_pa": num_pa,
+            "score_received": score_received,
+            "tier_received": tier_received,
+            "useful": useful,
+            "accuracy": accuracy,
+            "comment": comment,
+        }
+        if recommendation is not None:
+            body["recommendation"] = recommendation
+        return self._c._post("/v1/score/feedback", json=body)
+
     def export(
         self,
         *,
@@ -423,6 +523,50 @@ class _AsyncPermitsResource:
         """GET /v1/permits/{num_pa}/score : version async. Plans Pro+ only."""
         return await self._c._get(f"/v1/permits/{num_pa}/score")
 
+    async def plu(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/plu : version async. Plans Pro+ only.
+        Voir _PermitsResource.plu pour la doc complete."""
+        return await self._c._get(f"/v1/permits/{num_pa}/plu")
+
+    async def risks(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/risks : version async. Plans Pro+ only.
+        Voir _PermitsResource.risks pour la doc complete."""
+        return await self._c._get(f"/v1/permits/{num_pa}/risks")
+
+    async def full_view(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/360 : version async. Vue agregee 6-en-1.
+
+        Cout quota : 6 unites pour Pro+, 1 unite pour Free / Explorer.
+        Le header `X-RateLimit-Cost` confirme le cout. Voir
+        _PermitsResource.full_view pour la doc complete.
+        """
+        return await self._c._get(f"/v1/permits/{num_pa}/360")
+
+    async def score_feedback(
+        self,
+        *,
+        num_pa: str,
+        score_received: int,
+        tier_received: str,
+        useful: bool,
+        accuracy: str,
+        comment: str,
+        recommendation: str | None = None,
+    ) -> dict[str, Any]:
+        """POST /v1/score/feedback : version async. Plans Pro+ only.
+        Voir _PermitsResource.score_feedback pour la doc complete."""
+        body: dict[str, Any] = {
+            "num_pa": num_pa,
+            "score_received": score_received,
+            "tier_received": tier_received,
+            "useful": useful,
+            "accuracy": accuracy,
+            "comment": comment,
+        }
+        if recommendation is not None:
+            body["recommendation"] = recommendation
+        return await self._c._post("/v1/score/feedback", json=body)
+
     async def export(
         self,
         *,

{permisapi_client-0.4.0 → permisapi_client-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "permisapi-client"
-version = "0.4.0"
+version = "0.7.0"
 description = "Client Python officiel pour PermisAPI : permis de construire France en API REST."
 readme = "README.md"
 requires-python = ">=3.9"

{permisapi_client-0.4.0 → permisapi_client-0.7.0}/tests/test_client.py

@@ -337,6 +337,56 @@ async def test_async_permits_export() -> None:
     assert b"PC-A,75" in result
 
 
+@respx.mock
+def test_permits_full_view_sync() -> None:
+    """Sync : full_view appelle GET /v1/permits/{num_pa}/360 et retourne
+    le payload agrege complet."""
+    respx.get(f"{BASE}/v1/permits/PC-360-001/360").respond(
+        json={
+            "num_pa": "PC-360-001",
+            "detail": {"num_pa": "PC-360-001", "dep_code": "75"},
+            "sirene": {"match": {"siren": "111222333"}},
+            "dvf": {"matches": []},
+            "score": {"score": 72, "tier": "high"},
+            "plu": {"zonage": {"code": "UA", "constructible": True}},
+            "risks": {"risk_tier": "low"},
+            "fetch_errors": [],
+            "subfetches_billed": 6,
+        }
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        view = client.permits.full_view("PC-360-001")
+    assert view["num_pa"] == "PC-360-001"
+    assert view["subfetches_billed"] == 6
+    assert view["score"]["tier"] == "high"
+    assert view["plu"]["zonage"]["constructible"] is True
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_permits_full_view() -> None:
+    """Async : full_view appelle GET /v1/permits/{num_pa}/360."""
+    respx.get(f"{BASE}/v1/permits/PC-FREE/360").respond(
+        json={
+            "num_pa": "PC-FREE",
+            "detail": {"num_pa": "PC-FREE"},
+            "sirene": None,
+            "dvf": None,
+            "score": None,
+            "plu": None,
+            "risks": None,
+            "fetch_errors": [],
+            "plan_required_for_full": "pro",
+            "subfetches_billed": 1,
+        }
+    )
+    async with AsyncPermisAPI(api_key="pk_test_abc") as client:
+        view = await client.permits.full_view("PC-FREE")
+    assert view["plan_required_for_full"] == "pro"
+    assert view["subfetches_billed"] == 1
+    assert view["sirene"] is None
+
+
 def test_custom_base_url() -> None:
     client = PermisAPI(api_key="pk_test_abc", base_url="http://localhost:8000/")
     assert client.base_url == "http://localhost:8000"