Composition: Entity screening + News media pulse

Series: compositions (2 of 4)
Prerequisites: Platform intro, Entity, News
Directions: Entity + News
Auth: x-api-key

Compose a compliance desk slice: screening signal for a counterparty, plus what curated media and global coverage are saying about related themes. Still a signal stack, not a legal determination.

Goal

For a name (or LEI / wallet):

Run Entity screen (hit / review / clear + lists + freshness).
Pull curated headlines and/or GDELT articles for the same string.
Optionally pull theme radar for policy/crisis context.
Package one case file JSON with disclaimers.

Call sequence

[Entity] POST /entity/screen  {name, country?}
[Entity] GET  /entity/sources   (or rely on meta.list_freshness)
[News]   GET  /news/search?q={name}
[News]   GET  /gdelt/articles?q={name}&max_records=10
[News]   GET  /gdelt/themes/trending?period=6h&limit=10   (optional context)
         -> case_file

Entity

H="x-api-key: $SUGRA_API_KEY"
B=https://sugra.ai

curl -X POST -H "$H" -H "Content-Type: application/json" \
  -d '{"name":"Example Corp","country":"US"}' \
  "$B/api/v1/entity/screen"

Store data.screening.status, matches, meta.disclaimer, meta.screening_id, meta.list_freshness, meta.stale_screening.

News

curl -H "$H" "$B/api/v1/news/search?q=Example%20Corp&limit=10"
curl -H "$H" "$B/api/v1/gdelt/articles?q=Example%20Corp&max_records=10"
curl -H "$H" "$B/api/v1/gdelt/themes/trending?period=6h&limit=10"

If GDELT returns 503, keep curated search results and mark gdelt_unavailable: true.

Client package (example)

case_file = {
    "subject": {"name": name, "country": country},
    "screening": {
        "status": entity["screening"]["status"],
        "match_count": len(entity["screening"].get("matches") or []),
        "screening_id": entity_meta.get("screening_id"),
        "stale_screening": entity_meta.get("stale_screening"),
        "disclaimer": entity_meta.get("disclaimer"),
    },
    "media": {
        "curated_hits": news_search_items,
        "gdelt_articles": gdelt_articles or [],
        "themes_window": themes if themes else None,
    },
    "policy": {
        "auto_block_if": ["hit"],  # your policy, not Sugra's
        "human_review_if": ["review"],
    },
}

Never auto-file a SAR or legal conclusion from this JSON alone.

Why this composition works

Leg	Contribution
Entity	Multi-list screen, rationale, freshness, disclaimer
News curated	Short-cadence headlines with links
GDELT	Broader global media evidence when available

Media is not a sanctions list. Use it for analyst context after or beside the screen.

Cadence and quota

Step	Cadence idea
Screen on onboarding / payment	Event-driven
Re-screen	Policy schedule (daily/weekly)
News search	Event-driven or hourly watch
Themes	Hourly dashboard

Batch onboarding: use Entity batch screen; do not N-serial GDELT for every vendor without a cache.

Failure modes

Failure	Handling
Entity `stale_screening` true	Queue human review or block per policy
GDELT 503	Curated-only media section
Empty news search	Still return screen; note no curated hits
Wallet path instead of name	Swap in `/entity/wallet/{addr}/screen`

Screen first, then read the room