# Locus Pocus

> A free, open-source primer-design tool for genomic loci. Runs Primer3 + NCBI-BLAST against Ensembl reference genomes for the standard model organisms. Supports flanking primers, junction PCRs for knock-ins, three-primer genotyping sets, and SNP-sensitive primers.

Locus Pocus has two front-door experiences:

- A **manual wizard** at https://locuspocus.co/design/new/reference (Reference → Locus → Run → Results)
- An **AI assistant** at https://locuspocus.co/design/ai that asks the minimum questions, accepts FASTA uploads, then submits the design through the same deterministic Primer3 + BLAST pipeline

The same REST API powers both experiences. AI agents can call it directly using a user-minted API key.

## Calling the API as an agent

1. The user mints an API key from https://locuspocus.co/me/api-keys (one-time copy; SHA-256 hashed at rest).
2. Authenticate every request with `Authorization: Bearer lp_live_<32hex>`.
3. Daily quotas apply (50 designs / 5000 gene resolves for authenticated users; refused requests at 429).

Full OpenAPI schema: https://locus-pocus-backend.onrender.com/openapi.json

## Key endpoints

- `POST /design` — Run the design pipeline. Streams a JSON envelope; final body is `{result: DesignResult}` or `{error: {...}}`.
- `POST /validate-input` — Pre-flight validation. Returns `{valid: bool, errors: [...], warnings: [...]}`.
- `POST /resolve-target` — Resolve a gene symbol or coordinate to genomic position + transcript info.
- `POST /genes/suggest` — Autocomplete gene names for a given organism.
- `GET /organisms` — List available reference genomes.
- `GET /references/status` — Per-organism download/index status.
- `POST /references/download` — Trigger download + BLAST indexing of an Ensembl genome.
- `GET /defaults` — Primer constraints, scoring weights, PCR conditions, specificity defaults.

## Minimal example

```bash
curl -X POST https://locus-pocus-backend.onrender.com/design \
  -H "Authorization: Bearer lp_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "organism_id": "c_elegans",
    "gene_input": {"input_type": "gene_symbol", "value": "unc-22"},
    "target": {"anchor_type": "TSS", "upstream_bp": 500, "downstream_bp": 500},
    "design_modes": ["flanking"],
    "pcr": {"polymerase_id": "neb_q5_hot_start"}
  }'
```

The response is a `DesignResult` containing ranked primer sets with Tm, GC%, predicted off-targets, and an export-ready protocol.

## Design modes

- `flanking` — external forward + reverse around a target window
- `left_junction` / `right_junction` — one primer in the genome, one in an inserted/replaced sequence (for knock-ins)
- `three_primer` — genotyping sets that distinguish edited from unedited alleles
- `snp_sensitive` — allele-discriminating primers for 1-bp replacements

Junction modes require an `edit` of type `insertion` or `replacement` in the request.

## Topic scope (in-app AI assistant)

The AI assistant at /design/ai is restricted to PCR primer design tasks. Off-topic prompts (general knowledge, code review, writing help, etc.) are refused. For non-primer questions, please use Claude or ChatGPT directly.

## More

- Source code: https://github.com/frnkmxwll/locus-pocus
- Privacy policy: https://locuspocus.co/privacy
- Terms of service: https://locuspocus.co/terms
- Contact: https://locuspocus.co/contact