permisapi-client 0.3.0__tar.gz → 0.6.0__tar.gz

{permisapi_client-0.3.0 → permisapi_client-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: permisapi-client
-Version: 0.3.0
+Version: 0.6.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.3.0 → permisapi_client-0.6.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.3.0 → permisapi_client-0.6.0}/permisapi_client/__init__.py

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

{permisapi_client-0.3.0 → permisapi_client-0.6.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.6.0"
 
 
 def _raise_for_status(resp: httpx.Response) -> None:
@@ -130,6 +130,93 @@ class _PermitsResource:
             params["max_distance"] = max_distance
         return self._c._get(f"/v1/permits/{num_pa}/dvf", params=params or None)
 
+    def score_mdb(self, num_pa: str) -> dict[str, Any]:
+        """GET /v1/permits/{num_pa}/score : Score Opportunité MDB v0.1.
+
+        Plans Pro et superieurs uniquement (402 si Free / Explorer).
+        Retourne {num_pa, permit_id, score (0-100), tier (low/medium/
+        high/premium), components (7 signaux ponderes), weights,
+        version, method, dvf_matches_used, density_class}.
+
+        Algo : heuristique ponderee qui combine type permis, surface,
+        DVF voisin €/m², activite dep, demandeur (SCI vs promoteur),
+        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 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,
         *,
@@ -405,6 +492,45 @@ class _AsyncPermitsResource:
             params["max_distance"] = max_distance
         return await self._c._get(f"/v1/permits/{num_pa}/dvf", params=params or None)
 
+    async def score_mdb(self, num_pa: str) -> dict[str, Any]:
+        """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 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.3.0 → permisapi_client-0.6.0}/pyproject.toml

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

{permisapi_client-0.3.0 → permisapi_client-0.6.0}/tests/test_client.py

@@ -302,6 +302,28 @@ def test_permits_export_403_for_explorer_plan() -> None:
             client.permits.export()
 
 
+@respx.mock
+def test_permits_score_mdb() -> None:
+    respx.get(f"{BASE}/v1/permits/PC-1/score").respond(
+        json={"num_pa": "PC-1", "score": 78, "tier": "high", "components": {}}
+    )
+    with PermisAPI(api_key="pk_test_abc") as client:
+        result = client.permits.score_mdb("PC-1")
+    assert result["score"] == 78
+    assert result["tier"] == "high"
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_permits_score_mdb() -> None:
+    respx.get(f"{BASE}/v1/permits/PC-A/score").respond(
+        json={"num_pa": "PC-A", "score": 42, "tier": "medium"}
+    )
+    async with AsyncPermisAPI(api_key="pk_test_abc") as client:
+        result = await client.permits.score_mdb("PC-A")
+    assert result["score"] == 42
+
+
 @pytest.mark.asyncio
 @respx.mock
 async def test_async_permits_export() -> None: