feat(contrib): add cross-border data-policy router recipe

[janrockdev]

Summary

Adds contrib/python/cross-border-data-router, a Python ADK recipe demonstrating a common enterprise compliance problem: deciding which regional agent is legally allowed to process a piece of data, based on where that agent says it operates.

A root orchestrator receives a data-processing request (a classification like PII plus an origin region), evaluates it against a registry of regional processor agents, and only then delegates the work — or refuses outright if no agent qualifies. Eligibility is read directly off each candidate's real a2a.types.AgentCard via a custom capabilities.extensions entry, since the core A2A spec has no built-in notion of jurisdiction or data residency.

Why this recipe

I searched the repo first for an existing sample that evaluates policy and routes based on an agent's declared location/jurisdiction, and found none:

• The only prior A2A AgentCard usage in the repo (core/python/long-horizon-harness) builds/serves a card but never reads location off one.
• python/agents/global-kyc-agent routes UK vs. US sub-agents, but by an LLM reading the company being checked out of free text — not metadata declared by the candidate agent itself.
• "Policy" elsewhere in the repo (long-horizon-harness's tool-call guardrails, core/python/safety-plugins) means something different: gating a single agent's own actions, not choosing between agents.

This recipe fills that gap with a pattern modeled on OpenEAGO (repo), a FINOS Labs specification for jurisdiction-aware governance of multi-agent workflows. OpenEAGO isn't a published Python package, so this is a from-scratch implementation of the pattern it describes (two-stage hard-filter-then-score agent selection), not a dependency on it — credited and linked in the README.

What's in it

• app/policy/cards.py — a static registry of three regional processor cards (eu_processor, uk_processor, us_processor), each a real a2a.types.AgentCard carrying jurisdiction/data-residency metadata via an AgentExtension.
• app/policy/engine.py — the routing policy: Stage 1/2 hard filters (data residency, jurisdiction exclusion) that scoring can never override, then a weighted score among survivors. No candidates surviving means an explicit rejection, never a silent fallback to a non-compliant agent.
• app/agent.py + app/sub_agents/* — an ADK LlmAgent orchestrator that calls the policy tool first, then delegates to the approved regional sub-agent via AgentTool.
• tests/unit/test_policy_engine.py, tests/unit/test_tools.py — cover the hard filters, preference scoring, and the reject-rather-than-fallback path directly.

Testing

Run locally from the repo root:

export RECIPE_PATH=contrib/python/cross-border-data-router
uv run validate "$RECIPE_PATH"                # PASS — manifest + structure
uv run ruff format "$RECIPE_PATH" && uv run ruff check "$RECIPE_PATH"   # clean
cd "$RECIPE_PATH" && uv lock && uv run pytest --ignore=tests/integration --ignore-glob="**/test_integration.py"
# 11 passed

Also manually verified uv run adk run app and uv run uvicorn app.fast_api_app:app --reload both start and route correctly against a live Gemini API key.