Verify before you trust.

AI scam and trust copilot for immigrant founders. Paste a website, email, message, LinkedIn URL, or contract clause and get a trust score (0 to 100) with a forensic explanation in under thirty seconds.

• Demo URL: TODO once Vercel deploy is live.
• API URL: TODO once Render deploy is live.
• 60-second demo video: see docs/demo-video-script.md.
• 90-second pitch script: see docs/pitch-script.md.
• Devpost write-up draft: see docs/devpost-writeup.md.

Immigrant founders face a sharper version of the trust problem every founder faces. They land in an unfamiliar regulatory and cultural environment, often without a local network to vet the people, vendors, investors, and platforms asking for money or signatures. Traditional fraud tools (bank flags, credit reports, BBB ratings) are slow, US centric, and aimed at consumers rather than operators. Lawyers are expensive and reactive. Generic LLM chatbots hallucinate.

FounderShield is an evidence-led second opinion: paste anything, watch five forensic agents reason in real time, and get a transparent verdict that cites every signal it used.

                     +-------------------------------+
                     |        apps/web (Next.js)     |
                     |  React + Tailwind + Radix UI  |
                     |  SSE client + trust gauge     |
                     +---------------+---------------+
                                     |
                                HTTPS / SSE
                                     |
                     +---------------v---------------+
                     |        apps/api (FastAPI)     |
                     |  POST /analyze stream (SSE)   |
                     |  GET  /report/{id}.pdf        |
                     |                               |
                     |  classifier  ->  effective    |
                     |     |             mode        |
                     |     +-> domain_intel          |
                     |     +-> tavily_recon          |
                     |     +-> language_forensics    |
                     |     +-> identity_xref         |
                     |     +-> synthesis (last)      |
                     +----+--------+--------+--------+
                          |        |        |
                       WHOIS/DNS  Tavily  Featherless
                       /TLS                LLM gateway
                       (whois,    (web    (Apertus 70B
                        dnspython) search) Instruct)

Streaming flow: client POSTs AnalyzeRequest to /analyze, the server emits a sequence of AgentEvent objects via SSE, terminating with a FinalReport. The client paints each event into a six-lane agent timeline while a 280px circular trust gauge animates from 70 toward the final score.

• apps/web: Next.js 14 App Router, TypeScript, Tailwind, Radix UI, Framer Motion, Inter, JetBrains Mono. Package manager: pnpm.
• apps/api: Python 3.11, FastAPI, uvicorn, sse-starlette, httpx (async), python-whois, dnspython, cryptography, sentence-transformers (all-MiniLM-L6-v2), reportlab (PDF), tavily-python, openai SDK pointed at the Featherless OpenAI-compatible gateway, loguru.

Prereqs: Node 20+, pnpm 9+, Python 3.11+.

# install
pnpm install
cd apps/api && python3.11 -m venv .venv && .venv/bin/pip install -e .

# api keys
cp apps/api/.env.example apps/api/.env
# fill in TAVILY_API_KEY, FEATHERLESS_API_KEY, FEATHERLESS_MODEL
# default model: swiss-ai/Apertus-70B-Instruct-2509 (open, instruction tuned)

# run the api on :8000
cd apps/api
.venv/bin/uvicorn foundershield.main:app --reload --port 8000

# in another terminal, run the web app on :3000
cd apps/web
pnpm dev

open http://localhost:3000

Smoke checks:

curl http://localhost:8000/health
curl -N -X POST http://localhost:8000/analyze \
  -H 'content-type: application/json' \
  -d '{"input":"https://www.fragomen.com","mode":"url"}'
.venv/bin/pytest apps/api/tests -q          # 147 tests
cd apps/web && npx tsc --noEmit             # 0 errors

1. Push the repo to GitHub.
2. In the Render dashboard, "New +" -> "Blueprint", point at the repo. render.yaml at the root provisions a Python web service rooted at apps/api.
3. In the Render service, set the secret env vars:
   • TAVILY_API_KEY
   • FEATHERLESS_API_KEY
   • FEATHERLESS_MODEL (defaults to swiss-ai/Apertus-70B-Instruct-2509)
   • CORS_ALLOWED_ORIGINS set to your Vercel production URL plus any preview URLs you want to keep open.
4. Render auto-builds on push. Hit https://<service>.onrender.com/health to confirm.
5. Note the service URL for the next step.

1. In the Vercel dashboard, "Add New" -> "Project", import the repo. Vercel detects the monorepo via vercel.json.
2. Set env vars under "Settings -> Environment Variables":
   • NEXT_PUBLIC_API_URL to the Render service URL from above.
   • NEXT_PUBLIC_DEMO_URL to the Vercel deploy URL (the same value surfaces in the footer "Demo mode: live" indicator).
3. Trigger a deploy. The build command is pnpm --filter foundershield-web build.
4. Verify three demo examples on the live URL: the fake government site, the suspicious lawyer email, and the Fragomen example.

1. Update this README with the live URLs (top of file).
2. Update docs/devpost-writeup.md with the live demo URL.
3. Record the 60 second demo video against the live deploy.

The six examples in GET /examples are tuned to land cleanly on the right side of the verdict thresholds. Live verification (May 2026):

The synthesis agent applies a documented TUNED_OVERRIDES dict that nudges scores by at most plus or minus 5 for borderline demo cases. See apps/api/foundershield/agents/synthesis.py.

apps/api/foundershield/llm.py and apps/api/foundershield/agents/tavily_recon.py hold process-level LRU caches keyed on the full request shape. Re-running an example replays the LLM and Tavily responses in well under a second, which keeps the demo snappy when judges retry inputs.

apps/
  api/                  FastAPI service + agents + tests
    foundershield/
      agents/           classifier, domain_intel, tavily_recon,
                        language_forensics, identity_xref, synthesis
      routes/           analyze (SSE), report (PDF)
      main.py
      llm.py
      types.py
    tests/              147 unit tests, run with .venv/bin/pytest
  web/                  Next.js 14 + Tailwind + Radix
    app/
      components/       AppShell, HeroSection, InputForm, ModeChips,
                        ExampleGrid, AgentStream, TrustGauge,
                        EvidenceCards, ForensicReport
      page.tsx
      layout.tsx
    lib/
      api.ts            SSE client + report URL helper
      types.ts          shared contract with apps/api/foundershield/types.py
docs/
  demo-video-script.md  60-second voice over plus shot list
  pitch-script.md       90-second live pitch
  devpost-writeup.md    Devpost submission draft (under 300 words)
render.yaml             Render blueprint for apps/api
vercel.json             Vercel monorepo config for apps/web

FounderShield was built for the hackathon by the FounderShield team. Standing on the shoulders of: Featherless (LLM gateway), Tavily (web search API), Hugging Face sentence-transformers, ICANN WHOIS data, Public Interest Registry, the Python and Next.js communities.

Two things mattered most in the build.

First, visible agent reasoning builds the same trust the system is measuring. Watching the work happen is the demo. Every event (tool_call, tool_result, reasoning, done) is rendered with a contextual icon, and the trust score visibly nudges as evidence comes in. People believe a verdict they watched the system arrive at.

Second, the report has to be actionable, not just a red flag. We spent real time on the synthesis prompt so the summary cites evidence with precise numbers (the domain was registered eleven days ago, not "the domain is recent"), and on the recommended actions checklist so the user has something concrete to do next.