+
+ ) : null,
+ )}
+ + {section.heading} +
+
+ {section.markdown}
+
+ {d.templates[templateId].name}
++ {error.message || t.errorFallback} +
+ ) : null} + + {/* Document left, working right — on a narrow screen the trace drops + below the document rather than beside it, since the document is what + someone on a phone came for. */} +{d.documentEmpty}
+ )} + + {busy ? ( +{d.description}
+
+
{t.deliverables.traceEmpty}
; + } + + return ( +Access constraints persist.
', + }, + }, + ], +}; + +/** Routes by host so a test can assert which upstreams were touched. */ +function stubFetch(options: { reliefWebStatus?: number } = {}) { + const calls: string[] = []; + const mock = vi.fn(async (url: string | URL) => { + const href = String(url); + calls.push(href); + if (href.includes('api.reliefweb.int')) { + const status = options.reliefWebStatus ?? 200; + return new Response(JSON.stringify(RELIEFWEB_PAYLOAD), { + status, + headers: { 'Content-Type': 'application/json' }, + }); + } + return new Response(JSON.stringify(IFRC_PAYLOAD), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }); + }); + vi.stubGlobal('fetch', mock); + return calls; +} + +let queryCounter = 0; +/** The module cache is per-process, so every test needs its own cache key. */ +function uniqueQuery(): string { + queryCounter += 1; + return `displacement-case-${queryCounter}`; +} + +function harvestOf(result: unknown) { + let n = 0; + return harvest('crisis_updates', result, () => `e${(n += 1)}`); +} + +describe('getCrisisUpdates with RELIEFWEB_APPNAME unset', () => { + afterEach(() => { + vi.unstubAllGlobals(); + vi.unstubAllEnvs(); + }); + + it('never calls ReliefWeb and answers from IFRC GO', async () => { + vi.stubEnv('RELIEFWEB_APPNAME', ''); + const calls = stubFetch(); + + const result = await getCrisisUpdates(uniqueQuery(), 'Sudan'); + + expect(calls.some((url) => url.includes('reliefweb'))).toBe(false); + expect(result.retrievedVia).toBe('ifrc-go'); + expect(result.updates).toHaveLength(1); + }); + + it('reports ReliefWeb as unavailable once, and not as a failure of the tool', async () => { + vi.stubEnv('RELIEFWEB_APPNAME', ''); + stubFetch(); + + const result = await getCrisisUpdates(uniqueQuery(), 'Sudan'); + + // `notice` stays free for a genuinely empty retrieval. + expect(result.notice).toBeUndefined(); + expect(result.sourceNote).toContain('IFRC GO'); + expect(result.errors).toHaveLength(1); + expect(result.errors?.[0].source).toBe('ReliefWeb'); + // Honest and readable by an operator: what is off, and what they get instead. + expect(result.errors?.[0].message).toMatch(/not enabled/i); + expect(result.errors?.[0].message).toContain('OCHA'); + }); + + it('harvests as a working source with one unavailable upstream', async () => { + vi.stubEnv('RELIEFWEB_APPNAME', ''); + stubFetch(); + + const { items, errors } = harvestOf(await getCrisisUpdates(uniqueQuery(), 'Sudan')); + + // The updates are evidence, not a degraded source. + expect(items.length).toBeGreaterThan(0); + // Exactly one issue, attributed to ReliefWeb rather than to `crisis_updates`. + expect(errors).toHaveLength(1); + expect(errors[0].source).toBe('crisis_updates · ReliefWeb'); + }); + + it('still reports a genuinely empty retrieval through notice', async () => { + vi.stubEnv('RELIEFWEB_APPNAME', ''); + vi.stubGlobal( + 'fetch', + vi.fn( + async () => + new Response(JSON.stringify({ results: [] }), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }), + ), + ); + + const result = await getCrisisUpdates(uniqueQuery(), 'Atlantis'); + + expect(result.updates).toHaveLength(0); + expect(result.notice).toMatch(/No matching emergencies/); + }); +}); + +describe('getCrisisUpdates with RELIEFWEB_APPNAME set', () => { + afterEach(() => { + vi.unstubAllGlobals(); + vi.unstubAllEnvs(); + }); + + it('uses ReliefWeb and reports no source issues', async () => { + vi.stubEnv('RELIEFWEB_APPNAME', 'approved-appname'); + const calls = stubFetch(); + + const result = await getCrisisUpdates(uniqueQuery(), 'Sudan'); + + expect(calls.some((url) => url.includes('api.reliefweb.int'))).toBe(true); + expect(result.retrievedVia).toBe('reliefweb'); + expect(result.errors).toBeUndefined(); + expect(harvestOf(result).errors).toHaveLength(0); + }); + + it('falls back to IFRC GO and records why when ReliefWeb rejects the appname', async () => { + vi.stubEnv('RELIEFWEB_APPNAME', 'revoked-appname'); + stubFetch({ reliefWebStatus: 403 }); + + const result = await getCrisisUpdates(uniqueQuery(), 'Sudan'); + + expect(result.retrievedVia).toBe('ifrc-go'); + expect(result.updates).toHaveLength(1); + expect(result.errors?.[0].source).toBe('ReliefWeb'); + expect(result.errors?.[0].message).toContain('403'); + }); +}); diff --git a/app/src/lib/tools/crisis-updates.ts b/app/src/lib/tools/crisis-updates.ts index 16cda5c..9cf930f 100644 --- a/app/src/lib/tools/crisis-updates.ts +++ b/app/src/lib/tools/crisis-updates.ts @@ -10,6 +10,8 @@ import { z } from 'zod'; * preferred source. Since 1 November 2025 it rejects any `appname` OCHA has * not pre-approved; approval is a reviewed request form, not a self-service * key. Set RELIEFWEB_APPNAME once granted and this path activates on its own. + * Until then the source is treated as disabled rather than broken: it is not + * called at all, and it says once per result that it is not configured. * 2. IFRC GO — open, no registration, and used by default. Its lens is * narrower: Red Cross / Red Crescent emergency operations rather than the * whole humanitarian information space, so the most recent entry for a given @@ -46,11 +48,58 @@ export interface CrisisUpdate { countries?: string[]; } +/** One upstream source that was unavailable, in the shape `harvest()` reads. */ +export interface SourceIssue { + source: string; + message: string; +} + export interface CrisisUpdatesResult { query: string; retrievedVia: 'reliefweb' | 'ifrc-go'; updates: CrisisUpdate[]; + /** + * How the model should attribute a successful retrieval — which source + * answered and what its coverage excludes. + * + * Deliberately NOT `notice`. Across this codebase `notice` means "this + * retrieval came back empty" and is read as a failure by both trace paths: + * `chat-trace.ts` turns it into an `ok: false` step and `evidence.ts` + * `extractFailures` turns it into a `source-error`. Carrying routine sourcing + * guidance in that field marked every successful IFRC GO answer as a failed + * source, once per call and once per deliverable section. + */ + sourceNote?: string; + /** Reserved for a genuinely empty retrieval. */ notice?: string; + /** + * Sources that did not answer, reported per source rather than as a whole-tool + * failure. `harvest()` renders these into the deliverable's "Source issues" + * block (de-duplicated there) and the trace panel shows them as notices. + */ + errors?: SourceIssue[]; +} + +/** + * ReliefWeb without an approved appname is an expected deployment state, not a + * fault: the API is never called, and the absence is announced once through the + * same per-source channel any other unavailable source uses. + */ +const RELIEFWEB_NOT_CONFIGURED: SourceIssue = { + source: 'ReliefWeb', + message: + 'Not enabled on this deployment, so it was not queried: ReliefWeb requires an appname approved by OCHA and none is configured. Crisis updates below come from IFRC GO, which covers Red Cross / Red Crescent operations only — consult reliefweb.int directly for the fuller reporting picture.', +}; + +type ReliefWebConfig = + | { configured: true; appname: string } + | { configured: false; issue: SourceIssue }; + +function reliefWebConfig(): ReliefWebConfig { + const appname = process.env.RELIEFWEB_APPNAME?.trim(); + return appname + ? { configured: true, appname } + : { configured: false, issue: RELIEFWEB_NOT_CONFIGURED }; } /** @@ -219,21 +268,32 @@ export async function getCrisisUpdates( const cached = readCache(cacheKey); if (cached) return cached; - const appname = process.env.RELIEFWEB_APPNAME; + // Configuration is settled before any request goes out, so the unconfigured + // path costs no call and raises nothing. + const config = reliefWebConfig(); + const issues: SourceIssue[] = []; let result: CrisisUpdatesResult | undefined; - if (appname) { + if (config.configured) { try { result = { query, retrievedVia: 'reliefweb', - updates: await fetchFromReliefWeb(appname, query, country), + updates: await fetchFromReliefWeb(config.appname, query, country), }; - } catch { - // An unapproved or revoked appname 403s. Fall through to IFRC GO rather - // than failing the user's question. - result = undefined; + } catch (error) { + // An unapproved or revoked appname 403s. That is a real degradation, so + // it is recorded against ReliefWeb — but it still falls through to IFRC + // GO rather than failing the user's question. + issues.push({ + source: 'ReliefWeb', + message: `Configured but did not answer (${ + error instanceof Error ? error.message : 'unknown error' + }). Results below are from IFRC GO instead; the appname may no longer be approved.`, + }); } + } else { + issues.push(config.issue); } if (!result) { @@ -241,12 +301,15 @@ export async function getCrisisUpdates( query, retrievedVia: 'ifrc-go', updates: await fetchFromIfrcGo(query, country), - notice: appname - ? 'ReliefWeb rejected the configured appname, so these results are IFRC GO emergency operations. Tell the user the source and that its coverage is narrower than ReliefWeb.' - : 'Results are IFRC GO emergency operations, not ReliefWeb: ReliefWeb now requires an OCHA-approved appname, which this deployment does not have. Attribute the figures to IFRC GO, note that its coverage is limited to Red Cross / Red Crescent operations, and point the user to reliefweb.int for the full reporting picture.', + sourceNote: + 'These results are IFRC GO emergency operations, not ReliefWeb. Attribute the figures to IFRC GO, say that its coverage is limited to Red Cross / Red Crescent operations, and point the user to reliefweb.int for the full reporting picture.', }; } + if (issues.length > 0) { + result.errors = issues; + } + if (result.updates.length === 0) { result.notice = `No matching emergencies were found${ country ? ` for ${country}` : '' diff --git a/app/src/lib/tools/hazards-context.test.ts b/app/src/lib/tools/hazards-context.test.ts new file mode 100644 index 0000000..b4071ca --- /dev/null +++ b/app/src/lib/tools/hazards-context.test.ts @@ -0,0 +1,116 @@ +import { beforeEach, describe, expect, it, vi } from 'vitest'; + +vi.mock('./live-sources/gdacs', () => ({ fetchAlerts: vi.fn() })); +vi.mock('./live-sources/usgs', () => ({ fetchEarthquakes: vi.fn() })); +vi.mock('./live-sources/worldbank', () => ({ fetchCountryContext: vi.fn() })); +vi.mock('./live-sources/hpc', () => ({ fetchPlans: vi.fn() })); + +import { getCountryHazardsBrief, getGlobalHazardsOverview, runHazardsContext } from './hazards-context'; +import { fetchAlerts } from './live-sources/gdacs'; +import { fetchPlans } from './live-sources/hpc'; +import { fetchEarthquakes } from './live-sources/usgs'; +import { fetchCountryContext } from './live-sources/worldbank'; + +const fetchAlertsMock = vi.mocked(fetchAlerts); +const fetchEarthquakesMock = vi.mocked(fetchEarthquakes); +const fetchPlansMock = vi.mocked(fetchPlans); +const fetchCountryContextMock = vi.mocked(fetchCountryContext); + +beforeEach(() => { + vi.clearAllMocks(); +}); + +describe('getGlobalHazardsOverview', () => { + it('combines all three global sources when every one succeeds', async () => { + fetchAlertsMock.mockResolvedValue([{ source: 'GDACS' } as never]); + fetchEarthquakesMock.mockResolvedValue([{ source: 'USGS' } as never]); + fetchPlansMock.mockResolvedValue([{ source: 'OCHA HPC' } as never]); + + const result = await getGlobalHazardsOverview(['gdacs', 'usgs', 'hpc']); + + expect(result.errors).toEqual([]); + expect(result.gdacsAlerts).toHaveLength(1); + expect(result.earthquakes).toHaveLength(1); + expect(result.responsePlans).toHaveLength(1); + expect(fetchAlertsMock).toHaveBeenCalledWith({ minLevel: 'orange' }); + }); + + it('degrades one failing source into `errors` instead of failing the whole report', async () => { + fetchAlertsMock.mockRejectedValue(new Error('feed down')); + fetchEarthquakesMock.mockResolvedValue([{ source: 'USGS' } as never]); + fetchPlansMock.mockResolvedValue([]); + + const result = await getGlobalHazardsOverview(['gdacs', 'usgs', 'hpc']); + + expect(result.gdacsAlerts).toEqual([]); + expect(result.earthquakes).toHaveLength(1); + expect(result.errors).toEqual(['gdacs: feed down']); + }); + + it('only calls the requested sources', async () => { + fetchEarthquakesMock.mockResolvedValue([]); + const result = await getGlobalHazardsOverview(['usgs']); + expect(fetchAlertsMock).not.toHaveBeenCalled(); + expect(fetchPlansMock).not.toHaveBeenCalled(); + expect(result.gdacsAlerts).toBeUndefined(); + expect(result.responsePlans).toBeUndefined(); + }); + + it('caps each section to its list limit', async () => { + fetchAlertsMock.mockResolvedValue(Array.from({ length: 25 }, () => ({}) as never)); + fetchEarthquakesMock.mockResolvedValue(Array.from({ length: 25 }, () => ({}) as never)); + fetchPlansMock.mockResolvedValue(Array.from({ length: 25 }, () => ({}) as never)); + + const result = await getGlobalHazardsOverview(['gdacs', 'usgs', 'hpc']); + + expect(result.gdacsAlerts).toHaveLength(10); + expect(result.earthquakes).toHaveLength(10); + expect(result.responsePlans).toHaveLength(15); + }); +}); + +describe('getCountryHazardsBrief', () => { + it('scopes GDACS to the country and reports World Bank context', async () => { + fetchAlertsMock.mockResolvedValue([{ source: 'GDACS' } as never]); + fetchCountryContextMock.mockResolvedValue([{ source: 'World Bank' } as never]); + + const result = await getCountryHazardsBrief('SDN', ['gdacs', 'worldbank']); + + expect(fetchAlertsMock).toHaveBeenCalledWith({ minLevel: 'green', countryIso3: 'SDN' }); + expect(result.countryIso3).toBe('SDN'); + expect(result.countryContext).toHaveLength(1); + expect(result.errors).toEqual([]); + }); + + it('reports a down World Bank source in errors and empties the section', async () => { + fetchAlertsMock.mockResolvedValue([]); + fetchCountryContextMock.mockRejectedValue(new Error('timeout')); + + const result = await getCountryHazardsBrief('SDN', ['gdacs', 'worldbank']); + + expect(result.countryContext).toEqual([]); + expect(result.errors).toEqual(['worldbank: timeout']); + }); +}); + +describe('runHazardsContext', () => { + it('rejects an invalid country code before calling any source', async () => { + const result = await runHazardsContext({ scope: 'country', country_iso3: 'sudan' }); + + expect(fetchAlertsMock).not.toHaveBeenCalled(); + expect(result.errors[0]).toMatch(/not a valid ISO 3166-1 alpha-3 code/); + }); + + it('defaults to the global source set when none is given', async () => { + fetchAlertsMock.mockResolvedValue([]); + fetchEarthquakesMock.mockResolvedValue([]); + fetchPlansMock.mockResolvedValue([]); + + const result = await runHazardsContext({ scope: 'global' }); + + expect(result.scope).toBe('global'); + expect(fetchAlertsMock).toHaveBeenCalled(); + expect(fetchEarthquakesMock).toHaveBeenCalled(); + expect(fetchPlansMock).toHaveBeenCalled(); + }); +}); diff --git a/app/src/lib/tools/hazards-context.ts b/app/src/lib/tools/hazards-context.ts new file mode 100644 index 0000000..b2b82cb --- /dev/null +++ b/app/src/lib/tools/hazards-context.ts @@ -0,0 +1,148 @@ +import { tool } from 'ai'; +import { z } from 'zod'; + +import { fetchAlerts, type GdacsAlert } from './live-sources/gdacs'; +import { fetchPlans, type ResponsePlan } from './live-sources/hpc'; +import { fetchEarthquakes, type EarthquakeEvent } from './live-sources/usgs'; +import { fetchCountryContext, type WorldBankIndicatorValue } from './live-sources/worldbank'; + +// Aggregates the keyless live hazard/context sources (USGS, GDACS, World Bank, +// OCHA HPC) behind one tool call, so a source that is down degrades its own +// section instead of failing the whole answer. +// +// Ported from commit eb5e5c3 (src/hai/situation.py), +// which combines the same connectors into `global_overview` / `country_brief` +// reports with a `_try`-per-source degradation pattern reproduced here. + +const GLOBAL_SOURCES = ['gdacs', 'usgs', 'hpc'] as const; +const COUNTRY_SOURCES = ['gdacs', 'worldbank'] as const; +type Source = (typeof GLOBAL_SOURCES)[number] | (typeof COUNTRY_SOURCES)[number]; + +/** Cap list lengths: results are re-sent to the model on every tool-loop step. */ +const EARTHQUAKE_LIMIT = 10; +const GDACS_LIMIT = 10; +const PLAN_LIMIT = 15; + +export interface HazardsContextResult { + scope: 'global' | 'country'; + countryIso3?: string; + generatedAt: string; + gdacsAlerts?: GdacsAlert[]; + earthquakes?: EarthquakeEvent[]; + responsePlans?: ResponsePlan[]; + countryContext?: WorldBankIndicatorValue[]; + /** One entry per source that failed or was skipped — the report is + * degraded, not absent, when this is non-empty. */ + errors: string[]; +} + +async function tryFetch