Skip to main content

EdisonScientific Platform API Documentation

Documentation and tutorials for edison-client, a client for interacting with endpoints of the EdisonScientific platform.

See our cookbook for detailed documentation on usage.


Table of Contents


Installation

uv pip install edison-client

For YAML directory manifests, install edison-client[yaml].

Quickstart

from edison_client import EdisonClient, JobNames

# Set your API key to EDISON_API_KEY environment variable,
# or pass it as a string literal to the api_key parameter
client = EdisonClient()

task_data = {
    "name": JobNames.LITERATURE,
    "query": (
        "Which neglected diseases had a treatment developed by artificial intelligence?"
    ),
}
(task_response,) = client.run_tasks_until_done(task_data)

run_tasks_until_done() always returns a list, even for a single task, so single-task examples unpack the first element with (task_response,) = ....

A quickstart example can be found in the client_notebook.ipynb file, where we show how to submit and retrieve a job task, pass runtime configuration to the agent, and ask follow-up questions to the previous job.

Functionalities

EdisonScientific client implements a RestClient (called EdisonClient) with the following functionalities:

  • Simple task running: run_tasks_until_done(TaskRequest) or await arun_tasks_until_done(TaskRequest)
  • Asynchronous tasks: get_task(task_id) or aget_task(task_id) and create_task(TaskRequest) or acreate_task(TaskRequest)

To create a EdisonClient, you need to pass an EdisonScientific platform api key (see Authentication):

from edison_client import EdisonClient

# Set your API key to EDISON_API_KEY environment variable
client = EdisonClient()
# Or pass it as a string literal to the api_key parameter
client = EdisonClient(api_key="your_api_key")

Authentication

In order to use the EdisonClient, you need to authenticate yourself. Authentication is done by providing an API key, which can be obtained directly from your profile page in the EdisonScientific platform.

Simple task running

In the EdisonScientific platform, we define the deployed combination of an agent and an environment as a job. To invoke a job, we need to submit a task (also called a query) to it. EdisonClient can be used to submit tasks/queries to available jobs in the EdisonScientific platform. Using a EdisonClient instance, you can submit tasks to the platform by calling the create_task method, which receives a TaskRequest (or a dictionary with kwargs) and returns the task id. Aiming to make the submission of tasks as simple as possible, we have created a JobNames enum that contains the available task types.

The available supported jobs are:

Alias Available Aliases Task type Description
JobNames.LITERATURE literature-20260216, JobNames.CROW, JobNames.FALCON Literature Search Ask a question of scientific data sources, and receive a high-accuracy, cited response. Built with PaperQA3.
JobNames.LITERATURE_HIGH literature-high-20260216 Literature Search Ask a question of scientific data sources, and receive a high-accuracy, cited response. High reasoning mode enabled for SOTA performance.
JobNames.ANALYSIS JobNames.FINCH Data Analysis Turn biological datasets into detailed analyses answering your research questions.
JobNames.PRECEDENT JobNames.OWL Precedent Search Formerly known as HasAnyone, query if anyone has ever done something in science.
JobNames.MOLECULES JobNames.PHOENIX Chemistry Tasks A new iteration of ChemCrow, Phoenix uses cheminformatics tools to do chemistry. Good for planning synthesis and designing new molecules.
JobNames.DUMMY N/A Dummy Task This is a dummy task. Mainly for testing purposes.

Using JobNames, the task submission looks like this:

from edison_client import EdisonClient, JobNames

client = EdisonClient()

task_data = {
    "name": JobNames.PRECEDENT,
    "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
}
(task_response,) = client.run_tasks_until_done(task_data)
print(task_response.answer)

Or if running async code:

import asyncio
from edison_client import EdisonClient, JobNames


async def main():
    client = EdisonClient(
        api_key="your_api_key",
    )

    task_data = {
        "name": JobNames.PRECEDENT,
        "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
    }
    (task_response,) = await client.arun_tasks_until_done(task_data)
    print(task_response.answer)
    return task_id


# For Python 3.7+
if __name__ == "__main__":
    task_id = asyncio.run(main())

Note that in either the sync or the async code, collections of tasks can be given to the client to run them in a batch:

import asyncio
from edison_client import EdisonClient, JobNames


async def main():
    client = EdisonClient()

    task_data = [
        {
            "name": JobNames.PRECEDENT,
            "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
        },
        {
            "name": JobNames.LITERATURE,
            "query": (
                "Are there any clinically validated therapeutic exerkines for humans?"
            ),
        },
    ]
    task_responses = await client.arun_tasks_until_done(task_data)
    print(task_responses[0].answer)
    print(task_responses[1].answer)
    return task_id


# For Python 3.7+
if __name__ == "__main__":
    task_id = asyncio.run(main())

TaskRequest can also be used to submit jobs and it has the following fields:

Field Type Description
id UUID Optional job identifier. A UUID will be generated if not provided
name str Name of the job to execute eg. job-futurehouse-paperqa2, or using the JobNames for convenience: JobNames.LITERATURE
query str Query or task to be executed by the job
runtime_config RuntimeConfig Optional runtime parameters for the job

runtime_config can receive an AgentConfig object with the desired kwargs. Check the available AgentConfig fields in the LDP documentation. Besides the AgentConfig object, we can also pass timeout to limit the execution time of the agent.

from edison_client import EdisonClient, JobNames
from edison_client.models.app import TaskRequest

client = EdisonClient()

(task_response,) = client.run_tasks_until_done(
    TaskRequest(
        name=JobNames.PRECEDENT,
        query="Has anyone tested therapeutic exerkines in humans or NHPs?",
    )
)
print(task_response.answer)

A TaskResponse will be returned from using our agents. For Owl, Crow, and Falcon, we default to a subclass, PQATaskResponse which has some key attributes:

Field Type Description
answer str Answer to your query.
formatted_answer str Specially formatted answer with references.
has_successful_answer bool Flag for whether the agent was able to find a good answer to your query or not.

If using the verbose setting, much more data can be pulled down from your TaskResponse, which will exist across all agents (not just Owl, Crow, and Falcon).

from edison_client import EdisonClient, JobNames
from edison_client.models.app import TaskRequest

client = EdisonClient(
    api_key="your_api_key",
)

(task_response,) = client.run_tasks_until_done(
    TaskRequest(
        name=JobNames.PRECEDENT,
        query="Has anyone tested therapeutic exerkines in humans or NHPs?",
    ),
    verbose=True,
)
print(task_response.environment_frame)

In that case, a TaskResponseVerbose will have the following fields:

Field Type Description
agent_state dict Large object with all agent states during the progress of your task.
environment_frame dict Large nested object with all environment data, for PQA environments it includes contexts, paper metadata, and answers.
metadata dict Extra metadata about your query.

Task Continuation

Once a task is submitted and the answer is returned, EdisonScientific platform allow you to ask follow-up questions to the previous task. It is also possible through the platform API. To accomplish that, we can use the runtime_config we discussed in the Simple task running section.

from edison_client import EdisonClient, JobNames

client = EdisonClient(
    api_key="your_api_key",
)

task_data = {
    "name": JobNames.LITERATURE,
    "query": "How many species of birds are there?",
}
task_id = client.create_task(task_data)

continued_task_data = {
    "name": JobNames.LITERATURE,
    "query": (
        "From the previous answer, specifically, how many species of crows are there?"
    ),
    "runtime_config": {"continued_task_id": task_id},
}
(task_response,) = client.run_tasks_until_done(continued_task_data)

Asynchronous tasks

Sometimes you may want to submit many jobs, while querying results at a later time. In this way you can do other things while waiting for a response. The platform API supports this as well rather than waiting for a result.

from edison_client import EdisonClient, JobNames

client = EdisonClient()

task_data = {
    "name": JobNames.LITERATURE,
    "query": "How many species of birds are there?",
}
task_id = client.create_task(task_data)

# move on to do other things

task_status = client.get_task(task_id, lite=True)
print(task_status.status)

task_status includes task_id, query, and status. You can continually query the status until it's success before moving on.

Metadata

Release files for edison-client 0.19.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for edison-client 0.19.0
File Size Uploaded Provenance Actions
edison_client-0.19.0.tar.gz 259.6 kB Without provenance Details for edison_client-0.19.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for edison-client 0.19.0
File Interpreter ABI Platform Actions
edison_client-0.19.0-py3-none-any.whl Python 3 none any Details for edison_client-0.19.0-py3-none-any.whl

Total release size: 367.5 kB

Release files / edison_client-0.19.0.tar.gz

Download URL edison_client-0.19.0.tar.gz
Size 259.6 kB
Tags Source
SHA-256 checksum
How to use checksums
f2eab249902d61274df67226afcad178907566cea09d2a28bda225985af78bd8
BLAKE2b-256 checksum
How to use checksums
666df98386e0bcd87788c200c6c45377c7ff2ea59dc847cb34de4704c27b6104
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / edison_client-0.19.0-py3-none-any.whl

Download URL edison_client-0.19.0-py3-none-any.whl
Size 107.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c6e8e653698709af64f83915d847e7e012384c2e229614d9d3786a06ec76ed52
BLAKE2b-256 checksum
How to use checksums
ff21aa36c47a7e354ba9dba11be42dde537bbb2e7169af8fd013c81d67230cd9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for edison-client 0.19.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.19.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page