futurehouse-client 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

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/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/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"

futurehouse_client/clients/rest_client.py

@@ -29,6 +29,7 @@ from futurehouse_client.clients import JobNames
 from futurehouse_client.models.app import (
     APIKeyPayload,
     AuthType,
+    # TODO: Rename this to JobDeploymentConfig. But other parts of the code depend on this name, so I'm not changing it now
     CrowDeploymentConfig,
     JobRequest,
     Stage,
@@ -73,7 +74,7 @@ JWT_TOKEN_CACHE_EXPIRY: int = 300  # seconds
 
 
 class JobResponse(BaseModel):
-    """Base class for job responses. This holds attributes shared over all crows."""
+    """Base class for job responses. This holds attributes shared over all futurehouse jobs."""
 
     model_config = ConfigDict(extra="ignore")
 
@@ -81,7 +82,7 @@ class JobResponse(BaseModel):
     task: str
     user: str
     created_at: datetime
-    crow: str
+    job_name: str
     public: bool
     shared_with: list[str]
     build_owner: str | None = None
@@ -95,6 +96,9 @@ class JobResponse(BaseModel):
         # Extract fields from environment frame state
         if not isinstance(data, dict):
             return data
+        data["job_name"] = data.get(
+            "crow"
+        )  # TODO: remove this once we have the new job_name field.
         if not (env_frame := data.get("environment_frame", {})):
             return data
         state = env_frame.get("state", {}).get("state", {})
@@ -340,7 +344,7 @@ class RestClient:
     def get_job(
         self, job_id: str | None = None, history: bool = False, verbose: bool = False
     ) -> "JobResponse":
-        """Get details for a specific crow job."""
+        """Get details for a specific job."""
         try:
             job_id = job_id or self.trajectory_id
             response = self.client.get(
@@ -352,7 +356,7 @@ class RestClient:
             if verbose:
                 return verbose_response
             if any(
-                JobNames.from_string(job_name) in verbose_response.crow
+                JobNames.from_string(job_name) in verbose_response.job_name
                 for job_name in ["crow", "falcon", "owl", "dummy"]
             ):
                 return PQAJobResponse(**response.json())
@@ -368,7 +372,7 @@ class RestClient:
         retry=retry_if_exception_type(Timeout),
     )
     def create_job(self, job_data: JobRequest | dict[str, Any]):
-        """Create a new crow job."""
+        """Create a new futurehouse job."""
         if isinstance(job_data, dict):
             job_data = JobRequest.model_validate(job_data)
 
@@ -401,6 +405,7 @@ class RestClient:
         return response.json()
 
     # TODO: Refactor later so we don't have to ignore PLR0915
+    # TODO: Rename this to create_job. I'm not doing it now to avoid breaking the infrastructure.
     @retry(
         stop=stop_after_attempt(MAX_RETRY_ATTEMPTS),
         wait=wait_exponential(multiplier=RETRY_MULTIPLIER, max=MAX_RETRY_WAIT),

futurehouse_client-0.0.2.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+futurehouse_client/__init__.py,sha256=QhDraw1J-DNc2kEq8E3iMIMokbllTHuVEOXgUCIT8qc,338
+futurehouse_client/clients/__init__.py,sha256=JpqWhXNRo4-xe9-SA_9QI5Z5P3xlJ-b4STGaljQpj3k,314
+futurehouse_client/clients/job_client.py,sha256=RNgdSJVI1vjQSypdfswHX0Gvv_XnKG4bZjklf3WdSuk,8828
+futurehouse_client/clients/rest_client.py,sha256=Qu6Ui-ot_pAJG-55Ll_IjOWLOkFELDaTObLkay7vxEY,25101
+futurehouse_client/models/__init__.py,sha256=VBKYb_2kmxtDwp9LvTL7BEFyioekggQsrQg5I_dhZoI,342
+futurehouse_client/models/app.py,sha256=_MO31xvKJaAztWz4KrV13ty4POg-RuWrGgqmvS9w2bc,22298
+futurehouse_client/models/client.py,sha256=n4HD0KStKLm6Ek9nL9ylP-bkK10yzAaD1uIDF83Qp_A,1828
+futurehouse_client/models/rest.py,sha256=W-wNFTN7HALYFFphw-RQYRMm6_TSa1cl4T-mZ1msk90,393
+futurehouse_client/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+futurehouse_client/utils/module_utils.py,sha256=aFyd-X-pDARXz9GWpn8SSViUVYdSbuy9vSkrzcVIaGI,4955
+futurehouse_client-0.0.2.dist-info/METADATA,sha256=lOwcSqbXH6Y1MDN22bW4j7VlsLItc0aG3lHaysdA-TU,8894
+futurehouse_client-0.0.2.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+futurehouse_client-0.0.2.dist-info/top_level.txt,sha256=TRuLUCt_qBnggdFHCX4O_BoCu1j2X43lKfIZC-ElwWY,19
+futurehouse_client-0.0.2.dist-info/RECORD,,

futurehouse_client-0.0.1.dist-info/METADATA

@@ -1,151 +0,0 @@
-Metadata-Version: 2.4
-Name: futurehouse-client
-Version: 0.0.1
-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"
-
-# crow-client
-
-A client for interacting with endpoints of the FutureHouse crow service.
-
-## Installation
-
-```bash
-uv pip install crow-client
-```
-
-## Usage
-
-The CrowClient provides simple functions to deploy and monitor your crow.
-
-In the case of environments the deployment looks like this
-
-```python
-from pathlib import Path
-from crow_client import CrowClient
-from crow_client.models import CrowDeploymentConfig
-
-client = CrowClient()
-
-crow = CrowDeploymentConfig(
-    path=Path("../envs/dummy_env"),
-    environment="dummy_env.env.DummyEnv",
-    requires_aviary_internal=False,
-    environment_variables={"SAMPLE_ENV_VAR": "sample_val"},
-    agent="ldp.agent.SimpleAgent",
-)
-
-client.create_crow(crow)
-
-# checks the status
-client.get_build_status()
-```
-
-For functional environments we don't need to pass the file path and can pass the environment builder instead
-
-```python
-from aviary.core import fenv
-import numpy as np
-
-
-def function_to_use_here(inpste: str):
-    a = np.array(np.asmatrix("1 2; 3 4"))
-    return inpste
-
-
-@fenv.start()
-def my_env(topic: str):
-    """
-    Here is the doc string describing the task.
-    """
-    a = np.array(np.asmatrix("1 2; 3 4"))
-    return f"Write a sad story about {topic}", {"chosen_topic": topic}
-
-
-@my_env.tool()
-def print_story(story: str, state) -> None:
-    """Print the story and complete the task"""
-    print(story)
-    print(function_to_use_here(story))
-    state.reward = 1
-    state.done = True
-
-
-from crow_client import CrowClient
-from crow_client.models import CrowDeploymentConfig, Stage
-from crow_client.clients.rest_client import generate_requirements
-
-client = CrowClient(stage=Stage.LOCAL)
-
-crow = CrowDeploymentConfig(
-    functional_environment=my_env,
-    environment="my_env",
-    requires_aviary_internal=False,
-    environment_variables={"SAMPLE_ENV_VAR": "sample_val"},
-    agent="ldp.agent.SimpleAgent",
-    requirements=generate_requirements(my_env, globals()),
-)
-
-client.create_crow(crow)
-```
-
-This client also provides functions that let you send tasks to an existing crow:
-
-```python
-from crow_client import CrowJob
-
-client = CrowClient()
-
-job_data = {"name": "your-job-name", "query": "your task"}
-client.create_job(job_data)
-
-# checks the status
-client.get_job()
-```
-
-The CrowJobClient provides an interface for managing environment states and agent interactions in the FutureHouse crow service.
-
-```python
-from crow_client import CrowJobClient
-from crow_client.models.app import Stage
-
-client = CrowJobClient(
-    environment="your_environment_name",
-    agent="your_agent_id",
-    auth_token="your_auth_token",
-    base_uri=Stage.DEV,
-    trajectory_id=None,
-)
-```

futurehouse_client-0.0.1.dist-info/RECORD

@@ -1,14 +0,0 @@
-futurehouse_client/__init__.py,sha256=SaaBeLHh4K81dONiXxowhsgM-Zr12t1g-phDgwi5iWc,316
-futurehouse_client/clients/__init__.py,sha256=OWJtj6WNJ1GvzA5v-Z8yiKlta47k4dprih-9n7mag40,300
-futurehouse_client/clients/job_client.py,sha256=M0siUz-5Ffri4_fhXXeBb54qnELwMa1hYzosS8bx3ek,8833
-futurehouse_client/clients/rest_client.py,sha256=dEes4lP0JOsuRoFgjhU9uXSogBGFOWgSw8ZfopUJ4w8,24734
-futurehouse_client/models/__init__.py,sha256=VBKYb_2kmxtDwp9LvTL7BEFyioekggQsrQg5I_dhZoI,342
-futurehouse_client/models/app.py,sha256=_MO31xvKJaAztWz4KrV13ty4POg-RuWrGgqmvS9w2bc,22298
-futurehouse_client/models/client.py,sha256=n4HD0KStKLm6Ek9nL9ylP-bkK10yzAaD1uIDF83Qp_A,1828
-futurehouse_client/models/rest.py,sha256=W-wNFTN7HALYFFphw-RQYRMm6_TSa1cl4T-mZ1msk90,393
-futurehouse_client/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-futurehouse_client/utils/module_utils.py,sha256=aFyd-X-pDARXz9GWpn8SSViUVYdSbuy9vSkrzcVIaGI,4955
-futurehouse_client-0.0.1.dist-info/METADATA,sha256=L7c7KYAcl5HgkRBNmjHS0xnWmZb4QHwmAS3-vrLmtsw,4076
-futurehouse_client-0.0.1.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-futurehouse_client-0.0.1.dist-info/top_level.txt,sha256=TRuLUCt_qBnggdFHCX4O_BoCu1j2X43lKfIZC-ElwWY,19
-futurehouse_client-0.0.1.dist-info/RECORD,,