Metadata-Version: 2.4
Name: biocatalystfeed
Version: 0.3.2
Summary: Open-source monitors for biotech catalysts: ClinicalTrials.gov, openFDA, NIH RePORTER, PubMed/Europe PMC/bioRxiv, SEC EDGAR, EMA, FDA advisory committees (Federal Register). CLI + MCP server.
License-Expression: Apache-2.0
Project-URL: Homepage, https://biocat.ai
Project-URL: Source, https://github.com/biocatalystfeed/biocatalystfeed
Project-URL: Issues, https://github.com/biocatalystfeed/biocatalystfeed/issues
Keywords: biotech,clinical-trials,fda,pubmed,mcp,sec-edgar,ema,fda-advisory-committee,monitoring
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests>=2.28
Requires-Dist: mcp>=1.2
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

<p><img src="assets/brand/logo-icon.svg" alt="BioCatalystFeed logo" width="64" height="64"></p>

# BioCatalystFeed

<!-- mcp-name: io.github.biocatalystfeed/biocatalystfeed -->

Website: https://biocat.ai · Contact: contact@biocat.ai

**An open-source catalyst feed for biotech: see what changed across clinical trials, FDA and EMA actions, NIH grants,
papers/preprints and SEC filings for the companies and drugs you follow.** Use it as a CLI, as an MCP server for AI
agents (Claude, Cursor, …), or as an [Apify actor](https://apify.com/biocatalystfeed/biocatalystfeed-clinicaltrials-monitor).

> ⚠️ **Not investment, legal or medical advice.** Data may be incomplete, delayed or wrong; PDUFA dates are unverified
> candidates from SEC filings. Always check the linked primary source.

## What it does
| Source | Command | What you get |
|---|---|---|
| ClinicalTrials.gov API v2 (NLM) | `bcf trials` | search, sponsor pipelines, **diffs**: new trials, status/phase/enrollment/date, primary-endpoint, arm, intervention, site-count and results-posted changes, each labelled **critical / notable / minor** |
| openFDA (Drugs@FDA, SPL labels) | `bcf fda` | approvals (incl. novel NME/BLA flag), submissions, label revisions, diffs |
| NIH RePORTER | `bcf grants` | grants by org / PI (middle-initial aware) / keyword; new awards, amount changes |
| PubMed + **Europe PMC** + bioRxiv/medRxiv | `bcf papers` | papers & preprints, **deduplicated by DOI/PMID** across sources |
| SEC EDGAR | `bcf sec` | 8-K mentions of PDUFA dates (UNVERIFIED candidates, linked to the filing) |
| European Medicines Agency (EMA) | `bcf ema` | EU centrally authorised medicines: CHMP opinions, EC authorisations, refusals, withdrawals, suspensions; orphan/PRIME flags; diffs |
| Federal Register (FDA notices) | `bcf adcom` | FDA advisory committee meetings: committee, meeting date, NDA/BLA numbers and sponsors from the agenda; postponements/cancellations; diffs |
| All of the above | `bcf profile` | one merged company profile (name or ticker) |

**Optional global coverage (`--global` / `include_global`).** Off by default. When you turn it on, BCF also links to records in trial registries outside the US and EU, such as China's ChiCTR and other WHO-listed national registries, and flags papers from other jurisdictions. These records may come from research run under regulatory, ethics and data standards different from, and sometimes lighter than, those of the US or EU. They are labelled "non-FDA/EMA registry". The option is for users who want to see everything that is out there. Inclusion is not an endorsement or recommendation and is not medical, legal or investment advice.

Records are links (registry ID + URL, from ClinicalTrials.gov secondary IDs); papers get `jurisdiction_flag` from author-affiliation countries (`"unknown"` when none is found). Details: `bcf --global --help` or [docs/GLOBAL.md](docs/GLOBAL.md).

Across tools: `--exclude TERM …` to drop noise, `--rank` for relevance ordering, and `--rss` / `--json-feed` digest
files on every `watch` (local files you can serve or feed into any reader; nothing is emailed).

## Quickstart
```bash
python3 -m venv .venv && source .venv/bin/activate   # macOS/Homebrew Python blocks global pip installs (PEP 668)
pip install biocatalystfeed
# no venv needed:  uvx --from biocatalystfeed bcf --help    or    pipx install biocatalystfeed

bcf trials search --sponsor "Viking Therapeutics" --phase PHASE3
bcf papers search --drug resmetirom --since 2026-09-01 --exclude mice rat --rank
bcf grants search --pi "Ioannou, George N" --since 2024-01-01 --no-future
bcf sec pdufa MDGL --since 2023-01-01
bcf profile Lilly MDGL "Viking Therapeutics" --md profiles.md
bcf ema search --status Opinion --since 2026-09-01          # latest CHMP opinions (EU)
bcf adcom upcoming --area drugs biologics                   # scheduled FDA advisory committee meetings

# watches: first run = baseline, later runs report what changed (cron it daily)
bcf trials --db bcf.db watch --name obesity --condition obesity --phase PHASE3 --rss obesity.rss
bcf trials --db bcf.db changes --name obesity --min-severity critical   # terminations, endpoint rewrites
bcf papers --db bcf.db watch --name mdgl --affiliation "Madrigal Pharmaceuticals" --json-feed mdgl.feed.json
```
Global flags such as `--db` go **after the tool name and before the subcommand**: `bcf trials --db bcf.db changes`, not `bcf --db bcf.db trials changes` or `bcf trials changes --db bcf.db`.
`bcf trials changes` prints a readable one-line-per-change summary; add `--json` for one JSON object per line.
PubMed `--since`/`--until` filter on the publication date shown in the output (Europe PMC uses first-publication date).

The old commands (`trialwatch`, `fdawatch`, `grantwatch`, `paperwatch`, `secwatch`, `trialwatch-mcp`) still work.

### MCP server
```json
{"mcpServers": {"biocatalystfeed": {"command": "uvx", "args": ["biocatalystfeed", "mcp"],
  "env": {"BIOCATALYSTFEED_DB": "/path/to/bcf.db"}}}}
```
(or point `command` at an installed `biocatalystfeed-mcp`). Listed in the official MCP Registry as
`io.github.biocatalystfeed/biocatalystfeed`.
Tools include `search_trials`, `sponsor_pipeline`, `fda_approvals`, `company_profile`, `search_grants`,
`search_papers`, `sec_pdufa_mentions`, `ema_medicines`, `fda_adcom_meetings`, `snapshot_*` / `*_changes_since`, and `changes_feed` (RSS / JSON Feed).

### Configuration
| Env var | Purpose |
|---|---|
| `BIOCATALYSTFEED_CONTACT` | contact email put in the SEC User-Agent (SEC fair-access policy). Default is the project contact (`contact@biocat.ai`); set it to your own contact for heavy SEC use |
| `SEC_USER_AGENT` | full SEC User-Agent override |
| `NCBI_EMAIL` | optional email sent to NCBI E-utilities |
| `OPENFDA_API_KEY` | optional openFDA API key (free at open.fda.gov/apis/authentication); raises daily/minute rate limits. Never logged |
| `NCBI_API_KEY` | optional NCBI E-utilities API key (free from your NCBI account settings); raises the PubMed limit from 3 to 10 req/s. Never logged |
| `BIOCATALYSTFEED_DB` (or `TRIALWATCH_DB`) | SQLite DB for the MCP server |
| `FDAWATCH_ALIASES` | JSON file extending the company alias table |

## How it compares
Facts about DataLookout are from datalookout.com, its /citeline-alternative and /clinical-trial-monitoring pages (checked 2026-10-21 PT). We have not tested
their product. Fuller, cited comparison: [`docs/COMPARISON.md`](docs/COMPARISON.md).

| | BioCatalystFeed (open source) | DataLookout |
|---|---|---|
| Price | Free (Apache-2.0); free rate-limited hosted MCP endpoint | Free tier; Pro $49/month |
| Sources | ClinicalTrials.gov, openFDA, NIH RePORTER, PubMed, Europe PMC, bioRxiv/medRxiv, SEC EDGAR, EMA, Federal Register (FDA AdComs) | ClinicalTrials.gov |
| Change tracking | Diffs between your own runs (trials: status, phase, enrollment, dates, sponsor, title, why stopped, primary endpoints, arms, interventions, site counts, results posting; severity critical/notable/minor; plus FDA, EMA, AdCom, grant, paper and SEC changes) | Daily scan; 13 fields incl. status, enrollment, primary endpoints, interventions, results, site counts, completion dates; changes marked Stopped/Notable/Minor |
| Delivery | CLI, MCP server for AI agents (local, or hosted read-only subset), RSS/JSON Feed files, Apify actor | Morning email digest + dashboard inbox |
| Watch limits | None when self-hosted | Free: 1 sponsor + 1 disease watchlist + 1 saved search; Pro: 10 of each |
| Scheduling | You run it (cron, Apify schedule) | Hosted, daily |
| Setup | Python install | "2 minutes" (their claim) |

Pick DataLookout for a hosted, emailed, ClinicalTrials.gov-only digest. Pick BioCatalystFeed if you want several
sources per company or ticker, agent/MCP access, or to self-host.

### Trial change severity (v0.3.0)
Every trial change carries `severity`, and date changes carry `shift_days`:
- **critical**: status moves to TERMINATED / SUSPENDED / WITHDRAWN, a why-stopped reason appears, or the primary
  endpoint(s) are rewritten.
- **notable**: other status or phase changes, new trials, lead-sponsor changes, results posted, arm or intervention
  changes, enrollment changes of 20% or more, start / primary completion / completion dates moved 30+ days.
- **minor**: everything else (small date or enrollment tweaks, site-count changes, title edits).

Filter with `--min-severity notable|critical` on `bcf trials watch` / `changes`, or `min_severity` in the MCP tool
`trial_changes_since`. Snapshots made by older versions start tracking the new fields on their next run, so upgrading
doesn't produce a burst of false changes.

### Search filters (v0.2.1)
- `--exclude` takes words or phrases (space- or comma-separated); matching is whole-word and case-insensitive, and a
  trailing `*` is a prefix wildcard (`--exclude "murin*" rat`).
- `--rank` scores title hits 3 and other-field hits 1 (simple plurals tolerated), +1 for exact multi-word phrases in
  the title and +2 when every query term matches; ties break by newest date. The score is in `relevance`.

## Data sources, limits and etiquette
Built-in throttles follow each source's published policy (e.g. NIH RePORTER 1 req/s, NCBI ≤3 req/s without key, SEC
≤10 req/s with a declared User-Agent, openFDA 1,000 req/day per IP without key). We store **metadata and links only**
for papers/preprints, never abstracts. Change detection only covers your own runs; there's no historical backfill.
PDUFA dates are regex extractions from 8-K text, not a calendar. Data provided by the U.S. Food and Drug Administration (https://open.fda.gov). Source: European Medicines Agency
(EMA), https://www.ema.europa.eu. Full attributions are in [`NOTICE`](NOTICE). Design notes
and per-source terms are in [`docs/DEVELOPER-NOTES.md`](docs/DEVELOPER-NOTES.md).

## Hosted MCP endpoint (free)
A free, read-only, rate-limited MCP endpoint (Streamable HTTP, no account) runs on Cloudflare Workers:

    https://bcf-mcp.lively-recipe-5a12.workers.dev/mcp

```json
{"mcpServers": {"biocatalystfeed-hosted": {"type": "http", "url": "https://bcf-mcp.lively-recipe-5a12.workers.dev/mcp"}}}
```
It offers 5 tools (`search_trials`, `get_trial`, `fda_approvals`, `search_papers`, `fda_adcom_meetings`) over
ClinicalTrials.gov, openFDA, PubMed and the Federal Register. Limit: 30 requests/minute per IP (HTTP 429 above that).
Watches, change history and the other sources need the local install above. No request logs are kept; see
[`TERMS.md`](TERMS.md) and [`PRIVACY.md`](PRIVACY.md). Source: [`worker/`](worker/).

## Contributing / Testing
```bash
git clone https://github.com/biocatalystfeed/biocatalystfeed && cd biocatalystfeed
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
pytest                      # offline tests; live-API tests are skipped by default
TRIALWATCH_LIVE=1 pytest    # also run tests that call the real public APIs (needs network; slower)
```

## Contributing & licence
See [`CONTRIBUTING.md`](CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) and [`SECURITY.md`](SECURITY.md) (report vulnerabilities privately). Licensed under the [Apache License 2.0](LICENSE). BioCatalystFeed is
independent and not endorsed by NLM, NIH, FDA, SEC, EMA, the Office of the Federal Register, EMBL-EBI/Europe PMC, or bioRxiv/medRxiv.
