futurehouse-client 0.0.3__tar.gz → 0.0.5__tar.gz

{futurehouse_client-0.0.3 → futurehouse_client-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: futurehouse-client
-Version: 0.0.3
+Version: 0.0.5
 Summary: A client for interacting with endpoints of the FutureHouse service.
 Author-email: FutureHouse technical staff <hello@futurehouse.org>
 Classifier: Operating System :: OS Independent
@@ -38,101 +38,76 @@ Requires-Dist: setuptools_scm; extra == "dev"
 
 # FutureHouse Platform API Documentation
 
-Documentation and tutorials for crow-client, a client for interacting with endpoints of the FutureHouse crow service.
-
-> FutureHouse's mascot is the crow. Therefore, some objects are named after the crow as a homage.
+Documentation and tutorials for futurehouse-client, a client for interacting with endpoints of the FutureHouse platform.
 
 <!--TOC-->
 
 - [Installation](#installation)
 - [Quickstart](#quickstart)
 - [Functionalities](#functionalities)
-  - [Stages](#stages)
 - [Authentication](#authentication)
-- [Job submission](#job-submission)
-- [Job Continuation](#job-continuation)
-- [Job retrieval](#job-retrieval)
+- [Task submission](#task-submission)
+- [Task Continuation](#task-continuation)
+- [Task retrieval](#task-retrieval)
 
 <!--TOC-->
 
 ## Installation
 
 ```bash
-uv pip install crow-client
+uv pip install futurehouse-client
 ```
 
 ## Quickstart
 
 ```python
-from crow_client import CrowClient, JobNames
+from futurehouse_client import FutureHouseClient, JobNames
 from pathlib import Path
 from aviary.core import DummyEnv
 import ldp
 
-client = CrowClient(
-    stage=Stage.PROD,
-    auth_type=AuthType.API_KEY,
+client = FutureHouseClient(
     api_key="your_api_key",
 )
 
-job_data = {
+task_data = {
     "name": JobNames.CROW,
-    "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
+    "query": "Which neglected diseases had a treatment developed by artificial intelligence?",
 }
 
-job_run_id = client.create_job(job_data)
+task_run_id = client.create_task(task_data)
 
-job_status = client.get_job(job_run_id)
+task_status = client.get_task(task_run_id)
 ```
 
-A quickstart example can be found in the [crow_client_notebook.ipynb](./docs/crow_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.
+A quickstart example can be found in the [client_notebook.ipynb](https://github.com/Future-House/futurehouse-client-docs/blob/main/docs/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
 
-Crow-client implements a RestClient (called `CrowClient`) with the following functionalities:
+FutureHouse client implements a RestClient (called `FutureHouseClient`) with the following functionalities:
 
-- [Authentication](#authtype): `auth_client`
-- [Job submission](#job-submission): `create_job(JobRequest)`
-- [Job status](#job-status): `get_job(job_id)`
-
-To create a `CrowClient`, you need to pass the following parameters:
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| stage | Stage | Stage.DEV | Where the job will be submitted? |
-| organization | str \| None | None | Which organization to use? |
-| auth_type | AuthType | AuthType.API_KEY | Which authentication method to use? |
-| api_key | str \| None | None | The API key to use for authentication, if using auth_type=AuthType.API_KEY. |
+- [Task submission](#task-submission): `create_task(TaskRequest)`
+- [Task status](#task-status): `get_task(task_id)`
 
-To instantiate a Client, we can use the following code:
+To create a `FutureHouseClient`, you need to pass an FutureHouse platform api key (see [Authentication](#authentication)):
 
 ```python
-from crow_client import CrowClient
-from crow_client.models import Stage, AuthType
+from futurehouse_client import FutureHouseClient
 
-client = CrowClient(
-    stage=Stage.PROD,
-    organization="your_organization",
-    auth_type=AuthType.API_KEY,
+client = FutureHouseClient(
     api_key="your_api_key",
 )
 ```
 
-### Stages
-
-The stage is where your job will be submitted. This parameter can be one of the following:
-| Name | Description |
-| --- | --- |
-| Stage.DEV | Development environment at https://dev.api.platform.futurehouse.org |
-| Stage.PROD | Production environment at https://api.platform.futurehouse.org |
-
 ## Authentication
 
-In order to use the `CrowClient`, you need to authenticate yourself. Authentication is done by providing an API key, which can be obtained directly from your [profile page in the FutureHouse platform](https://platform.futurehouse.org/profile).
+In order to use the `FutureHouseClient`, you need to authenticate yourself. Authentication is done by providing an API key, which can be obtained directly from your [profile page in the FutureHouse platform](https://platform.futurehouse.org/profile).
 
-## Job submission
+## Task submission
 
-`CrowClient` can be used to submit jobs to the FutureHouse platform. Using a `CrowClient` instance, you can submit jobs to the platform by calling the `create_job` method, which receives a `JobRequest` (or a dictionary with `kwargs`) and returns the job id.
-Aiming to make the submission of jobs as simple as possible, we have created a `JobNames` enum that contains the available job types.
+In the futurehouse 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.
+`FutureHouseClient` can be used to submit tasks/queries to available jobs in the FutureHouse platform. Using a `FutureHouseClient` 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 | Job Name | Task type | Description |
@@ -143,27 +118,24 @@ The available supported jobs are:
 | `JobNames.DUMMY` | `job-futurehouse-dummy` | Dummy Task | This is a dummy task. Mainly for testing purposes. |
 
 Using `JobNames`, the client automatically adapts the job name to the current stage.
-The job submission looks like this:
+The task submission looks like this:
 
 ```python
-from crow_client import CrowClient, JobNames
-from crow_client.models import AuthType, Stage
+from futurehouse_client import FutureHouseClient, JobNames
 
-client = CrowClient(
-    stage=Stage.PROD,
-    auth_type=AuthType.API_KEY,
+client = FutureHouseClient(
     api_key="your_api_key",
 )
 
-job_data = {
-    "name": JobNames.CROW,
+task_data = {
+    "name": JobNames.OWL,
     "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
 }
 
-job_id = client.create_job(job_data)
+task_id = client.create_task(task_data)
 ```
 
-`JobRequest` has the following fields:
+`TaskRequest` has the following fields:
 
 | Field          | Type          | Description                                                                                                         |
 | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
@@ -175,51 +147,46 @@ job_id = client.create_job(job_data)
 `runtime_config` can receive a `AgentConfig` object with the desired kwargs. Check the available `AgentConfig` fields in the [LDP documentation](https://github.com/Future-House/ldp/blob/main/src/ldp/agent/agent.py#L87). Besides the `AgentConfig` object, we can also pass `timeout` and `max_steps` to limit the execution time and the number of steps the agent can take.
 Other especialised configurations are also available but are outside the scope of this documentation.
 
-## Job Continuation
+## Task Continuation
 
-Once a job is submitted and the answer is returned, FutureHouse platform allow you to ask follow-up questions to the previous job.
+Once a task is submitted and the answer is returned, FutureHouse 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 [Job submission](#job-submission) section.
+To accomplish that, we can use the `runtime_config` we discussed in the [Task submission](#task-submission) section.
 
 ```python
-from crow_client import CrowClient, JobNames
-from crow_client.models import AuthType, Stage
+from futurehouse_client import FutureHouseClient, JobNames
 
-client = CrowClient(
-    stage=Stage.PROD,
-    auth_type=AuthType.API_KEY,
+client = FutureHouseClient(
     api_key="your_api_key",
 )
 
-job_data = {"name": JobNames.CROW, "query": "How many species of birds are there?"}
+task_data = {"name": JobNames.CROW, "query": "How many species of birds are there?"}
 
-job_id = client.create_job(job_data)
+task_id = client.create_task(task_data)
 
-continued_job_data = {
+continued_task_data = {
     "name": JobNames.CROW,
     "query": "From the previous answer, specifically,how many species of crows are there?",
-    "runtime_config": {"continued_job_id": job_id},
+    "runtime_config": {"continued_task_id": task_id},
 }
 
-continued_job_id = client.create_job(continued_job_data)
+continued_task_id = client.create_task(continued_task_data)
 ```
 
-## Job retrieval
+## Task retrieval
 
-Once a job is submitted, you can retrieve it by calling the `get_job` method, which receives a job id and returns a `JobResponse` object.
+Once a task is submitted, you can retrieve it by calling the `get_task` method, which receives a task id and returns a `TaskResponse` object.
 
 ```python
-from crow_client import CrowClient
-from crow_client.models import AuthType
+from futurehouse_client import FutureHouseClient
 
-client = CrowClient(
-    auth_type=AuthType.API_KEY,
+client = FutureHouseClient(
     api_key="your_api_key",
 )
 
-job_id = "job_id"
+task_id = "task_id"
 
-job_status = client.get_job(job_id)
+task_status = client.get_task(task_id)
 ```
 
-`job_status` contains information about the job. For instance, its `status`, `task`, `environment_name` and `agent_name`, and other fields specific to the job.
+`task_status` contains information about the task. For instance, its `status`, `task`, `environment_name` and `agent_name`, and other fields specific to the job.

futurehouse_client-0.0.5/README.md

@@ -0,0 +1,154 @@
+# FutureHouse Platform API Documentation
+
+Documentation and tutorials for futurehouse-client, a client for interacting with endpoints of the FutureHouse platform.
+
+<!--TOC-->
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Functionalities](#functionalities)
+- [Authentication](#authentication)
+- [Task submission](#task-submission)
+- [Task Continuation](#task-continuation)
+- [Task retrieval](#task-retrieval)
+
+<!--TOC-->
+
+## Installation
+
+```bash
+uv pip install futurehouse-client
+```
+
+## Quickstart
+
+```python
+from futurehouse_client import FutureHouseClient, JobNames
+from pathlib import Path
+from aviary.core import DummyEnv
+import ldp
+
+client = FutureHouseClient(
+    api_key="your_api_key",
+)
+
+task_data = {
+    "name": JobNames.CROW,
+    "query": "Which neglected diseases had a treatment developed by artificial intelligence?",
+}
+
+task_run_id = client.create_task(task_data)
+
+task_status = client.get_task(task_run_id)
+```
+
+A quickstart example can be found in the [client_notebook.ipynb](https://github.com/Future-House/futurehouse-client-docs/blob/main/docs/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
+
+FutureHouse client implements a RestClient (called `FutureHouseClient`) with the following functionalities:
+
+- [Task submission](#task-submission): `create_task(TaskRequest)`
+- [Task status](#task-status): `get_task(task_id)`
+
+To create a `FutureHouseClient`, you need to pass an FutureHouse platform api key (see [Authentication](#authentication)):
+
+```python
+from futurehouse_client import FutureHouseClient
+
+client = FutureHouseClient(
+    api_key="your_api_key",
+)
+```
+
+## Authentication
+
+In order to use the `FutureHouseClient`, you need to authenticate yourself. Authentication is done by providing an API key, which can be obtained directly from your [profile page in the FutureHouse platform](https://platform.futurehouse.org/profile).
+
+## Task submission
+
+In the futurehouse 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.
+`FutureHouseClient` can be used to submit tasks/queries to available jobs in the FutureHouse platform. Using a `FutureHouseClient` 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 | Job Name | Task type | Description |
+| --- | --- | --- | --- |
+| `JobNames.CROW` | `job-futurehouse-paperqa2` | Fast Search | Ask a question of scientific data sources, and receive a high-accuracy, cited response. Built with [PaperQA2](https://github.com/Future-House/paper-qa). |
+| `JobNames.FALCON` | `job-futurehouse-paperqa2-deep` | Deep Search | Use a plethora of sources to deeply research. Receive a detailed, structured report as a response. |
+| `JobNames.OWL` | `job-futurehouse-hasanyone` | Precedent Search | Formerly known as HasAnyone, query if anyone has ever done something in science. |
+| `JobNames.DUMMY` | `job-futurehouse-dummy` | Dummy Task | This is a dummy task. Mainly for testing purposes. |
+
+Using `JobNames`, the client automatically adapts the job name to the current stage.
+The task submission looks like this:
+
+```python
+from futurehouse_client import FutureHouseClient, JobNames
+
+client = FutureHouseClient(
+    api_key="your_api_key",
+)
+
+task_data = {
+    "name": JobNames.OWL,
+    "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
+}
+
+task_id = client.create_task(task_data)
+```
+
+`TaskRequest` 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.CROW` |
+| query          | str           | Query or task to be executed by the job                                                                             |
+| runtime_config | RuntimeConfig | Optional runtime parameters for the job                                                                             |
+
+`runtime_config` can receive a `AgentConfig` object with the desired kwargs. Check the available `AgentConfig` fields in the [LDP documentation](https://github.com/Future-House/ldp/blob/main/src/ldp/agent/agent.py#L87). Besides the `AgentConfig` object, we can also pass `timeout` and `max_steps` to limit the execution time and the number of steps the agent can take.
+Other especialised configurations are also available but are outside the scope of this documentation.
+
+## Task Continuation
+
+Once a task is submitted and the answer is returned, FutureHouse 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 [Task submission](#task-submission) section.
+
+```python
+from futurehouse_client import FutureHouseClient, JobNames
+
+client = FutureHouseClient(
+    api_key="your_api_key",
+)
+
+task_data = {"name": JobNames.CROW, "query": "How many species of birds are there?"}
+
+task_id = client.create_task(task_data)
+
+continued_task_data = {
+    "name": JobNames.CROW,
+    "query": "From the previous answer, specifically,how many species of crows are there?",
+    "runtime_config": {"continued_task_id": task_id},
+}
+
+continued_task_id = client.create_task(continued_task_data)
+```
+
+## Task retrieval
+
+Once a task is submitted, you can retrieve it by calling the `get_task` method, which receives a task id and returns a `TaskResponse` object.
+
+```python
+from futurehouse_client import FutureHouseClient
+
+client = FutureHouseClient(
+    api_key="your_api_key",
+)
+
+task_id = "task_id"
+
+task_status = client.get_task(task_id)
+```
+
+`task_status` contains information about the task. For instance, its `status`, `task`, `environment_name` and `agent_name`, and other fields specific to the job.

futurehouse_client-0.0.5/docs/client_notebook.ipynb

@@ -0,0 +1,197 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# FutureHouse platform client usage example"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "from pathlib import Path\n",
+    "\n",
+    "sys.path.insert(0, str(Path(\"..\").resolve()))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import time\n",
+    "\n",
+    "from futurehouse_client import Client, JobNames\n",
+    "from futurehouse_client.models import (\n",
+    "    AuthType,\n",
+    "    JobRequest,\n",
+    "    RuntimeConfig,\n",
+    "    Stage,\n",
+    ")\n",
+    "from ldp.agent import AgentConfig"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Client instantiation\n",
+    "\n",
+    "Here we use `auth_type=AuthType.API_KEY` to authenticate with the platform.\n",
+    "Please log in to the platform and go to your user settings to get your API key."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client = Client(\n",
+    "    stage=Stage.PROD,\n",
+    "    auth_type=AuthType.API_KEY,\n",
+    "    api_key=\"your-api-key\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Submit a job"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Submitting jobs is done by calling the `create_job` method, which receives a `JobRequest` object."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "job_data = JobRequest(\n",
+    "    name=JobNames.from_string(\"crow\"),\n",
+    "    query=\"What is the molecule known to have the greatest solubility in water?\",\n",
+    ")\n",
+    "client.create_job(job_data)\n",
+    "\n",
+    "while client.get_job().status != \"success\":\n",
+    "    time.sleep(5)\n",
+    "print(f\"Job status: {client.get_job().status}\")\n",
+    "print(f\"Job answer: \\n{client.get_job().formatted_answer}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can also pass a `runtime_config` to the job, which will be used to configure the agent on runtime.\n",
+    "Here, we will define a agent configuration and pass it to the job. This agent is used to decide the next action to take.\n",
+    "We will also use the `max_steps` parameter to limit the number of steps the agent will take."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "agent = AgentConfig(\n",
+    "    agent_type=\"SimpleAgent\",\n",
+    "    agent_kwargs={\n",
+    "        \"model\": \"gpt-4o\",\n",
+    "        \"temperature\": 0.0,\n",
+    "    },\n",
+    ")\n",
+    "job_data = JobRequest(\n",
+    "    name=JobNames.CROW,\n",
+    "    query=\"How many moons does earth have?\",\n",
+    "    runtime_config=RuntimeConfig(agent=agent, max_steps=10),\n",
+    ")\n",
+    "client.create_job(job_data)\n",
+    "\n",
+    "while client.get_job().status != \"success\":\n",
+    "    time.sleep(5)\n",
+    "print(f\"Job status: {client.get_job().status}\")\n",
+    "print(f\"Job answer: \\n{client.get_job().formatted_answer}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Continue a job\n",
+    "\n",
+    "The platform allows to keep asking follow-up questions to the previous job.\n",
+    "To accomplish that, we can use the `runtime_config` to pass the `job_id` of the previous job.\n",
+    "\n",
+    "Notice that `create_job` accepts both a `JobRequest` object and a dictionary with keywords arguments."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "job_data = JobRequest(name=JobNames.CROW, query=\"How many species of birds are there?\")\n",
+    "\n",
+    "job_id = client.create_job(job_data)\n",
+    "while client.get_job().status != \"success\":\n",
+    "    time.sleep(5)\n",
+    "print(f\"First job status: {client.get_job().status}\")\n",
+    "print(f\"First job answer: \\n{client.get_job().formatted_answer}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "continued_job_data = {\n",
+    "    \"name\": JobNames.CROW,\n",
+    "    \"query\": \"From the previous answer, specifically,how many species of crows are there?\",\n",
+    "    \"runtime_config\": {\"continued_job_id\": job_id},\n",
+    "}\n",
+    "\n",
+    "continued_job_id = client.create_job(continued_job_data)\n",
+    "while client.get_job().status != \"success\":\n",
+    "    time.sleep(5)\n",
+    "print(f\"Continued job status: {client.get_job().status}\")\n",
+    "print(f\"Continued job answer: \\n{client.get_job().formatted_answer}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

{futurehouse_client-0.0.3 → futurehouse_client-0.0.5}/futurehouse_client/clients/rest_client.py

@@ -173,7 +173,7 @@ class RestClient:
 
     def __init__(
         self,
-        stage: Stage = Stage.DEV,
+        stage: Stage = Stage.PROD,
         service_uri: str | None = None,
         organization: str | None = None,
         auth_type: AuthType = AuthType.API_KEY,