# Endo Lab — long-form introduction for AI agents

Endo Lab is a federated research corpus for endometriosis and adenomyosis.
It pulls metadata from 11 public sources, normalises onto a license-aware
schema, and exposes a hybrid (BM25 + vector) search API.

## When to use Endo Lab

- "Find recent RCTs on dienogest for endometriosis pain" → POST /search
- "Hydrate this list of 50 DOIs" → POST /papers/lookup (phase C)
- "What's the trend in adolescent endometriosis prevalence studies?"
  → GET /research/api/explore/prevalence
- "Export the papers in my chat thread as BibTeX / RIS" → POST /research/chat/citations (available)
- "Give me a Vancouver-style citation for this paper" → GET /papers/{id}/citation (phase B)

## First-party reference agent

`/research/chat` is a working corpus-tool LLM agent built on a 7-tool
surface defined as stable JSON schemas in
`src/endo_lab/agent/tools.py`: `search_corpus`, `find_recent`,
`get_paper`, `ask_paper`, `compare_papers`, `get_trial`, `get_grant`.

The MCP server (phase D of the agent-support spec) is not yet
shipped. The intended starting surface is the same 7 tools; the
final MCP inventory may grow per the spec at
docs/superpowers/specs/2026-05-17-ai-agent-support.md. Drive
`/research/chat` directly today to see the shape of responses the
MCP server will return.

## When NOT to use Endo Lab

- Medical advice / clinical decisions — out of scope, see /terms.
- Real-time trial recruitment status — registries (ClinicalTrials.gov,
  WHO ICTRP) are the authoritative source; we mirror them periodically.

## Source license matrix

| Source | License | Commercial OK | Redistribution |
|---|---|---|---|
| OpenAlex | CC0 | yes | yes |
| Crossref metadata | CC0 | yes | yes |
| PubMed (NLM) | US public domain | yes | yes (courtesy attribution) |
| Europe PMC metadata | CC0 / CC-BY | mostly | mostly |
| Unpaywall | CC0 | yes | yes |
| ClinicalTrials.gov | US public domain | yes | yes |
| NIH RePORTER | US public domain | yes | yes |
| EU CORDIS | CC-BY 4.0 | yes (with attribution) | yes |
| WHO ICTRP | TOU non-commercial only | **no** | restricted |
| PMC full text | varies per paper | varies | per paper |
| SciLite annotations | CC-BY | yes | yes (attribute Europe PMC) |
| Publisher abstracts | publisher copyright | fair-use only | fair-use only |

## Self-discovery

- /openapi.json — full OpenAPI 3.1 spec with operation_ids, summaries,
  descriptions on every endpoint.
- /docs — interactive Swagger UI (humans).
- /agents — install recipes (MCP, OpenAPI, cURL) and example prompts.

## Identification & rate limits

Anonymous use: 60 requests/minute per IP. Authenticated keys (phase E of
the agent-support spec): higher quotas. Every response carries
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (phase C);
back off before exhausting the bucket.

## Trust posture

No advertising, no paid placement. Server-side enforcement of license
gates (ICTRP non-commercial click-through, PMC-NC full-text stub). All
requests audit-logged with IP anonymisation.

Project lead: Denisha Labuschagne — Honours graduate, SACAP; MA candidate,
University of Pretoria.