Self-hosted supplier intelligence — AI research, continuous monitoring, evidence-backed risk signals.
ForeChain helps procurement, supply-chain, and resilience teams onboard critical suppliers, monitor them continuously with background AI research, detect meaningful risk changes, and review evidence-backed results through a durable product workflow.
Most teams don't struggle because they have zero supplier data — they struggle because their supplier-risk workflow is fragmented across spreadsheets, inbox alerts, and one-off reviews. ForeChain turns that into a structured operating loop:
- Onboard suppliers with structured intake (country, what you procure, dependency, criticality, locations, monitoring interests)
- Bootstrap each supplier with a baseline profile, monitoring plan, and memory seed
- Monitor continuously in the background — daily or weekly, evidence-grounded
- Surface signals as structured risk events backed by cited sources
- Review through a dashboard of portfolio risk, signals, and reports
| Object | Description |
|---|---|
Supplier |
The supplier being monitored, with structured intake |
Harness Job |
A durable background task (bootstrap, monitor, research, digest) |
Signal |
An individual evidence-backed risk event |
Risk Snapshot |
The current risk assessment for a supplier run |
Report / Artifact |
The persisted evidence-cited output of a completed run |
Memory Snapshot |
Durable supplier memory carried across runs |
- Zero-external-account quickstart — SQLite by default; no auth provider, no billing provider, no object storage required
- Single-workspace, no-auth deployment — everyone who opens the app uses the same local workspace
- Durable async jobs — research and monitoring run in the background, survived by a database-backed queue with recovery
- Six risk dimensions — supplier disruption, logistics & trade, geopolitical & regulatory, compliance & ESG, financial distress, climate & physical
- Evidence-grounded output — every signal must cite fetched sources; high-severity signals require independent corroboration
- Persistent supplier memory — profiles, lifecycle state, and reports survive across runs
- Replayable task packets — every run's inputs, reasoning trace, evidence, and outputs are preserved on disk
- Interactive setup wizard —
uv run forechain-setupconfigures everything
├── backend/ # FastAPI + SQLAlchemy product API, durable job orchestration, persistence
├── harness/ # AI agent runtime: supervisor, workers, tools, evidence, validation
├── frontend/ # React 19 + Vite dashboard
├── scripts/ # setup wizard + maintenance commands
├── tests/ # backend and harness verification (uses test-only fakes)
├── docs/ # product, architecture, and interface documentation
├── pyproject.toml
└── LICENSE.md # MIT
Prerequisites:
- Python 3.11+ and
uv - Node.js 18+ and npm
uv sync --extra dev
cd frontend && npm install && cd ..uv run forechain-setupThe wizard walks you through:
- Database location — SQLite by default, no external database required
- Backend / frontend URLs
- An internal harness token — generated for you automatically
- Optional AI provider keys — LLM, Brave search, Firecrawl (all optional; the wizard explains each)
It writes the .env files and initializes the database for you.
uv run uvicorn backend.app.main:app --reload --port 8001cd frontend && npm run devOpen http://localhost:3000/dashboard and you're in. On first visit you'll be guided through workspace onboarding.
On your first visit you're asked for your company name, profile, supply-base
size, and risk focuses. This context shapes how the harness interprets
supplier materiality. Saving it triggers a background company_research job
that resolves and seeds your buyer-company profile.
Create a supplier with structured intake:
- name, country, supplier type
- what you procure, dependency level, criticality
- key locations, shipping lanes / ports
- known upstream suppliers
- monitoring interests and cadence (daily / weekly)
Creating a supplier triggers an automatic bootstrap job in the background, and once bootstrap completes, an initial monitor run is queued automatically.
The dashboard shows:
- Overview — portfolio risk: active suppliers, elevated risk, critical alerts, watchlist
- Global Risk — macro supply-chain intelligence from the scheduled global digest
- Suppliers — list with current risk score, trend, and top factor
- Supplier Detail — profile, latest run, evidence-backed signals, recommendations, risk dimensions, and the full report
- Signals — the portfolio signal feed with filters and LLM-powered summarization
- Reports — the persisted evidence-cited monitoring reports
Once a supplier is ready, the harness schedules daily or weekly monitor runs
automatically. You can also trigger a manual run from the API
(POST /api/suppliers/{id}/runs). Each run gathers fresh evidence, assesses
risk, updates memory, and writes a new report.
The harness runs research and monitoring through three optional providers.
Without them the product runs, but research/monitoring jobs are gated on a
configured provider. Add keys to .env (or re-run uv run forechain-setup)
and restart the backend.
| Purpose | Environment variable | Required for |
|---|---|---|
LLM provider (openai, gemini, openrouter) |
HARNESS_LLM_PROVIDER |
all research/synthesis |
| LLM model | HARNESS_LLM_MODEL |
all research/synthesis |
| OpenAI / OpenRouter key | HARNESS_OPENAI_API_KEY |
LLM calls |
| Gemini key | HARNESS_GEMINI_API_KEY |
LLM calls |
| Synthesis output tokens | HARNESS_SYNTHESIS_MAX_OUTPUT_TOKENS |
report/memory JSON size (default 4096) |
| Brave web/news search | HARNESS_BRAVE_SEARCH_API_KEY |
source discovery |
| Firecrawl page scraping | HARNESS_FIRECRAWL_API_KEY |
page extraction (HTTP fallback exists) |
All backend settings are read from the environment with a BACKEND_ prefix
(plus HARNESS_* for the harness package). See backend/.env.example for the
full annotated list. Key options:
| Variable | Default | Description |
|---|---|---|
BACKEND_DATABASE_URL |
sqlite+aiosqlite:///./data/product.db |
Database (SQLite by default) |
BACKEND_FRONTEND_URL |
http://localhost:3000 |
CORS origin for the dashboard |
BACKEND_API_BASE_URL |
http://localhost:8001 |
API base URL written into the frontend env |
BACKEND_MONITOR_INTERNAL_TOKEN |
(empty) | Shared secret for internal harness endpoints — set via setup wizard |
BACKEND_LOCAL_STORAGE_ROOT |
data/uploads |
Local directory for uploaded artifacts |
HARNESS_* |
— | LLM/search/crawl providers, budgets, concurrency, schedules |
Frontend: copy frontend/.env.example to frontend/.env.local and set
VITE_PRODUCT_API_BASE_URL (default http://localhost:8001/api). The setup
wizard writes this for you.
uv sync --extra dev # install Python deps (+ dev/test extras)
uv run forechain-setup # interactive setup wizard
uv run pytest -q # run the test suite
uv run alembic upgrade head # apply DB migrations (optional; setup inits schema)
cd frontend && npm run dev # run the dashboard
cd frontend && npm run lint # TypeScript typecheck
cd frontend && npm run build # production build of the dashboardRelease gates (require real provider credentials):
uv run harness-production-check --live
uv run harness-benchmark --output benchmark-report.jsonAt a high level:
Frontend (React) → Product Backend (FastAPI) → Durable Harness Job
│
▼
Agent Runtime
│
Evidence + Validated Result
│
▼
Product Database
- frontend collects onboarding and supplier data
- backend validates the request, stores records, and creates durable jobs
- the harness runs the job using task-specific lead agents and shared specialist workers
- results are validated and written back into the product database
- frontend reads status, signals, reports, and supplier detail through APIs
The harness is a model-driven supervisor with a deterministic shell: models plan, delegate, critique, and synthesize; code enforces budgets, worker whitelists, ordering invariants, security boundaries, and machine-checkable evidence rules.
Read more:
docs/architecture.md— guided visual walkthrough of the whole agent harnessharness/Goal.md— harness objectives and completion criteriaharness/ARCHITECTURE.md— harness V2 runtime designproduct.md— full product overview
backend/— FastAPI + SQLAlchemy (async), durable job orchestration, persistence. Key modules:harness/(job manager, task builders),suppliers/,dashboard/,monitor_sync/(result ingestion).harness/— the agent runtime.orchestrator.py(supervisor),workers.py(specialists),agent.py(model + bounded research loop),tools/(providers, evidence, validation),skill_library/(per-worker scoped skills),persistence.py(replayable packets),telemetry.py(budgets + cost).frontend/— React 19 + Vite + Tailwind dashboard, single-workspace no-auth.
Tests use explicit test-only fakes for model/search/fetch providers — no network or credentials required. Production has no stub or synthetic fallback.
uv run pytest -q- Open issues and pull requests on the repository.
- Keep the no-synthetic-fallback principle: deterministic code is reserved for security, budgets, schema validation, and evidence rules — never for generating supplier intelligence.
- When adding a provider or worker, add coverage under
tests/using the existing fakes.
ForeChain is released under the MIT License. See LICENSE.md
for the full license text.