Pharma R&D Copilot

A research-support workspace for pharmaceutical development. A scientist submits a research question; a supervisor agent plans the work, specialist agents retrieve real literature and patent evidence, and the system produces a structured report in which every citation resolves to a source that was actually retrieved.

It is decision support. It does not provide medical, regulatory, toxicological, clinical or legal decisions, and does not replace qualified scientists, patent counsel, regulatory experts, toxicologists, clinicians or statisticians.

---

Two modules, one idea

Research answers a question once: retrieve, synthesise, cite, done.

PDP Operations & Stage-Gate Guardian tracks a development programme across Gate 0–7 for as long as it runs — requirements, evidence, owners, approvals, and whether a gate may actually be reviewed. See docs/PDP_MODULE.md.

They share one projects table, which is what lets a completed research run be attached as evidence against a gate requirement rather than the two being separate applications behind one login.

Both enforce their central guarantee structurally:

Module	Guarantee	Why it holds
Research	A citation cannot exist unless the source was retrieved	Evidence rows are written before synthesis; unresolvable markers are stripped
PDP	A requirement cannot be green because someone ticked a box	There is no box — no completion column exists, so nothing can set one

A rule enforced by structure survives contact with people in a hurry. A rule enforced by convention does not.

---

What makes a citation trustworthy here

The central guarantee is structural rather than behavioural:

1. Provider adapters write evidence_records rows before any synthesis runs. Each row gets a stable marker (E1, E2, …).
2. Synthesis prompts receive only that marker list as citable sources.
3. Every [En] marker in generated text is extracted and checked against the evidence table. Anything that does not resolve is removed and replaced with a visible [unverified citation removed] flag.
4. The reference list and disclaimers are assembled by code from stored rows, not generated by a model.

A model that hallucinates [E999] therefore cannot produce a plausible-looking fake citation. It produces a visibly flagged, stripped claim.

Section confidence is computed from evidence coverage and source breadth, never from the model's opinion of its own output.

---

Architecture

Next.js 15 frontend  ──▶  FastAPI  ──▶  Postgres (Supabase)
   Supabase Auth            │              ▲
   middleware guard         │              │
                            ▼              │
                      run_jobs queue       │
                            │              │
                            ▼              │
                     Python worker ────────┘
                            │
                     LangGraph workflow
                            │
              ┌─────────────┼─────────────┐
         PubMed /       EPO OPS        OpenAI
        Europe PMC                  Responses API

Research runs take minutes and make dozens of external calls, so they never run inside an HTTP request. POST /api/runs creates the run, enqueues a job and returns a run id immediately; a separate worker executes the graph and writes a progress event after every node.

The graph:

START → intake_and_scope → supervisor_planner
      → { research_agent, literature_agent, patent_agent }   (concurrent)
      → development_strategy_agent → supervisor_synthesis
      → evidence_reviewer → report_generation → END

See docs/ARCHITECTURE.md and docs/AGENT_WORKFLOW.md.

---

Local setup

Requires Node 20+, Python 3.12+, and a Supabase project.

Windows PowerShell users: commands below are given for PowerShell, which has no && operator — use ; to chain, as shown. On macOS, Linux or Git Bash, replace .venv\Scripts\python.exe with .venv/bin/python and ; with &&.

1. Install dependencies

npm install

python -m venv backend/.venv

Windows (PowerShell):

backend\.venv\Scripts\python.exe -m pip install -r backend/requirements.txt

macOS / Linux:

backend/.venv/bin/python -m pip install -r backend/requirements.txt

2. Create the database

Apply the migrations in supabase/migrations/ in filename order, either through the Supabase SQL editor or the Supabase CLI:

supabase db push

This creates 35 tables, 30 RLS policies and 22 private schema helpers, across both modules.

3. Configure environment

Copy the example file and fill in real values:

cp .env.example .env.local

.env.local (frontend) needs:

NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<publishable key>
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

backend/.env needs, at minimum:

DATABASE_URL=postgresql://postgres.<ref>:<password>@<host>:6543/postgres
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=<service role key>
OPENAI_API_KEY=sk-...

All four are required; the backend refuses to start without them and names exactly which are missing. Provider keys are optional — see docs/DATA_SOURCES.md for what degrades without each.

Where to find the connection string: the green Connect button in the dashboard's top bar — not the Settings page. Choose the Transaction pooler (port 6543).

Do not use the direct connection (db.<ref>.supabase.co, port 5432): on current projects that host is IPv6-only, so it is unreachable from most networks. The pooler is IPv4.

The service role key is under Project Settings → API Keys.

No JWT secret is needed. Current Supabase projects sign tokens with asymmetric ES256 keys published at /auth/v1/.well-known/jwks.json, which the backend fetches automatically. Confirm yours does too:

curl https://<project-ref>.supabase.co/auth/v1/.well-known/jwks.json

A non-empty keys array means you can leave SUPABASE_JWT_SECRET blank. Only legacy projects with an HS256 shared secret need it. GET /api/health reports which scheme is active.

4. Check your setup

cd backend; .venv\Scripts\python.exe check_setup.py

Tests every credential and reports pass or fail per item — database connection, schema completeness, JWT scheme, OpenAI model availability, and each provider. It prints no secret values, so its output is safe to paste when asking for help.

5. Run

Three processes, each in its own terminal.

Frontend:

npm run dev

API:

cd backend; .venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000

Worker:

cd backend; .venv\Scripts\python.exe -m app.worker

Open http://localhost:3000, create an account, and check http://localhost:3000/integrations to confirm which providers are live.

6. Seed the demo project

Sign up through the web app first, then:

cd backend; .venv\Scripts\python.exe -m app.seed --email [email protected]

This creates the Peptide Depot Delivery Feasibility Assessment project with its research question and parameters. It seeds no results — running it performs a real search and returns whatever the providers actually hold. Add --start to queue the run immediately.

---

Tests

cd backend; .venv\Scripts\python.exe -m pytest -q

npm run lint; npx tsc --noEmit; npm run build

The stage-gate suites need a real database, so they are scripts rather than pytest modules and run separately:

cd backend; .venv\Scripts\python.exe tests\db\test_readiness_engine.py

cd backend; .venv\Scripts\python.exe tests\db\test_phase_c_workflow.py

Both create everything they need inside a transaction and roll it back, so the database is unchanged afterwards.

The Python suite covers provider normalisation, deduplication, structured model outputs, citation validation, failed external APIs, missing optional keys, graph routing, and one end-to-end workflow that runs the real compiled graph against fixture providers.

---

Project layout

app/                 Next.js App Router pages
components/          UI, layout, run views
lib/                 API client, Supabase clients, shared types
middleware.ts        server-side route protection
backend/app/
  config.py          settings; required values fail loudly at startup
  auth.py            Supabase JWT verification
  repository.py      all SQL; every read filters by user_id
  api/               HTTP routes
  providers/         PubMed, Europe PMC, EPO OPS adapters
  llm/               Responses API, pricing, prompts, citation validation
  graph/             LangGraph state, nodes, workflow
  worker.py          job queue consumer
  seed.py            demo project
supabase/migrations/ versioned SQL
docs/                architecture, agents, data sources, security, deployment

---

Documentation

Document	Contents
CURRENT_SYSTEM_AUDIT.md	Audit of the prototype this replaced
PDP_MODULE.md	Stage gates: the no-false-green rule, roles, endpoints
ARCHITECTURE.md	System design and data model
AGENT_WORKFLOW.md	Each agent, the graph, routing
DATA_SOURCES.md	Providers, credentials, rate limits
SECURITY.md	Auth, RLS, secrets, prompt injection
DEPLOYMENT.md	Production deployment
KNOWN_LIMITATIONS.md	What is unverified or missing

Read KNOWN_LIMITATIONS.md before relying on any output. It states plainly which paths have been exercised against live services and which have only been tested against fixtures.