feat: add French Territorial Intelligence agent

[hamidedefr]

Summary

Adds a new agent that cross-references French open data APIs to produce territorial intelligence insights. No API keys needed — all three data sources are zero-auth French government APIs.

Data sources:

• Recherche Entreprises (SIRENE) — business registry, enterprise density, sector breakdown
• DVF (Cerema) — real estate transactions, price per sqm, property types
• Geo API — communes, population, surface, geographic context

Key differentiator: cross-referencing. The agent doesn't just query APIs — it computes derived indicators by combining data across sources:

• Enterprise density (enterprises per 1,000 inhabitants)
• Affordability index (real estate cost vs. economic activity)
• Economic intensity (concentration of activity)

Architecture:

• Extensible DataSource protocol — adding a new API = one file, zero changes to existing code
• Auto-discovery registry
• OpenAI function calling with 3 tools: analyze_territory, compare_territories, search_enterprises
• SSE streaming following OpenBB conventions

Example queries:

• "Analyze the business dynamics in Marseille"
• "Compare Lyon and Nantes for a tech startup"
• "What's the real estate market like in Bordeaux?"

Closes #86

Test plan

• 23 unit tests passing (sources, crossref, endpoints)
• TDD: all tests written before implementation
• Mock-based tests (no external API calls in CI)
• Manual test with OpenBB Workspace (requires OPENAI_API_KEY)

Built on Tawiza's territorial intelligence engine.

[DidierRLopes]

Hey!

We are trying to keep this repo more to be used as a reference on how to build an agent for the workspace!

Instead - want to host it on your repo and add a link here: https://github.com/OpenBB-finance/awesome-openbb/blob/main/README.md#agents

Would love to feature it there 😄

[hamidedefr]

Hey @DidierRLopes! Thanks for the feedback and the suggestion — makes total sense to keep this repo focused on reference agents.

I've moved the agent to its own repository: tawiza/openbb-french-territorial-intelligence

I'll submit a PR to awesome-openbb to get it listed in the Agents section.

Happy to close this PR once the awesome-openbb listing is live. Thanks for the warm welcome! 🙏

[DidierRLopes]

Added!!

@hamidedefr have you thought about using these sources to build an OpenBB App?

You can use this agent skill to build it out:

npx skills add https://github.com/openbb-finance/backends-for-openbb --skill openbb-app-builder

If this is of interest, then we can not only share it in the awesome apps page section as well but make it appear here: https://openbb.co/solutions/app-showcase/

Also - we are working on announcing an Apps Marketplace soon. This would be a really nice app to make available to other users from the workspace directly. Let me know if there's interest to explore this :)

Closing this PR, but feel free to reach out to me at didier.lopes [at] openbb.finance - to discuss more!

[hamidedefr]

That's awesome, thanks for the feature! 🙏

Really interested in all three:

1. OpenBB App - I'll explore the app builder skill this week. The territorial data lends itself well to visual widgets (score gauges, department comparison tables, alert panels). Would love to build something that showcases cross-referencing in a visual way.

2. App Showcase - Absolutely, happy to be featured once the app is ready.

3. Apps Marketplace - Very interested. French territorial intelligence is a niche that doesn't exist on any platform today could bring a unique audience to the marketplace. Let's explore this.

I'll get back to you once I have a first version of the app working. Thanks for the warm welcome to the OpenBB ecosystem!

[DidierRLopes]

Of course @hamidedefr !!!

Looking forward to collaborate here - anything you need from me let me know. If you open source the app, I can also help you if you get stuck or anything 😄

I recommend checking this out - https://github.com/OpenBB-finance/backends-for-openbb/tree/main/getting-started/reference-backend

As it has the most diverse type of widgets, params, etc... and that gives you some ideas on how to structure this app!

Thank you!