Metadata-Version: 2.4
Name: piilot-pack-fropendata
Version: 0.1.3
Summary: Connecteur Open Data France — SIRENE, INPI, BAN, Bodacc, geo et recherche entreprises pour enrichir clients et surveiller portefeuille
Author-email: Kinetics Consulting V2 <contact@piilot.ai>
License-Expression: Apache-2.0
Project-URL: homepage, https://github.com/Kinetics-Consulting-V2/piilot-pack-fropendata
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: piilot-sdk<1.0.0,>=0.7.0
Requires-Dist: fastapi>=0.115
Requires-Dist: langchain-core>=0.3
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: pydantic<3.0,>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: black>=25.0; extra == "dev"
Dynamic: license-file

# piilot-pack-fr-opendata

> Plugin Piilot qui agrège **6 APIs gouvernementales françaises** pour
> enrichir vos fiches clients, normaliser les adresses, et surveiller
> les annonces juridiques de votre portefeuille.

| Package | Registry | Version |
|---|---|---|
| `piilot-pack-fropendata` | [PyPI](https://pypi.org/project/piilot-pack-fropendata/) | 0.1.0 |
| `piilot-pack-fropendata-ui` | [npm](https://www.npmjs.com/package/piilot-pack-fropendata-ui) | 0.1.0 |

---

## APIs couvertes

| API | Auth | Quota | Use case |
|---|---|---|---|
| Recherche entreprises (DINUM) | ❌ | 7 req/s | Lookup rapide nom / SIREN / SIRET / dirigeant |
| SIRENE V3 (INSEE) | 🔑 OAuth2 BYOK | 30 req/min | Source de vérité légale, NAF, état admin |
| BAN (Base Adresse Nationale) | ❌ | 50 req/s | Géocodage + normalisation adresses |
| geo.api.gouv.fr | ❌ | ~10 req/s | Communes, départements, régions par code INSEE |
| Bodacc | ❌ | OK | Annonces juridiques (procédures, ventes, modifs) |
| INPI DNE | 🔑 Basic BYOK | OK | Comptes annuels, mandataires sociaux |

---

## Surface v0.1

- **2 connectors BYOK** — `fropendata.sirene` (consumer_key + consumer_secret INSEE), `fropendata.inpi` (username + password)
- **18 agent tools** tous wrappés `bind_session` — 10 no-auth + 5 BYOK + 3 composés (`enrich_company`, `validate_address`, `record_bodacc_alert`)
- **3 agent templates** prêts à l'emploi :
  - `fropendata-enricheur` — single-SIRET → fiche enrichie via send_table
  - `fropendata-veille-portefeuille` — surveillance Bodacc du portefeuille SIREN, écrit alertes dans la KB plugin
  - `fropendata-onboarding-cabinet` — enrichissement batch depuis liste SIRETs
- **1 module Settings + ModuleView** React 4 onglets (APIs / Auth / Cache / Métriques)
- **3 routes HTTP** sous `/plugins/fropendata/*` (settings/health, connections/test, connections/{id} PATCH)
- **1 KB plugin-owned** "Veille juridique — Annonces Bodacc" lazy-seedée à la 1re alerte
- **Stateless DB-side** — pas de schéma plugin, pas de migration plugin

---

## Installation

### Sur une instance Piilot existante (admin)

Le plugin est intégré au core depuis AICockpit PR #180. Pour activer pour une company :

```bash
curl -X PUT "https://<your-piilot>/admin/plugins/fropendata/activations/<company_id>" \
  -H "Authorization: Bearer $TOKEN"
```

Puis dans l'UI :
1. Ouvrir **Settings → Open Data France** (le ModuleView 4 onglets)
2. Onglet **Auth** → cliquer le lien d'aide pour créer vos comptes développeur :
   - SIRENE : https://api.insee.fr/catalogue/ → créer une application → récupérer `consumer_key` + `consumer_secret`
   - INPI : https://www.inpi.fr/services-en-ligne → créer un compte développeur → récupérer `username` + `password`
3. Saisir les credentials via la page Settings → Connecteurs du host (la Save passe par là, pas par ce ModuleView)
4. Revenir dans le ModuleView, cliquer **Tester la connexion** par connecteur

Les 4 APIs sans auth (recherche, BAN, geo, Bodacc) marchent dès l'activation, sans aucune config.

### Standalone (dev / test isolé)

```bash
pip install piilot-pack-fropendata==0.1.0
npm install piilot-pack-fropendata-ui@0.1.0
```

Le plugin se déclare via le `[project.entry-points."piilot.plugins"]` du pyproject.toml ; le loader Piilot le découvre au boot.

---

## Décisions architecturales (cf. CHANGELOG)

- **BYOK full** — chaque cabinet crée ses propres comptes INSEE + INPI (pas de pool centralisé Piilot)
- **2 connectors distincts** — pattern aligné sur `piilot-pack-supabase`
- **Stateless DB-side** — la seule KB plugin-owned (Veille Bodacc) vit dans `kbs.*` natif PG, lazy-seedée façon `piilot-pack-compta`
- **Pas de scheduler v0.1** — SDK scheduler bloqué côté core, veille = invocation manuelle d'agent ou trigger N8N externe
- **Pas de write KB générique** — le core n'expose pas `kb_insert_row` aux agents. `enricheur` et `onboarding-cabinet` restituent via `send_table` (l'utilisateur recopie dans son CRM/KB cible). Seule la veille a son propre `record_bodacc_alert` custom.

---

## Stack technique

- **Backend** : Python 3.12+ · `piilot-sdk>=0.7.0,<1.0.0` · `httpx`/async · LangChain `StructuredTool` + `bind_session`
- **Frontend** : React 19 · TypeScript strict · `react-i18next` · Tailwind classes brutes (pas d'imports `@plugin-host/*` hors le type API)
- **Tests** : pytest 78 unit tests à **71% coverage** (clients HTTP 85-96%, helpers 84%, routes 89%, infra 100%)
- **CI** : ruff + black + pytest sur Python 3.12 / SDK 0.7.0

---

## Roadmap potentielle v0.2+

- Tool plugin `fropendata.upsert_company_row(kb_name, ...)` générique pour permettre aux agents `enricheur` + `onboarding-cabinet` d'écrire directement dans une KB cible (déclenche dogfood-driven)
- TTL overrides cache par company depuis `connection.config["cache_ttl_overrides"]`
- KB référentielle staff `kbs_reference.fropendata_naf_rev2` (~750 codes NAF) — bloqué tant que le SDK n'expose pas formellement `kbs_reference.*` aux plugins
- Scheduled veille Bodacc native (bloqué par SDK scheduler)
- KB plugin-owned `dirigeant_societe` enfant via `kb_ref` (multi-mandataires INPI)
- DECP marchés publics (synergie verticale ESN)
- KALI conventions collectives

---

## Contribuer

Forks, issues et PRs bienvenus. Suivre les conventions du `CLAUDE.md` du repo.

License : Apache-2.0.
