Edison Integration Tutorial

Edison Scientific provides AI-powered hypothesis generation by analyzing scientific literature. This tutorial shows you how to use Edison to generate testable hypotheses.

What Edison Does

Analyzes your research query — Understands what you want to investigate
Searches scientific literature — Finds relevant papers and studies
Generates hypotheses — Creates testable statements with supporting rationale
Suggests experiment types — Recommends appropriate assays
Provides reasoning trace — Shows how it arrived at conclusions

Starting an Edison Run

Basic Query

curl -X POST https://api.litmus.science/cloud-labs/edison/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Novel antimicrobial peptides targeting gram-negative bacteria"
  }'

Response:

{
  "run_id": "edison_run_abc123",
  "status": "PENDING",
  "query": "Novel antimicrobial peptides targeting gram-negative bacteria"
}

With Experiment Type Preference

curl -X POST https://api.litmus.science/cloud-labs/edison/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Mechanisms of antibiotic resistance in hospital infections",
    "experiment_type": "MIC_MBC_ASSAY"
  }'

Checking Run Status

Edison runs are asynchronous. Poll for completion:

curl https://api.litmus.science/cloud-labs/edison/runs/edison_run_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Status Values

Status	Description
`PENDING`	Queued, waiting to start
`RUNNING`	Analysis in progress
`COMPLETED`	Results ready
`FAILED`	Error occurred

Example: Polling Loop

import requests
import time
 
API_URL = "https://api.litmus.science"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
 
# Start the run
response = requests.post(
    f"{API_URL}/cloud-labs/edison/start",
    json={"query": "Novel approaches to treating resistant infections"},
    headers=headers
)
run_id = response.json()["run_id"]
 
# Poll until complete
while True:
    status = requests.get(
        f"{API_URL}/cloud-labs/edison/runs/{run_id}",
        headers=headers
    ).json()
 
    print(f"Status: {status['status']}")
 
    if status["status"] == "COMPLETED":
        print("Hypothesis:", status["result"]["hypothesis"]["statement"])
        break
    elif status["status"] == "FAILED":
        print("Error:", status["error"])
        break
 
    time.sleep(5)  # Wait 5 seconds before next poll

Understanding Results

A completed Edison run includes:

{
  "run_id": "edison_run_abc123",
  "status": "COMPLETED",
  "query": "Novel antimicrobial peptides",
  "experiment_type": "MIC_MBC_ASSAY",
  "result": {
    "hypothesis": {
      "statement": "Cationic peptides with alpha-helical structure disrupt gram-negative outer membranes",
      "null_hypothesis": "Peptide structure has no effect on membrane integrity"
    },
    "reasoning_trace": [
      {
        "step": 1,
        "action": "literature_search",
        "summary": "Searched for antimicrobial peptide mechanisms"
      },
      {
        "step": 2,
        "action": "analyze_findings",
        "summary": "Identified membrane disruption as primary mechanism"
      },
      {
        "step": 3,
        "action": "formulate_hypothesis",
        "summary": "Generated testable hypothesis based on structural features"
      }
    ],
    "sources": [
      {
        "title": "Mechanisms of antimicrobial peptide action",
        "doi": "10.1000/example",
        "relevance": "Primary source for membrane disruption mechanism"
      }
    ]
  }
}

Editing the Draft

Before saving, you can refine the generated hypothesis:

curl -X PATCH https://api.litmus.science/cloud-labs/edison/runs/edison_run_abc123/draft \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "edited_hypothesis": {
      "statement": "Cationic peptide AMP-7 disrupts E. coli outer membrane with IC50 < 10 μM",
      "null_hypothesis": "AMP-7 has no effect on E. coli membrane integrity"
    }
  }'

Saving to Hypothesis Library

Save the generated hypothesis for future use:

curl -X POST https://api.litmus.science/hypotheses \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Edison: Antimicrobial peptide mechanism",
    "statement": "Cationic peptide AMP-7 disrupts E. coli outer membrane with IC50 < 10 μM",
    "null_hypothesis": "AMP-7 has no effect on E. coli membrane integrity",
    "experiment_type": "MIC_MBC_ASSAY",
    "edison_query": "Novel antimicrobial peptides targeting gram-negative bacteria",
    "edison_response": {...}
  }'

Managing Edison Runs

List All Runs

curl "https://api.litmus.science/cloud-labs/edison/runs?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Active Run

Check if you have a run in progress:

curl https://api.litmus.science/cloud-labs/edison/active \
  -H "Authorization: Bearer YOUR_TOKEN"

Clear History

Remove old runs:

curl -X POST https://api.litmus.science/cloud-labs/edison/runs/clear-history \
  -H "Authorization: Bearer YOUR_TOKEN"

Writing Effective Queries

Good Queries

"Novel mechanisms for enhancing antibiotic efficacy against resistant bacteria"
"Small molecule inhibitors of bacterial efflux pumps"
"Synergistic combinations of existing antibiotics"

Tips

Be specific — Include the biological target or mechanism
Mention context — "for drug-resistant infections" helps focus results
Specify constraints — "using cell-based assays" guides experiment suggestions
Ask testable questions — Avoid overly broad topics

Complete Workflow Example

import requests
import time
 
API_URL = "https://api.litmus.science"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
 
# 1. Start Edison
print("Starting Edison analysis...")
run = requests.post(
    f"{API_URL}/cloud-labs/edison/start",
    json={
        "query": "Novel compounds that inhibit bacterial biofilm formation",
        "experiment_type": "MIC_MBC_ASSAY"
    },
    headers=headers
).json()
 
# 2. Wait for completion
while True:
    status = requests.get(
        f"{API_URL}/cloud-labs/edison/runs/{run['run_id']}",
        headers=headers
    ).json()
 
    if status["status"] in ["COMPLETED", "FAILED"]:
        break
    time.sleep(5)
 
if status["status"] == "FAILED":
    print(f"Edison failed: {status['error']}")
    exit(1)
 
# 3. Save hypothesis
hypothesis = requests.post(
    f"{API_URL}/hypotheses",
    json={
        "title": "Biofilm inhibition hypothesis",
        "statement": status["result"]["hypothesis"]["statement"],
        "null_hypothesis": status["result"]["hypothesis"]["null_hypothesis"],
        "experiment_type": status["experiment_type"],
        "edison_response": status["result"]
    },
    headers=headers
).json()
 
print(f"Saved hypothesis: {hypothesis['id']}")
 
# 4. Convert to experiment
experiment = requests.post(
    f"{API_URL}/hypotheses/{hypothesis['id']}/to-experiment",
    json={
        "additional_fields": {
            "compliance": {"bsl": "BSL1"},
            "privacy": "open"
        }
    },
    headers=headers
).json()
 
print(f"Created experiment: {experiment['experiment_id']}")

Next Steps

Hypothesis Library — Manage saved hypotheses
Cloud Labs — Automate experiment execution
API Reference — Full Edison endpoint documentation

Hypothesis Library Protocol Selection