Future House Edison Client Crow Literature Qa

---
name: crow-literature-qa
description: Fast scientific literature Q&A with citations via FutureHouse's Crow agent (production PaperQA2). Use when the user wants a single, well-cited answer drawn from the published scientific literature — biology, chemistry, medicine, ML, etc. Handles one focused question per call. For multi-paper thematic synthesis use Falcon; for "has anyone done X" precedent queries use Owl.
metadata:
  skill-author: Compiled from FutureHouse edison-client (Apache-2.0)
  upstream: https://github.com/Future-House/edison-client-docs
---

# Crow — Scientific Literature Q&A (FutureHouse Platform)

Crow is FutureHouse's fast, production literature search agent. It is the deployed version of [PaperQA2](https://github.com/Future-House/paper-qa). Behind the scenes it searches Semantic Scholar, Crossref, and other indexes, fetches full text, runs the PaperQA2 retrieval-augmented generation pipeline, and returns a grounded answer with in-text citations.

Use this skill when the user asks a focused factual question about the scientific literature ("What is known about X?", "What dose of Y was used in study Z?", "Summarize evidence on …"). For broader review-style questions hand off to Falcon; for chemistry-specific questions hand off to Phoenix.

## Prerequisites

- `pip install edison-client` (or `uv pip install edison-client`)
- `EDISON_API_KEY` in env. Get one from <https://platform.edisonscientific.com/profile> → Account → API Tokens. Free tier exists; deeper queries consume credits.

## Minimal usage

```python
from edison_client import EdisonClient, JobNames

client = EdisonClient(api_key=os.environ["EDISON_API_KEY"])
resp = client.run_tasks_until_done({
    "name": JobNames.LITERATURE,                  # alias for Crow
    "query": "What dose of semaglutide is used for chronic weight management in adults?",
})
print(resp.formatted_answer)                      # answer with [Author Year] inline citations
```

`resp` is a `PQATaskResponse` with:

| field | meaning |
|---|---|
| `answer` | plain answer text |
| `formatted_answer` | answer with inline citations and reference list |
| `has_successful_answer` | bool — whether the agent actually grounded its answer |

## Recipes

### Batch many questions in parallel
```python
import asyncio
from edison_client import EdisonClient, JobNames

async def main():
    client = EdisonClient(api_key=os.environ["EDISON_API_KEY"])
    queries = [
        "What is the half-life of remdesivir?",
        "What efficacy did GLP-1 agonists show in NAFLD trials?",
        "Latest evidence on creatine for cognitive function in older adults?",
    ]
    tasks = [{"name": JobNames.LITERATURE, "query": q} for q in queries]
    results = await client.arun_tasks_until_done(tasks)
    for q, r in zip(queries, results):
        print(q, "→", r.has_successful_answer, "\n", r.answer[:400], "\n")

asyncio.run(main())
```

### Follow-up question on a previous answer
```python
first_id = client.create_task({
    "name": JobNames.LITERATURE,
    "query": "How many species of birds are there?",
})
follow_up = client.run_tasks_until_done({
    "name": JobNames.LITERATURE,
    "query": "Of those, how many are corvids?",
    "runtime_config": {"continued_job_id": first_id},
})
```

### Fire-and-poll
```python
task_id = client.create_task({"name": JobNames.LITERATURE, "query": "..."})
# … do other work …
status = client.get_task(task_id)   # status.status: 'queued' | 'running' | 'success' | 'failed'
```

## Picking the right FutureHouse agent

| If user wants… | Use |
|---|---|
| One focused literature answer (fast) | **Crow** = `JobNames.LITERATURE` (this skill) |
| Same, but maximum reasoning quality | **Falcon** = `JobNames.LITERATURE_HIGH` |
| "Has anyone ever done / measured / tried X?" | **Owl** = `JobNames.PRECEDENT` |
| Synthesis route, molecule design, cheminformatics | **Phoenix** = `JobNames.MOLECULES` |
| Run analysis on a biological dataset | **Finch** = `JobNames.ANALYSIS` |

## Failure modes

- `has_successful_answer == False`: the agent looked but couldn't ground a confident answer. Show the user `resp.answer` (often "I don't know" with reasons) rather than fabricating.
- 401 / `Unauthorized`: `EDISON_API_KEY` missing or invalid.
- `Insufficient credits`: tell the user to top up at <https://platform.edisonscientific.com/profile>.
- Long queries can take 30 s – 3 min. Use `arun_tasks_until_done` for parallel batches.