futurehouse-client 0.0.1__tar.gz → 0.0.2__tar.gz

futurehouse_client-0.0.2/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: futurehouse-client
+Version: 0.0.2
+Summary: A client for interacting with endpoints of the FutureHouse service.
+Author-email: FutureHouse technical staff <hello@futurehouse.org>
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cloudpickle
+Requires-Dist: dm-tree<0.1.9
+Requires-Dist: fhaviary
+Requires-Dist: httpx
+Requires-Dist: ldp>=0.22.0
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+Requires-Dist: tenacity
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: notebook; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pylint-per-file-ignores; extra == "dev"
+Requires-Dist: pylint-pydantic; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-rerunfailures; extra == "dev"
+Requires-Dist: pytest-subtests; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+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.
+
+<!--TOC-->
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Functionalities](#functionalities)
+  - [Stages](#stages)
+- [Authentication](#authentication)
+- [Job submission](#job-submission)
+- [Job Continuation](#job-continuation)
+- [Job retrieval](#job-retrieval)
+
+<!--TOC-->
+
+## Installation
+
+```bash
+uv pip install crow-client
+```
+
+## Quickstart
+
+```python
+from crow_client import CrowClient, JobNames
+from pathlib import Path
+from aviary.core import DummyEnv
+import ldp
+
+client = CrowClient(
+    stage=Stage.DEV,
+    auth_type=AuthType.API_KEY,
+    api_key="your_api_key",
+)
+
+job_data = {
+    "name": JobNames.CROW,
+    "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
+}
+
+job_run_id = client.create_job(job_data)
+
+job_status = client.get_job(job_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.
+
+## Functionalities
+
+Crow-client implements a RestClient (called `CrowClient`) 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. |
+
+To instantiate a Client, we can use the following code:
+
+```python
+from crow_client import CrowClient
+from crow_client.models import Stage, AuthType
+
+client = CrowClient(
+    stage=Stage.DEV,
+    organization="your_organization",
+    auth_type=AuthType.API_KEY,
+    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).
+
+## Job 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.
+
+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 job submission looks like this:
+
+```python
+from crow_client import CrowClient, JobNames
+from crow_client.models import AuthType, Stage
+
+client = CrowClient(
+    stage=Stage.DEV,
+    auth_type=AuthType.API_KEY,
+    api_key="your_api_key",
+)
+
+job_data = {
+    "name": JobNames.CROW,
+    "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
+}
+
+job_id = client.create_job(job_data)
+```
+
+`JobRequest` 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.
+
+## Job Continuation
+
+Once a job is submitted and the answer is returned, FutureHouse platform allow you to ask follow-up questions to the previous job.
+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.
+
+```python
+from crow_client import CrowClient, JobNames
+from crow_client.models import AuthType, Stage
+
+client = CrowClient(
+    stage=Stage.DEV,
+    auth_type=AuthType.API_KEY,
+    api_key="your_api_key",
+)
+
+job_data = {"name": JobNames.CROW, "query": "How many species of birds are there?"}
+
+job_id = client.create_job(job_data)
+
+continued_job_data = {
+    "name": JobNames.CROW,
+    "query": "From the previous answer, specifically,how many species of crows are there?",
+    "runtime_config": {"continued_job_id": job_id},
+}
+
+continued_job_id = client.create_job(continued_job_data)
+```
+
+## Job 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.
+
+```python
+from crow_client import CrowClient
+from crow_client.models import AuthType
+
+client = CrowClient(
+    auth_type=AuthType.API_KEY,
+    api_key="your_api_key",
+)
+
+job_id = "job_id"
+
+job_status = client.get_job(job_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.

futurehouse_client-0.0.2/README.md

@@ -0,0 +1,187 @@
+# 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.
+
+<!--TOC-->
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Functionalities](#functionalities)
+  - [Stages](#stages)
+- [Authentication](#authentication)
+- [Job submission](#job-submission)
+- [Job Continuation](#job-continuation)
+- [Job retrieval](#job-retrieval)
+
+<!--TOC-->
+
+## Installation
+
+```bash
+uv pip install crow-client
+```
+
+## Quickstart
+
+```python
+from crow_client import CrowClient, JobNames
+from pathlib import Path
+from aviary.core import DummyEnv
+import ldp
+
+client = CrowClient(
+    stage=Stage.DEV,
+    auth_type=AuthType.API_KEY,
+    api_key="your_api_key",
+)
+
+job_data = {
+    "name": JobNames.CROW,
+    "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
+}
+
+job_run_id = client.create_job(job_data)
+
+job_status = client.get_job(job_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.
+
+## Functionalities
+
+Crow-client implements a RestClient (called `CrowClient`) 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. |
+
+To instantiate a Client, we can use the following code:
+
+```python
+from crow_client import CrowClient
+from crow_client.models import Stage, AuthType
+
+client = CrowClient(
+    stage=Stage.DEV,
+    organization="your_organization",
+    auth_type=AuthType.API_KEY,
+    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).
+
+## Job 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.
+
+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 job submission looks like this:
+
+```python
+from crow_client import CrowClient, JobNames
+from crow_client.models import AuthType, Stage
+
+client = CrowClient(
+    stage=Stage.DEV,
+    auth_type=AuthType.API_KEY,
+    api_key="your_api_key",
+)
+
+job_data = {
+    "name": JobNames.CROW,
+    "query": "Has anyone tested therapeutic exerkines in humans or NHPs?",
+}
+
+job_id = client.create_job(job_data)
+```
+
+`JobRequest` 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.
+
+## Job Continuation
+
+Once a job is submitted and the answer is returned, FutureHouse platform allow you to ask follow-up questions to the previous job.
+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.
+
+```python
+from crow_client import CrowClient, JobNames
+from crow_client.models import AuthType, Stage
+
+client = CrowClient(
+    stage=Stage.DEV,
+    auth_type=AuthType.API_KEY,
+    api_key="your_api_key",
+)
+
+job_data = {"name": JobNames.CROW, "query": "How many species of birds are there?"}
+
+job_id = client.create_job(job_data)
+
+continued_job_data = {
+    "name": JobNames.CROW,
+    "query": "From the previous answer, specifically,how many species of crows are there?",
+    "runtime_config": {"continued_job_id": job_id},
+}
+
+continued_job_id = client.create_job(continued_job_data)
+```
+
+## Job 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.
+
+```python
+from crow_client import CrowClient
+from crow_client.models import AuthType
+
+client = CrowClient(
+    auth_type=AuthType.API_KEY,
+    api_key="your_api_key",
+)
+
+job_id = "job_id"
+
+job_status = client.get_job(job_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.

futurehouse_client-0.0.2/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.1 → futurehouse_client-0.0.2}/futurehouse_client/__init__.py

@@ -1,9 +1,9 @@
 from .clients.job_client import JobClient, JobNames
 from .clients.rest_client import JobResponse, JobResponseVerbose, PQAJobResponse
-from .clients.rest_client import RestClient as Client
+from .clients.rest_client import RestClient as FutureHouseClient
 
 __all__ = [
-    "Client",
+    "FutureHouseClient",
     "JobClient",
     "JobNames",
     "JobResponse",

{futurehouse_client-0.0.1 → futurehouse_client-0.0.2}/futurehouse_client/clients/__init__.py

@@ -1,9 +1,9 @@
 from .job_client import JobClient, JobNames
 from .rest_client import JobResponse, JobResponseVerbose, PQAJobResponse
-from .rest_client import RestClient as CrowClient
+from .rest_client import RestClient as FutureHouseClient
 
 __all__ = [
-    "CrowClient",
+    "FutureHouseClient",
     "JobClient",
     "JobNames",
     "JobResponse",

{futurehouse_client-0.0.1 → futurehouse_client-0.0.2}/futurehouse_client/clients/job_client.py

@@ -19,7 +19,7 @@ logger = logging.getLogger(__name__)
 
 
 class JobNames(StrEnum):
-    """Enum of available crow jobs."""
+    """Enum of available jobs."""
 
     CROW = "job-futurehouse-paperqa2"
     FALCON = "job-futurehouse-paperqa2-deep"