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.

APIs couvertes

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 :

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é)

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.