# Foresight

# Introduction
Our track is Industry & Manufacturing, supply chain risk and supplier sourcing sit at its center. Deloitte's 2026 Manufacturing Outlook found over 75% of manufacturers cite trade uncertainty as their top concern, yet most procurement teams still track risk manually across spreadsheets and gut feel. <br>
Foresight closes that gap: an MCP-based sourcing advisor, the supply chain that finds out first. It discovers suppliers, screens compliance and live hazards, calculates exposure, ranks alternatives, and drafts a purchasing decision. Just supply the industry, goods, and requirements without any need for database.

## What is real

- Live hazards: USGS earthquakes, NASA EONET natural events, Open-Meteo severe weather, and US NWS alerts.
- Compliance: SAM.gov public exclusions and OFAC SDN via OpenSanctions, bundled as a build-time index and matched locally.
- Supplier discovery: optional Odoo Community ERP records, Tavily web results, and best-effort publicly indexed Open Supply Hub evidence.
- Provenance: external findings carry their source URL and retrieval time.
- Unknown data stays unknown. Foresight does not invent price, lead time, capacity, certifications, coordinates, or reliability.

## MCP Surface

| Tool | Purpose |
|---|---|
| `find_supplier` | Discover, normalize, screen, and rank supplier sites in one call, optionally relative to an incumbent |
| `calculate_exposure` | Assess allocation value, hazard exposure, delay, delivery fit, compliance, verification items, and next steps for any supplied vendor |
| `check_disruptions` | Run caller-provided sites through live hazard, exposure, ranking, and map processing |
| `simulate_disruption` | Run the identical processing against a hypothetical event |
| `draft_supplier_memo` | Build an internal supplier recommendation memo from live assessment, discovery, ranking, and an optional scenario |

Resources: `discovery://latest`, `sources://status`, and `watchtower://latest`. Caller-context resources are disabled by default to prevent cross-client disclosure; trusted single-tenant deployments can set `ENABLE_CONTEXT_RESOURCES=true`. Feed and discovery caches remain bounded and temporary.

Prompts: `morning_briefing` and `draft_mitigation_memo`. The mitigation prompt calls `draft_supplier_memo`; the tool itself can also be called directly.

Widget: `disruption-map`, rendered by both live and simulated disruption tools.

`supplier-memo` is rendered by `draft_supplier_memo`. Widgets use universal MCP Apps metadata; deploy with `NITROSTACK_APP_MODE=universal` so Claude receives the MCP Apps bridge and ChatGPT/NitroStudio retain compatible metadata.

## Quick Start

```bash
npm install
npm run compliance
npm run typecheck
npm run smoke
npm run dev
```

The hazard tools and compliance gate work without supplier-discovery credentials. Configure `.env` from `.env.example` to enable Tavily, structured page enrichment, geocoding, Serper fallback, or Odoo discovery.

## Discovery Sources

### Tavily

Set `TAVILY_API_KEY`. Tavily currently offers 1,000 recurring monthly API credits without requiring a credit card. Foresight uses basic search and bounded result counts.

### Structured enrichment and geocoding

Set `ENABLE_WEB_ENRICHMENT=true` and `WEB_ENRICHMENT_USER_AGENT` to extract JSON-LD identity, public addresses, coordinates, and requested certification claims from up to eight candidate pages. Raw page text is never returned to the model. Set `ENABLE_GEOCODING=true` and `GEOCODING_USER_AGENT` to geocode extracted addresses through OpenStreetMap Nominatim at one request per second with a bounded in-memory cache.

### Serper Places fallback

Set `SERPER_API_KEY` to query Google Places through Serper only when fewer than three candidates have usable coordinates. Places results provide addresses and coordinates for geographic risk assessment; capability remains an inferred claim until corroborated.

### Odoo Community

Set `ENABLE_ODOO_DISCOVERY=true`, `ODOO_ALLOWED_SUBJECTS`, `ODOO_URL`, `ODOO_DATABASE`, `ODOO_USERNAME`, and `ODOO_API_KEY` for a self-hosted Odoo Community instance exposing JSON-RPC. Foresight reads standard vendor price-list and partner records only for authenticated MCP subjects on that allowlist. Odoo is disabled by default because ERP records may be private.

### Open Supply Hub

Direct OS Hub production search endpoints currently require authentication. Foresight uses Tavily domain-restricted search to collect publicly indexed OS Hub evidence and never bypasses authentication or access controls. No result is fabricated when public evidence is unavailable.

## Scoring

Compliance matches are hard-disqualified. Capability and required certifications are eligibility gates. Available evidence is scored as:

- Geographic hazard risk: 40
- Lead-time continuity: 30
- Cost: 20
- Reliability: 10

Missing components receive `null`. Every candidate reports `score_earned`, `score_possible`, and `score_coverage_pct`; partial evidence is not inflated to a complete 100-point score.

Each result also reports readiness: `procurement_ready` requires complete identity, compliance, commercial, reliability, certification, quantity-fit, and risk evidence; `risk_assessed` has capability evidence and usable hazard coordinates but may lack commercial facts; `lead_needing_verification` is not yet geographically assessable.

Unverified facts are presented as `verification_pending` with `next_verification_steps`. Foresight does not state that a supplier lacks a certificate when public evidence has simply not been located.

## Architecture

```text
src/modules/
  data/         supplier discovery and source adapters
  feeds/        live public hazard clients with timeout and visible degradation
  watchtower/   shared live/simulated site-to-hazard engine
  exposure/     stateless supplier allocation assessment
  ranking/      stateless alternate ranking and real-list compliance gate
  memo/         direct supplier memo orchestration, widget, and prompts
```

Live and simulated tools use the same disruption engine. The only difference is whether hazards come from public feeds or a synthetic event supplied to the simulator.

## External Components

APIs and datasets: USGS Earthquake GeoJSON, NASA EONET v3, Open-Meteo Forecast API (CC-BY 4.0), US NWS Alerts API, Tavily Search, optional Serper Google Places, OpenStreetMap Nominatim, optional Odoo Community JSON-RPC, publicly indexed Open Supply Hub pages, SAM.gov Exclusions public extract, and OpenSanctions OFAC SDN (CC-BY-NC 4.0).

Map data: OpenStreetMap contributors and CARTO basemaps.

Libraries: Nitrostack SDK, Model Context Protocol Ext Apps, Cheerio, dotenv, i18n-iso-countries, Undici, Zod, TypeScript/tsx, Next.js/React, and MapLibre GL JS.

AI implementation assistance is declared in `PROGRESS.md`. Architectural decisions and reasons are recorded in `decisions.md`.


## Contributors
[KK Surendran](https://github.com/KKSurendran06/) <br>
[Khushal](https://github.com/Khushal928) <br>
[Malavika](https://github.com/Malavika05M) <br>
[Praharsha](https://github.com/Praharsha2007) <br>