futurehouse-client 0.0.3__tar.gz → 0.0.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {futurehouse_client-0.0.3/futurehouse_client.egg-info → futurehouse_client-0.0.4}/PKG-INFO +1 -1
- futurehouse_client-0.0.4/docs/client_notebook.ipynb +197 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/clients/rest_client.py +1 -1
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4/futurehouse_client.egg-info}/PKG-INFO +1 -1
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client.egg-info/SOURCES.txt +0 -2
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/pyproject.toml +1 -1
- futurehouse_client-0.0.3/docs/client_notebook.ipynb +0 -349
- futurehouse_client-0.0.3/docs/client_notebook.md +0 -116
- futurehouse_client-0.0.3/docs/crow_client_notebook_w_deployment.ipynb +0 -226
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/LICENSE +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/README.md +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/docs/__init__.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/__init__.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/clients/__init__.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/clients/job_client.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/models/__init__.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/models/app.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/models/client.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/models/rest.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/utils/__init__.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/utils/module_utils.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client.egg-info/dependency_links.txt +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client.egg-info/requires.txt +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client.egg-info/top_level.txt +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/setup.cfg +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/tests/test_rest.py +0 -0
- {futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/uv.lock +0 -0
@@ -1,6 +1,6 @@
|
|
1
1
|
Metadata-Version: 2.4
|
2
2
|
Name: futurehouse-client
|
3
|
-
Version: 0.0.
|
3
|
+
Version: 0.0.4
|
4
4
|
Summary: A client for interacting with endpoints of the FutureHouse service.
|
5
5
|
Author-email: FutureHouse technical staff <hello@futurehouse.org>
|
6
6
|
Classifier: Operating System :: OS Independent
|
@@ -0,0 +1,197 @@
|
|
1
|
+
{
|
2
|
+
"cells": [
|
3
|
+
{
|
4
|
+
"cell_type": "markdown",
|
5
|
+
"metadata": {},
|
6
|
+
"source": [
|
7
|
+
"# FutureHouse platform client usage example"
|
8
|
+
]
|
9
|
+
},
|
10
|
+
{
|
11
|
+
"cell_type": "code",
|
12
|
+
"execution_count": null,
|
13
|
+
"metadata": {},
|
14
|
+
"outputs": [],
|
15
|
+
"source": [
|
16
|
+
"import sys\n",
|
17
|
+
"from pathlib import Path\n",
|
18
|
+
"\n",
|
19
|
+
"sys.path.insert(0, str(Path(\"..\").resolve()))"
|
20
|
+
]
|
21
|
+
},
|
22
|
+
{
|
23
|
+
"cell_type": "code",
|
24
|
+
"execution_count": null,
|
25
|
+
"metadata": {},
|
26
|
+
"outputs": [],
|
27
|
+
"source": [
|
28
|
+
"import time\n",
|
29
|
+
"\n",
|
30
|
+
"from futurehouse_client import Client, JobNames\n",
|
31
|
+
"from futurehouse_client.models import (\n",
|
32
|
+
" AuthType,\n",
|
33
|
+
" JobRequest,\n",
|
34
|
+
" RuntimeConfig,\n",
|
35
|
+
" Stage,\n",
|
36
|
+
")\n",
|
37
|
+
"from ldp.agent import AgentConfig"
|
38
|
+
]
|
39
|
+
},
|
40
|
+
{
|
41
|
+
"cell_type": "markdown",
|
42
|
+
"metadata": {},
|
43
|
+
"source": [
|
44
|
+
"## Client instantiation\n",
|
45
|
+
"\n",
|
46
|
+
"Here we use `auth_type=AuthType.API_KEY` to authenticate with the platform.\n",
|
47
|
+
"Please log in to the platform and go to your user settings to get your API key."
|
48
|
+
]
|
49
|
+
},
|
50
|
+
{
|
51
|
+
"cell_type": "code",
|
52
|
+
"execution_count": null,
|
53
|
+
"metadata": {},
|
54
|
+
"outputs": [],
|
55
|
+
"source": [
|
56
|
+
"client = Client(\n",
|
57
|
+
" stage=Stage.PROD,\n",
|
58
|
+
" auth_type=AuthType.API_KEY,\n",
|
59
|
+
" api_key=\"your-api-key\",\n",
|
60
|
+
")"
|
61
|
+
]
|
62
|
+
},
|
63
|
+
{
|
64
|
+
"cell_type": "markdown",
|
65
|
+
"metadata": {},
|
66
|
+
"source": [
|
67
|
+
"## Submit a job"
|
68
|
+
]
|
69
|
+
},
|
70
|
+
{
|
71
|
+
"cell_type": "markdown",
|
72
|
+
"metadata": {},
|
73
|
+
"source": [
|
74
|
+
"Submitting jobs is done by calling the `create_job` method, which receives a `JobRequest` object."
|
75
|
+
]
|
76
|
+
},
|
77
|
+
{
|
78
|
+
"cell_type": "code",
|
79
|
+
"execution_count": null,
|
80
|
+
"metadata": {},
|
81
|
+
"outputs": [],
|
82
|
+
"source": [
|
83
|
+
"job_data = JobRequest(\n",
|
84
|
+
" name=JobNames.from_string(\"crow\"),\n",
|
85
|
+
" query=\"What is the molecule known to have the greatest solubility in water?\",\n",
|
86
|
+
")\n",
|
87
|
+
"client.create_job(job_data)\n",
|
88
|
+
"\n",
|
89
|
+
"while client.get_job().status != \"success\":\n",
|
90
|
+
" time.sleep(5)\n",
|
91
|
+
"print(f\"Job status: {client.get_job().status}\")\n",
|
92
|
+
"print(f\"Job answer: \\n{client.get_job().formatted_answer}\")"
|
93
|
+
]
|
94
|
+
},
|
95
|
+
{
|
96
|
+
"cell_type": "markdown",
|
97
|
+
"metadata": {},
|
98
|
+
"source": [
|
99
|
+
"You can also pass a `runtime_config` to the job, which will be used to configure the agent on runtime.\n",
|
100
|
+
"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",
|
101
|
+
"We will also use the `max_steps` parameter to limit the number of steps the agent will take."
|
102
|
+
]
|
103
|
+
},
|
104
|
+
{
|
105
|
+
"cell_type": "code",
|
106
|
+
"execution_count": null,
|
107
|
+
"metadata": {},
|
108
|
+
"outputs": [],
|
109
|
+
"source": [
|
110
|
+
"agent = AgentConfig(\n",
|
111
|
+
" agent_type=\"SimpleAgent\",\n",
|
112
|
+
" agent_kwargs={\n",
|
113
|
+
" \"model\": \"gpt-4o\",\n",
|
114
|
+
" \"temperature\": 0.0,\n",
|
115
|
+
" },\n",
|
116
|
+
")\n",
|
117
|
+
"job_data = JobRequest(\n",
|
118
|
+
" name=JobNames.CROW,\n",
|
119
|
+
" query=\"How many moons does earth have?\",\n",
|
120
|
+
" runtime_config=RuntimeConfig(agent=agent, max_steps=10),\n",
|
121
|
+
")\n",
|
122
|
+
"client.create_job(job_data)\n",
|
123
|
+
"\n",
|
124
|
+
"while client.get_job().status != \"success\":\n",
|
125
|
+
" time.sleep(5)\n",
|
126
|
+
"print(f\"Job status: {client.get_job().status}\")\n",
|
127
|
+
"print(f\"Job answer: \\n{client.get_job().formatted_answer}\")"
|
128
|
+
]
|
129
|
+
},
|
130
|
+
{
|
131
|
+
"cell_type": "markdown",
|
132
|
+
"metadata": {},
|
133
|
+
"source": [
|
134
|
+
"# Continue a job\n",
|
135
|
+
"\n",
|
136
|
+
"The platform allows to keep asking follow-up questions to the previous job.\n",
|
137
|
+
"To accomplish that, we can use the `runtime_config` to pass the `job_id` of the previous job.\n",
|
138
|
+
"\n",
|
139
|
+
"Notice that `create_job` accepts both a `JobRequest` object and a dictionary with keywords arguments."
|
140
|
+
]
|
141
|
+
},
|
142
|
+
{
|
143
|
+
"cell_type": "code",
|
144
|
+
"execution_count": null,
|
145
|
+
"metadata": {},
|
146
|
+
"outputs": [],
|
147
|
+
"source": [
|
148
|
+
"job_data = JobRequest(name=JobNames.CROW, query=\"How many species of birds are there?\")\n",
|
149
|
+
"\n",
|
150
|
+
"job_id = client.create_job(job_data)\n",
|
151
|
+
"while client.get_job().status != \"success\":\n",
|
152
|
+
" time.sleep(5)\n",
|
153
|
+
"print(f\"First job status: {client.get_job().status}\")\n",
|
154
|
+
"print(f\"First job answer: \\n{client.get_job().formatted_answer}\")"
|
155
|
+
]
|
156
|
+
},
|
157
|
+
{
|
158
|
+
"cell_type": "code",
|
159
|
+
"execution_count": null,
|
160
|
+
"metadata": {},
|
161
|
+
"outputs": [],
|
162
|
+
"source": [
|
163
|
+
"continued_job_data = {\n",
|
164
|
+
" \"name\": JobNames.CROW,\n",
|
165
|
+
" \"query\": \"From the previous answer, specifically,how many species of crows are there?\",\n",
|
166
|
+
" \"runtime_config\": {\"continued_job_id\": job_id},\n",
|
167
|
+
"}\n",
|
168
|
+
"\n",
|
169
|
+
"continued_job_id = client.create_job(continued_job_data)\n",
|
170
|
+
"while client.get_job().status != \"success\":\n",
|
171
|
+
" time.sleep(5)\n",
|
172
|
+
"print(f\"Continued job status: {client.get_job().status}\")\n",
|
173
|
+
"print(f\"Continued job answer: \\n{client.get_job().formatted_answer}\")"
|
174
|
+
]
|
175
|
+
}
|
176
|
+
],
|
177
|
+
"metadata": {
|
178
|
+
"kernelspec": {
|
179
|
+
"display_name": ".venv",
|
180
|
+
"language": "python",
|
181
|
+
"name": "python3"
|
182
|
+
},
|
183
|
+
"language_info": {
|
184
|
+
"codemirror_mode": {
|
185
|
+
"name": "ipython",
|
186
|
+
"version": 3
|
187
|
+
},
|
188
|
+
"file_extension": ".py",
|
189
|
+
"mimetype": "text/x-python",
|
190
|
+
"name": "python",
|
191
|
+
"nbconvert_exporter": "python",
|
192
|
+
"pygments_lexer": "ipython3"
|
193
|
+
}
|
194
|
+
},
|
195
|
+
"nbformat": 4,
|
196
|
+
"nbformat_minor": 4
|
197
|
+
}
|
@@ -1,6 +1,6 @@
|
|
1
1
|
Metadata-Version: 2.4
|
2
2
|
Name: futurehouse-client
|
3
|
-
Version: 0.0.
|
3
|
+
Version: 0.0.4
|
4
4
|
Summary: A client for interacting with endpoints of the FutureHouse service.
|
5
5
|
Author-email: FutureHouse technical staff <hello@futurehouse.org>
|
6
6
|
Classifier: Operating System :: OS Independent
|
@@ -24,7 +24,7 @@ dependencies = [
|
|
24
24
|
"tenacity",
|
25
25
|
]
|
26
26
|
description = "A client for interacting with endpoints of the FutureHouse service."
|
27
|
-
version = "0.0.
|
27
|
+
version = "0.0.4"
|
28
28
|
name = "futurehouse-client"
|
29
29
|
readme = "README.md"
|
30
30
|
requires-python = ">=3.11,<3.13" # Pin to have dm-tree macOS wheels and avoid requiring cmake
|
@@ -1,349 +0,0 @@
|
|
1
|
-
{
|
2
|
-
"cells": [
|
3
|
-
{
|
4
|
-
"cell_type": "markdown",
|
5
|
-
"metadata": {},
|
6
|
-
"source": [
|
7
|
-
"# FutureHouse platform client usage example"
|
8
|
-
]
|
9
|
-
},
|
10
|
-
{
|
11
|
-
"cell_type": "code",
|
12
|
-
"execution_count": null,
|
13
|
-
"metadata": {},
|
14
|
-
"outputs": [],
|
15
|
-
"source": [
|
16
|
-
"import sys\n",
|
17
|
-
"from pathlib import Path\n",
|
18
|
-
"\n",
|
19
|
-
"sys.path.insert(0, str(Path(\"..\").resolve()))"
|
20
|
-
]
|
21
|
-
},
|
22
|
-
{
|
23
|
-
"cell_type": "code",
|
24
|
-
"execution_count": null,
|
25
|
-
"metadata": {},
|
26
|
-
"outputs": [],
|
27
|
-
"source": [
|
28
|
-
"import time\n",
|
29
|
-
"\n",
|
30
|
-
"from futurehouse_client import Client, JobNames\n",
|
31
|
-
"from futurehouse_client.models import (\n",
|
32
|
-
" AuthType,\n",
|
33
|
-
" JobRequest,\n",
|
34
|
-
" RuntimeConfig,\n",
|
35
|
-
" Stage,\n",
|
36
|
-
")\n",
|
37
|
-
"from ldp.agent import AgentConfig"
|
38
|
-
]
|
39
|
-
},
|
40
|
-
{
|
41
|
-
"cell_type": "markdown",
|
42
|
-
"metadata": {},
|
43
|
-
"source": [
|
44
|
-
"## Client instantiation\n",
|
45
|
-
"\n",
|
46
|
-
"Here we use `auth_type=AuthType.API_KEY` to authenticate with the platform.\n",
|
47
|
-
"Please log in to the platform and go to your user settings to get your API key."
|
48
|
-
]
|
49
|
-
},
|
50
|
-
{
|
51
|
-
"cell_type": "code",
|
52
|
-
"execution_count": null,
|
53
|
-
"metadata": {},
|
54
|
-
"outputs": [],
|
55
|
-
"source": [
|
56
|
-
"client = Client(\n",
|
57
|
-
" stage=Stage.PROD,\n",
|
58
|
-
" auth_type=AuthType.API_KEY,\n",
|
59
|
-
" api_key=\"your-api-key\",\n",
|
60
|
-
")"
|
61
|
-
]
|
62
|
-
},
|
63
|
-
{
|
64
|
-
"cell_type": "markdown",
|
65
|
-
"metadata": {},
|
66
|
-
"source": [
|
67
|
-
"## Submit a job"
|
68
|
-
]
|
69
|
-
},
|
70
|
-
{
|
71
|
-
"cell_type": "markdown",
|
72
|
-
"metadata": {},
|
73
|
-
"source": [
|
74
|
-
"Submitting jobs is done by calling the `create_job` method, which receives a `JobRequest` object."
|
75
|
-
]
|
76
|
-
},
|
77
|
-
{
|
78
|
-
"cell_type": "code",
|
79
|
-
"execution_count": null,
|
80
|
-
"metadata": {},
|
81
|
-
"outputs": [
|
82
|
-
{
|
83
|
-
"name": "stdout",
|
84
|
-
"output_type": "stream",
|
85
|
-
"text": [
|
86
|
-
"Job status: success\n",
|
87
|
-
"Job answer: \n",
|
88
|
-
"Question: What is the molecule known to have the greatest solubility in water?\n",
|
89
|
-
"\n",
|
90
|
-
"The phosphate prodrug of MSX‑2 is identified as having the greatest water solubility among the molecules with explicit solubility values; it reached 9.0 mg/mL in water—exceeding the 7.3 mg/mL value reported for its L‑valine prodrug counterpart and the lower solubility values for other compounds discussed (jornada2015theprodrugapproach pages 3–5). None of the other sources in the provided context specify an absolute water solubility that surpasses this value.\n",
|
91
|
-
"\n"
|
92
|
-
]
|
93
|
-
}
|
94
|
-
],
|
95
|
-
"source": [
|
96
|
-
"job_data = JobRequest(\n",
|
97
|
-
" name=JobNames.from_string(\"crow\"),\n",
|
98
|
-
" query=\"What is the molecule known to have the greatest solubility in water?\",\n",
|
99
|
-
")\n",
|
100
|
-
"client.create_job(job_data)\n",
|
101
|
-
"\n",
|
102
|
-
"while client.get_job().status != \"success\":\n",
|
103
|
-
" time.sleep(5)\n",
|
104
|
-
"print(f\"Job status: {client.get_job().status}\")\n",
|
105
|
-
"print(f\"Job answer: \\n{client.get_job().formatted_answer}\")"
|
106
|
-
]
|
107
|
-
},
|
108
|
-
{
|
109
|
-
"cell_type": "markdown",
|
110
|
-
"metadata": {},
|
111
|
-
"source": [
|
112
|
-
"You can also pass a `runtime_config` to the job, which will be used to configure the agent on runtime.\n",
|
113
|
-
"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",
|
114
|
-
"We will also use the `max_steps` parameter to limit the number of steps the agent will take."
|
115
|
-
]
|
116
|
-
},
|
117
|
-
{
|
118
|
-
"cell_type": "code",
|
119
|
-
"execution_count": null,
|
120
|
-
"metadata": {},
|
121
|
-
"outputs": [
|
122
|
-
{
|
123
|
-
"name": "stdout",
|
124
|
-
"output_type": "stream",
|
125
|
-
"text": [
|
126
|
-
"Job status: success\n",
|
127
|
-
"Job answer: \n",
|
128
|
-
"Question: How many moons does earth have?\n",
|
129
|
-
"\n",
|
130
|
-
"Earth has one permanent natural moon—the Moon. All of the cited sources consistently support that the only stable, long‐term satellite of Earth is the Moon, which formed via a giant impact and has been the sole permanent companion since ancient times (jedicke2018earthsminimoonsopportunities pages 1-4; belbruno2005wheredidthe pages 1-4; canup2012formingamoon pages 8-8).\n",
|
131
|
-
"\n",
|
132
|
-
"In addition to this permanent satellite, studies have identified that Earth’s gravity sometimes captures small near‐Earth objects on a temporary basis. These temporary satellites, called “minimoons,” can be either temporarily captured orbiters (TCOs) or temporarily captured flybys (TCFs). One notable example is 2006 RH120, which was captured for almost a year before escaping back to a heliocentric orbit (jedicke2018earthsminimoonsopportunities pages 4-6; jedicke2018earthsminimoonsopportunities pages 21-23). Although minimoons represent additional objects that can enter Earth’s gravitational influence, their capture is fleeting by nature, and they do not alter the fact that Earth maintains only one permanent natural satellite.\n",
|
133
|
-
"\n",
|
134
|
-
"The permanent Moon dominates the Earth-Moon system, and its stability as a satellite has been well established through both dynamical studies and historical observations. For instance, when considering the broader planetary context, the text in moonsUnknownyearallmoonsgreat pages 1-2 emphasizes that since the earliest times, human observers have only seen one moon orbiting Earth, in contrast to the multitude of satellites around other planets. Likewise, gallant2009currentbombardmentof pages 7-11 and pages 21-25 focus exclusively on Earth’s single moon while modeling the impact dynamics on its surface, with no suggestion of any additional permanent natural satellites.\n",
|
135
|
-
"\n",
|
136
|
-
"The concept of temporary satellite capture is particularly addressed in studies such as those by Jedicke et al. These works elaborate on the subtle dynamics around Earth’s Hill sphere and the Lagrange points where minimoons enter or exit Earth's gravitational influence. They note that the capture of these objects results from the interplay of kinetic and potential energies, which briefly renders their total energy negative when within approximately three Hill radii of Earth (jedicke2018earthsminimoonsopportunities pages 1-4; jedicke2018earthsminimoonsopportunities pages 6-9). Thus, while the Earth occasionally hosts these minimoons, their transient nature means they are not considered a second class of moons in the traditional, permanent sense.\n",
|
137
|
-
"\n",
|
138
|
-
"Historical and cultural perspectives as discussed by Peters in his articles (petersUnknownyearmanybluemoonsa pages 8-9; petersUnknownyearmanybluemoons pages 8-9) and by Murray (murray2021moontraditionsan pages 39-42) also implicitly confirm that Earth has always been recognized as having one moon. The cultural narratives, astronomical observations, and scientific models collectively presuppose the existence of a single, enduring natural satellite, with the Moon’s orbit and phenomena (such as Blue Moons and Super Moons) being analyzed in that context.\n",
|
139
|
-
"\n",
|
140
|
-
"This distinction between the permanent satellite and the transient captured objects is a critical element in the field of near-Earth object (NEO) research. Although various survey systems and dynamical simulations (jedicke2018earthsminimoonsopportunities pages 13-16; jedicke2018earthsminimoonsopportunities pages 16-18) are aimed at detecting these minimoon events, the consensus remains that they are ephemeral – lasting on the order of months to a year or so – and their transient nature prevents them from being classified as true moons alongside the Moon that has been gravitationally bound to Earth for billions of years.\n",
|
141
|
-
"\n",
|
142
|
-
"Furthermore, the giant impact hypothesis, as discussed by Belbruno and Gott III (belbruno2005wheredidthe pages 1-4) and Canup (canup2012formingamoon pages 8-8), provides a comprehensive explanation for the current Earth-Moon system, wherein the Moon’s formation is attributed to a Mars-sized body's collision with the proto-Earth. This theory not only addresses the unique mass ratio and properties of the Moon compared to Earth but also underscores the singular nature of Earth’s moon. There is no theoretical backing or observed evidence for any second permanent satellite emerging from such processes.\n",
|
143
|
-
"\n",
|
144
|
-
"To summarize, Earth’s satellite environment consists of:\n",
|
145
|
-
"\n",
|
146
|
-
"1. A single, permanent natural satellite—the Moon—which is a significant and gravitationally well-bound structure formed over 4.5 billion years ago (jedicke2018earthsminimoonsopportunities pages 1-4; canup2012formingamoon pages 8-8).\n",
|
147
|
-
"\n",
|
148
|
-
"2. A contingent population of temporary natural satellites or “minimoons” that are captured from the near-Earth population of small asteroids. These objects are only gravitationally bound to Earth for short periods (typically months), are often only a few meters (or smaller) in size, and eventually escape back to heliocentric orbits (jedicke2018earthsminimoonsopportunities pages 4-6; jedicke2018earthsminimoonsopportunities pages 21-23).\n",
|
149
|
-
"\n",
|
150
|
-
"The fundamental difference between these two forms of satellites lies in their dynamical lifetimes and stability. The permanent Moon has a stable orbit that has persisted since its formation, whereas minimoons are subject to complex dynamical interactions that inevitably lead to their departure from Earth’s gravitational hold.\n",
|
151
|
-
"\n",
|
152
|
-
"In conclusion, despite the occasional presence of temporarily captured asteroids (minimoons) that briefly become natural satellites of Earth, the unambiguous, supported answer is that Earth has one permanent moon—the Moon (jedicke2018earthsminimoonsopportunities pages 1-4; gallant2009currentbombardmentof pages 7-11; petersUnknownyearmanybluemoonsa pages 8-9).\n",
|
153
|
-
"\n",
|
154
|
-
"References\n",
|
155
|
-
"\n",
|
156
|
-
"1. (jedicke2018earthsminimoonsopportunities pages 1-4): Robert Jedicke, Bryce T. Bolin, William F. Bottke, Monique Chyba, Grigori Fedorets, Mikael Granvik, Lynne Jones, and Hodei Urrutxua. Earth's minimoons: opportunities for science and technology. Frontiers in Astronomy and Space Sciences, 5:13, May 2018. URL: https://doi.org/10.3389/fspas.2018.00013, doi:10.3389/fspas.2018.00013. This article has 35 citations and is from a peer-reviewed journal.\n",
|
157
|
-
"\n",
|
158
|
-
"2. (jedicke2018earthsminimoonsopportunities pages 6-9): Robert Jedicke, Bryce T. Bolin, William F. Bottke, Monique Chyba, Grigori Fedorets, Mikael Granvik, Lynne Jones, and Hodei Urrutxua. Earth's minimoons: opportunities for science and technology. Frontiers in Astronomy and Space Sciences, 5:13, May 2018. URL: https://doi.org/10.3389/fspas.2018.00013, doi:10.3389/fspas.2018.00013. This article has 35 citations and is from a peer-reviewed journal.\n",
|
159
|
-
"\n",
|
160
|
-
"3. (moonsUnknownyearallmoonsgreat pages 1-2): J Moons. All moons great and small... Unknown journal, Unknown year.\n",
|
161
|
-
"\n",
|
162
|
-
"4. (belbruno2005wheredidthe pages 1-4): Edward Belbruno and J. Richard Gott III. Where did the moon come from? The Astronomical Journal, 129:1724-1745, Mar 2005. URL: https://doi.org/10.1086/427539, doi:10.1086/427539. This article has 111 citations.\n",
|
163
|
-
"\n",
|
164
|
-
"5. (gallant2009currentbombardmentof pages 7-11): J. Gallant, B. Gladman, and M. Ćuk. Current bombardment of the earth–moon system: emphasis on cratering asymmetries. Icarus, 202:371-382, Aug 2009. URL: https://doi.org/10.1016/j.icarus.2009.03.025, doi:10.1016/j.icarus.2009.03.025. This article has 89 citations and is from a peer-reviewed journal.\n",
|
165
|
-
"\n",
|
166
|
-
"6. (jedicke2018earthsminimoonsopportunities pages 13-16): Robert Jedicke, Bryce T. Bolin, William F. Bottke, Monique Chyba, Grigori Fedorets, Mikael Granvik, Lynne Jones, and Hodei Urrutxua. Earth's minimoons: opportunities for science and technology. Frontiers in Astronomy and Space Sciences, 5:13, May 2018. URL: https://doi.org/10.3389/fspas.2018.00013, doi:10.3389/fspas.2018.00013. This article has 35 citations and is from a peer-reviewed journal.\n",
|
167
|
-
"\n",
|
168
|
-
"7. (jedicke2018earthsminimoonsopportunities pages 16-18): Robert Jedicke, Bryce T. Bolin, William F. Bottke, Monique Chyba, Grigori Fedorets, Mikael Granvik, Lynne Jones, and Hodei Urrutxua. Earth's minimoons: opportunities for science and technology. Frontiers in Astronomy and Space Sciences, 5:13, May 2018. URL: https://doi.org/10.3389/fspas.2018.00013, doi:10.3389/fspas.2018.00013. This article has 35 citations and is from a peer-reviewed journal.\n",
|
169
|
-
"\n",
|
170
|
-
"8. (jedicke2018earthsminimoonsopportunities pages 4-6): Robert Jedicke, Bryce T. Bolin, William F. Bottke, Monique Chyba, Grigori Fedorets, Mikael Granvik, Lynne Jones, and Hodei Urrutxua. Earth's minimoons: opportunities for science and technology. Frontiers in Astronomy and Space Sciences, 5:13, May 2018. URL: https://doi.org/10.3389/fspas.2018.00013, doi:10.3389/fspas.2018.00013. This article has 35 citations and is from a peer-reviewed journal.\n",
|
171
|
-
"\n",
|
172
|
-
"9. (canup2012formingamoon pages 8-8): Robin M. Canup. Forming a moon with an earth-like composition via a giant impact. Science, 338:1052-1055, Nov 2012. URL: https://doi.org/10.1126/science.1226073, doi:10.1126/science.1226073. This article has 639 citations and is from a highest quality peer-reviewed journal.\n",
|
173
|
-
"\n",
|
174
|
-
"10. (jedicke2018earthsminimoonsopportunities pages 21-23): Robert Jedicke, Bryce T. Bolin, William F. Bottke, Monique Chyba, Grigori Fedorets, Mikael Granvik, Lynne Jones, and Hodei Urrutxua. Earth's minimoons: opportunities for science and technology. Frontiers in Astronomy and Space Sciences, 5:13, May 2018. URL: https://doi.org/10.3389/fspas.2018.00013, doi:10.3389/fspas.2018.00013. This article has 35 citations and is from a peer-reviewed journal.\n",
|
175
|
-
"\n",
|
176
|
-
"11. (petersUnknownyearmanybluemoonsa pages 8-9): ART Peters. Many blue moons. Unknown journal, Unknown year.\n",
|
177
|
-
"\n",
|
178
|
-
"12. (petersUnknownyearmanybluemoons pages 8-9): ART Peters. Many blue moons. Unknown journal, Unknown year.\n",
|
179
|
-
"\n",
|
180
|
-
"13. (murray2021moontraditionsan pages 39-42): Gerald F. Murray. Moon traditions: an overview of changing beliefs about earth’s moon. Space and Society, pages 19-40, Jan 2021. URL: https://doi.org/10.1007/978-3-030-81388-8\\_2, doi:10.1007/978-3-030-81388-8\\_2. This article has 4 citations.\n",
|
181
|
-
"\n"
|
182
|
-
]
|
183
|
-
}
|
184
|
-
],
|
185
|
-
"source": [
|
186
|
-
"agent = AgentConfig(\n",
|
187
|
-
" agent_type=\"SimpleAgent\",\n",
|
188
|
-
" agent_kwargs={\n",
|
189
|
-
" \"model\": \"gpt-4o\",\n",
|
190
|
-
" \"temperature\": 0.0,\n",
|
191
|
-
" },\n",
|
192
|
-
")\n",
|
193
|
-
"job_data = JobRequest(\n",
|
194
|
-
" name=JobNames.CROW,\n",
|
195
|
-
" query=\"How many moons does earth have?\",\n",
|
196
|
-
" runtime_config=RuntimeConfig(agent=agent, max_steps=10),\n",
|
197
|
-
")\n",
|
198
|
-
"client.create_job(job_data)\n",
|
199
|
-
"\n",
|
200
|
-
"while client.get_job().status != \"success\":\n",
|
201
|
-
" time.sleep(5)\n",
|
202
|
-
"print(f\"Job status: {client.get_job().status}\")\n",
|
203
|
-
"print(f\"Job answer: \\n{client.get_job().formatted_answer}\")"
|
204
|
-
]
|
205
|
-
},
|
206
|
-
{
|
207
|
-
"cell_type": "markdown",
|
208
|
-
"metadata": {},
|
209
|
-
"source": [
|
210
|
-
"# Continue a job\n",
|
211
|
-
"\n",
|
212
|
-
"The platform allows to keep asking follow-up questions to the previous job.\n",
|
213
|
-
"To accomplish that, we can use the `runtime_config` to pass the `job_id` of the previous job.\n",
|
214
|
-
"\n",
|
215
|
-
"Notice that `create_job` accepts both a `JobRequest` object and a dictionary with keywords arguments."
|
216
|
-
]
|
217
|
-
},
|
218
|
-
{
|
219
|
-
"cell_type": "code",
|
220
|
-
"execution_count": null,
|
221
|
-
"metadata": {},
|
222
|
-
"outputs": [
|
223
|
-
{
|
224
|
-
"name": "stdout",
|
225
|
-
"output_type": "stream",
|
226
|
-
"text": [
|
227
|
-
"First job status: success\n",
|
228
|
-
"First job answer: \n",
|
229
|
-
"Question: How many species of birds are there?\n",
|
230
|
-
"\n",
|
231
|
-
"The answer depends on which species concept is used. Under the traditional biological species concept (BSC)—which defines species based on reproductive isolation—lists such as the American Ornithologists' Union (AOU) checklist recognize roughly 9,000 to 10,000 species (e.g., 9,159 species in earlier checklists and 10,021 in updated lists) (barrowclough2016howmanykinds pages 2-4, 8-11). In contrast, when using the phylogenetic species concept (PSC)—which defines species as diagnosably distinct evolutionary lineages based on morphological or genetic differences—the same analyses suggest that many currently recognized “species” harbor multiple distinct lineages. Barrowclough et al. (2016) demonstrated that a morphological analysis of an exemplar sample produced an average ratio close to 2:1, yielding an estimated total of roughly 18,000 phylogenetic species worldwide (barrowclough2016howmanykinds pages 1-2, 4-5). A complementary genetic analysis, based on mitochondrial DNA that yielded an average of about 2.4 evolutionary units per traditional species, would push that number even further, with one analysis suggesting closer to 22,000 phylogenetic species (barrowclough2016howmanykinds pages 5-8). \n",
|
232
|
-
"\n",
|
233
|
-
"To clarify, the BSC emphasizes mate choice and reproductive isolation; it has historically been the standard resulting in venerable checklists that list approximately 9,000–10,000 species (barrowclough2016howmanykinds pages 2-4, 8-11). However, the PSC emphasizes diagnosable differences in morphology and genetic markers that reveal distinct evolutionary histories. Under this approach, many “species” recognized under the BSC actually contain multiple phylogenetic species. For example, about 41% of examined biological species consist of two or more phylogenetic units, with individual assessments ranging from about 1.66 to 2.48 units per biological species (barrowclough2016howmanykinds pages 4-5, 8-11). Consequently, several independent analyses suggest that the true evolutionary diversity of birds is nearly double that indicated by traditional lists. \n",
|
234
|
-
"\n",
|
235
|
-
"Moreover, even in studies that focus on specific subsets of birds, such as landbirds, the recognized numbers are consistent with traditional counts. Jetz et al. (2007) note there are approximately 8,750 species of land birds—a figure that aligns with the traditional BSC-based counts—but these represent only terrestrial species, not the complete avifauna (jetz2007projectedimpactsof pages 1-2, 8-8). Similarly, large-scale analyses using community science data tend to work with nearly 9,000 species, which again reflects the traditional taxonomy (neateclegg2020monitoringtheworlds pages 1-2).\n",
|
236
|
-
"\n",
|
237
|
-
"In summary, if one asks “How many species of birds are there?” there are two relevant answers depending on the species concept:\n",
|
238
|
-
"\n",
|
239
|
-
"1. Using traditional taxonomy under the biological species concept, there are approximately 9,000 to 10,000 recognized species. This count is derived from extensive checklists (e.g., the AOU and Howard and Moore checklists) that rely predominantly on morphological criteria and reproductive isolation patterns (barrowclough2016howmanykinds pages 2-4, 8-11; jetz2007projectedimpactsof pages 1-2).\n",
|
240
|
-
"\n",
|
241
|
-
"2. Applying a phylogenetic species concept—that is, by recognizing diagnosable evolutionary lineages based on both morphology and genetic data—the estimated number of species nearly doubles, landing in the range of about 18,000 to possibly 22,000 species. This estimate comes from detailed morphological analyses (using an average ratio of approximately 1.97 phylogenetic species per biological species) and complementary molecular studies that unveil further subdivisions not captured in traditional counts (barrowclough2016howmanykinds pages 1-2, 4-5, 5-8).\n",
|
242
|
-
"\n",
|
243
|
-
"Thus, the true answer is nuanced: the widely recognized “species” count is around 9,000 to 10,000 when using conventional taxonomic criteria, yet evolutionary studies using a phylogenetic framework indicate that avian diversity may be undercounted by at least a factor of two. This discrepancy has significant implications for conservation biology, biogeographical studies, and comparative evolutionary research because halving or doubling the number of recognized species alters our understanding of lineage diversity and endemism (barrowclough2016howmanykinds pages 11-13, 14-15).\n",
|
244
|
-
"\n",
|
245
|
-
"Because these two approaches answer different questions—one based on traditional reproductive isolation and the other on evolutionary distinctiveness—the answer depends on the context and purpose of the inquiry. For conservation prioritization and understanding biodiversity patterns at an evolutionary scale, acknowledging the higher number of phylogenetic species is critical (barrowclough2016howmanykinds pages 8-11). On the other hand, for studies focused on reproductive biology and established taxonomic protocols, the traditional count serves as the standard (jetz2007projectedimpactsof pages 1-2).\n",
|
246
|
-
"\n",
|
247
|
-
"In conclusion, while standard taxonomies list roughly 9,000–10,000 bird species, research employing phylogenetic methods supports a much higher number—approximately 18,000 to 22,000 species—reflecting a significant underestimation of true avian diversity under traditional approaches (barrowclough2016howmanykinds pages 1-2; 4-5; 5-8; jetz2007projectedimpactsof pages 1-2, 8-8; neateclegg2020monitoringtheworlds pages 1-2).\n",
|
248
|
-
"\n",
|
249
|
-
"References\n",
|
250
|
-
"\n",
|
251
|
-
"1. (barrowclough2016howmanykinds pages 1-2): George F. Barrowclough, Joel Cracraft, John Klicka, and Robert M. Zink. How many kinds of birds are there and why does it matter? PLOS ONE, 11:e0166307, Nov 2016. URL: https://doi.org/10.1371/journal.pone.0166307, doi:10.1371/journal.pone.0166307. This article has 295 citations and is from a peer-reviewed journal.\n",
|
252
|
-
"\n",
|
253
|
-
"2. (barrowclough2016howmanykinds pages 5-8): George F. Barrowclough, Joel Cracraft, John Klicka, and Robert M. Zink. How many kinds of birds are there and why does it matter? PLOS ONE, 11:e0166307, Nov 2016. URL: https://doi.org/10.1371/journal.pone.0166307, doi:10.1371/journal.pone.0166307. This article has 295 citations and is from a peer-reviewed journal.\n",
|
254
|
-
"\n",
|
255
|
-
"3. (jetz2007projectedimpactsof pages 1-2): Walter Jetz, David S Wilcove, and Andrew P Dobson. Projected impacts of climate and land-use change on the global diversity of birds. PLoS Biology, 5:e157, Jun 2007. URL: https://doi.org/10.1371/journal.pbio.0050157, doi:10.1371/journal.pbio.0050157. This article has 1369 citations and is from a highest quality peer-reviewed journal.\n",
|
256
|
-
"\n",
|
257
|
-
"4. (barrowclough2016howmanykinds pages 2-4): George F. Barrowclough, Joel Cracraft, John Klicka, and Robert M. Zink. How many kinds of birds are there and why does it matter? PLOS ONE, 11:e0166307, Nov 2016. URL: https://doi.org/10.1371/journal.pone.0166307, doi:10.1371/journal.pone.0166307. This article has 295 citations and is from a peer-reviewed journal.\n",
|
258
|
-
"\n",
|
259
|
-
"5. (barrowclough2016howmanykinds pages 4-5): George F. Barrowclough, Joel Cracraft, John Klicka, and Robert M. Zink. How many kinds of birds are there and why does it matter? PLOS ONE, 11:e0166307, Nov 2016. URL: https://doi.org/10.1371/journal.pone.0166307, doi:10.1371/journal.pone.0166307. This article has 295 citations and is from a peer-reviewed journal.\n",
|
260
|
-
"\n",
|
261
|
-
"6. (barrowclough2016howmanykinds pages 8-11): George F. Barrowclough, Joel Cracraft, John Klicka, and Robert M. Zink. How many kinds of birds are there and why does it matter? PLOS ONE, 11:e0166307, Nov 2016. URL: https://doi.org/10.1371/journal.pone.0166307, doi:10.1371/journal.pone.0166307. This article has 295 citations and is from a peer-reviewed journal.\n",
|
262
|
-
"\n",
|
263
|
-
"7. (barrowclough2016howmanykinds pages 11-13): George F. Barrowclough, Joel Cracraft, John Klicka, and Robert M. Zink. How many kinds of birds are there and why does it matter? PLOS ONE, 11:e0166307, Nov 2016. URL: https://doi.org/10.1371/journal.pone.0166307, doi:10.1371/journal.pone.0166307. This article has 295 citations and is from a peer-reviewed journal.\n",
|
264
|
-
"\n",
|
265
|
-
"8. (neateclegg2020monitoringtheworlds pages 1-2): Montague H.C. Neate-Clegg, Joshua J. Horns, Frederick R. Adler, M. Çisel Kemahlı Aytekin, and Çağan H. Şekercioğlu. Monitoring the world's bird populations with community science data. Biological Conservation, 248:108653, Aug 2020. URL: https://doi.org/10.1016/j.biocon.2020.108653, doi:10.1016/j.biocon.2020.108653. This article has 92 citations and is from a domain leading peer-reviewed journal.\n",
|
266
|
-
"\n"
|
267
|
-
]
|
268
|
-
}
|
269
|
-
],
|
270
|
-
"source": [
|
271
|
-
"job_data = JobRequest(name=JobNames.CROW, query=\"How many species of birds are there?\")\n",
|
272
|
-
"\n",
|
273
|
-
"job_id = client.create_job(job_data)\n",
|
274
|
-
"while client.get_job().status != \"success\":\n",
|
275
|
-
" time.sleep(5)\n",
|
276
|
-
"print(f\"First job status: {client.get_job().status}\")\n",
|
277
|
-
"print(f\"First job answer: \\n{client.get_job().formatted_answer}\")"
|
278
|
-
]
|
279
|
-
},
|
280
|
-
{
|
281
|
-
"cell_type": "code",
|
282
|
-
"execution_count": null,
|
283
|
-
"metadata": {},
|
284
|
-
"outputs": [
|
285
|
-
{
|
286
|
-
"name": "stdout",
|
287
|
-
"output_type": "stream",
|
288
|
-
"text": [
|
289
|
-
"Continued job status: success\n",
|
290
|
-
"Continued job answer: \n",
|
291
|
-
"Question: You are following up on a prior task: How many species of birds are there?\n",
|
292
|
-
"\n",
|
293
|
-
"To perform a new task using prior context: From the previous answer, specifically,how many species of crows are there?\n",
|
294
|
-
"\n",
|
295
|
-
"Based on the provided context, the best-supported estimate is that there are roughly 40 species in the genus Corvus—the group commonly referred to as crows. This figure is derived from analyses that indicate crows make up around one‐third of the species diversity within the Corvidae family, which comprises about 117 species in total (krol2020crowsandravens pages 1-3). Consequently, if approximately one-third of 117 corvid species are crows, that yields roughly 40 species.\n",
|
296
|
-
"\n",
|
297
|
-
"Supporting this figure, regional assessments such as those by DeGrazio (1978) list several crow species in different areas—for example, the Common Raven (Corvus corax) and American Crow (Corvus brachyrhynchos) in North America, along with Carrion Crow (Corvus corone) and Hooded Crow (Corvus cornix) in Europe and Asia (degrazio1978worldbirddamage pages 11-12). Although these regional inventories are not complete global lists, they align with the broader taxonomic count and illustrate that the diversity of crows is widely distributed, reinforcing the overall estimate.\n",
|
298
|
-
"\n",
|
299
|
-
"It is important to note that while broader studies on bird taxonomy (such as those by Barrowclough et al. 2016) have argued that avian diversity is generally underestimated—and that even a phylogenetic species concept might double recognized numbers—the specific count for crows in the genus Corvus remains on a firmer footing due to focused analysis on this clade (barrowclough2016howmanykinds pages 1-2, 8-11). In other words, the issues of taxonomic inflation or underestimation that affect total bird species counts do not directly alter the best-supported current understanding for the number of species within Corvus.\n",
|
300
|
-
"\n",
|
301
|
-
"In summary, the weight of the evidence from the available sources indicates that there are about 40 species of crows recognized globally. This estimate is directly supported by data showing that crows represent roughly one-third of the species in the Corvidae family (krol2020crowsandravens pages 1-3) and is further corroborated by various regional inventories (degrazio1978worldbirddamage pages 11-12).\n",
|
302
|
-
"\n",
|
303
|
-
"References\n",
|
304
|
-
"\n",
|
305
|
-
"1. (barrowclough2016howmanykinds pages 1-2): George F. Barrowclough, Joel Cracraft, John Klicka, and Robert M. Zink. How many kinds of birds are there and why does it matter? PLOS ONE, 11:e0166307, Nov 2016. URL: https://doi.org/10.1371/journal.pone.0166307, doi:10.1371/journal.pone.0166307. This article has 295 citations and is from a peer-reviewed journal.\n",
|
306
|
-
"\n",
|
307
|
-
"2. (krol2020crowsandravens pages 1-3): Karol Król and Józef Hernik. Crows and ravens as indicators of socioeconomic and cultural changes in urban areas. Sustainability, 12:10231, Dec 2020. URL: https://doi.org/10.3390/su122410231, doi:10.3390/su122410231. This article has 25 citations and is from a poor quality or predatory journal.\n",
|
308
|
-
"\n",
|
309
|
-
"3. (degrazio1978worldbirddamage pages 11-12): JW DeGrazio. World bird damage problems. Unknown journal, 1978.\n",
|
310
|
-
"\n"
|
311
|
-
]
|
312
|
-
}
|
313
|
-
],
|
314
|
-
"source": [
|
315
|
-
"continued_job_data = {\n",
|
316
|
-
" \"name\": JobNames.CROW,\n",
|
317
|
-
" \"query\": \"From the previous answer, specifically,how many species of crows are there?\",\n",
|
318
|
-
" \"runtime_config\": {\"continued_job_id\": job_id},\n",
|
319
|
-
"}\n",
|
320
|
-
"\n",
|
321
|
-
"continued_job_id = client.create_job(continued_job_data)\n",
|
322
|
-
"while client.get_job().status != \"success\":\n",
|
323
|
-
" time.sleep(5)\n",
|
324
|
-
"print(f\"Continued job status: {client.get_job().status}\")\n",
|
325
|
-
"print(f\"Continued job answer: \\n{client.get_job().formatted_answer}\")"
|
326
|
-
]
|
327
|
-
}
|
328
|
-
],
|
329
|
-
"metadata": {
|
330
|
-
"kernelspec": {
|
331
|
-
"display_name": ".venv",
|
332
|
-
"language": "python",
|
333
|
-
"name": "python3"
|
334
|
-
},
|
335
|
-
"language_info": {
|
336
|
-
"codemirror_mode": {
|
337
|
-
"name": "ipython",
|
338
|
-
"version": 3
|
339
|
-
},
|
340
|
-
"file_extension": ".py",
|
341
|
-
"mimetype": "text/x-python",
|
342
|
-
"name": "python",
|
343
|
-
"nbconvert_exporter": "python",
|
344
|
-
"pygments_lexer": "ipython3"
|
345
|
-
}
|
346
|
-
},
|
347
|
-
"nbformat": 4,
|
348
|
-
"nbformat_minor": 4
|
349
|
-
}
|
@@ -1,116 +0,0 @@
|
|
1
|
-
---
|
2
|
-
jupyter:
|
3
|
-
jupytext:
|
4
|
-
text_representation:
|
5
|
-
extension: .md
|
6
|
-
format_name: markdown
|
7
|
-
format_version: "1.3"
|
8
|
-
jupytext_version: 1.16.7
|
9
|
-
kernelspec:
|
10
|
-
display_name: .venv
|
11
|
-
language: python
|
12
|
-
name: python3
|
13
|
-
---
|
14
|
-
|
15
|
-
# FutureHouse platform client usage example
|
16
|
-
|
17
|
-
```python
|
18
|
-
import time
|
19
|
-
|
20
|
-
from futurehouse_client import CrowClient, JobNames
|
21
|
-
from futurehouse_client.models import (
|
22
|
-
AuthType,
|
23
|
-
JobRequest,
|
24
|
-
RuntimeConfig,
|
25
|
-
Stage,
|
26
|
-
)
|
27
|
-
from ldp.agent import AgentConfig
|
28
|
-
```
|
29
|
-
|
30
|
-
## Client instantiation
|
31
|
-
|
32
|
-
Here we use `auth_type=AuthType.API_KEY` to authenticate with the platform.
|
33
|
-
Please log in to the platform and go to your user settings to get your API key.
|
34
|
-
|
35
|
-
```python
|
36
|
-
client = CrowClient(
|
37
|
-
stage=Stage.DEV,
|
38
|
-
auth_type=AuthType.API_KEY,
|
39
|
-
api_key="your-api-key",
|
40
|
-
)
|
41
|
-
```
|
42
|
-
|
43
|
-
## Submit a job
|
44
|
-
|
45
|
-
Submitting jobs is done by calling the `create_job` method, which receives a `JobRequest` object.
|
46
|
-
|
47
|
-
```python
|
48
|
-
job_data = JobRequest(
|
49
|
-
name=JobNames.from_string("crow"),
|
50
|
-
query="What is the molecule known to have the smallest solubility in water?",
|
51
|
-
)
|
52
|
-
client.create_job(job_data)
|
53
|
-
|
54
|
-
while client.get_job().status != "success":
|
55
|
-
time.sleep(5)
|
56
|
-
print(f"Job status: {client.get_job().status}")
|
57
|
-
print(f"Job answer: \n{client.get_job().formatted_answer}")
|
58
|
-
```
|
59
|
-
|
60
|
-
You can also pass a `runtime_config` to the job, which will be used to configure the agent on runtime.
|
61
|
-
Here, we will define a agent configuration and pass it to the job. This agent is used to decide the next action to take.
|
62
|
-
We will also use the `max_steps` parameter to limit the number of steps the agent will take.
|
63
|
-
|
64
|
-
```python
|
65
|
-
agent = AgentConfig(
|
66
|
-
agent_type="SimpleAgent",
|
67
|
-
agent_kwargs={
|
68
|
-
"model": "gpt-4o",
|
69
|
-
"temperature": 0.0,
|
70
|
-
},
|
71
|
-
)
|
72
|
-
job_data = JobRequest(
|
73
|
-
name=JobNames.CROW,
|
74
|
-
query="How many moons does earth have?",
|
75
|
-
runtime_config=RuntimeConfig(agent=agent, max_steps=10),
|
76
|
-
)
|
77
|
-
client.create_job(job_data)
|
78
|
-
|
79
|
-
while client.get_job().status != "success":
|
80
|
-
time.sleep(5)
|
81
|
-
print(f"Job status: {client.get_job().status}")
|
82
|
-
print(f"Job answer: \n{client.get_job().formatted_answer}")
|
83
|
-
```
|
84
|
-
|
85
|
-
# Continue a job
|
86
|
-
|
87
|
-
The platform allows to keep asking follow-up questions to the previous job.
|
88
|
-
To accomplish that, we can use the `runtime_config` to pass the `job_id` of the previous job.
|
89
|
-
|
90
|
-
Notice that `create_job` accepts both a `JobRequest` object and a dictionary with keywords arguments.
|
91
|
-
|
92
|
-
```python
|
93
|
-
job_data = JobRequest(name=JobNames.CROW, query="How many species of birds are there?")
|
94
|
-
|
95
|
-
job_id = client.create_job(job_data)
|
96
|
-
while client.get_job().status != "success":
|
97
|
-
time.sleep(5)
|
98
|
-
print(f"First job status: {client.get_job().status}")
|
99
|
-
print(f"First job answer: \n{client.get_job().formatted_answer}")
|
100
|
-
```
|
101
|
-
|
102
|
-
```python
|
103
|
-
continued_job_data = {
|
104
|
-
"name": JobNames.CROW,
|
105
|
-
"query": (
|
106
|
-
"From the previous answer, specifically,how many species of crows are there?"
|
107
|
-
),
|
108
|
-
"runtime_config": {"continued_job_id": job_id},
|
109
|
-
}
|
110
|
-
|
111
|
-
continued_job_id = client.create_job(continued_job_data)
|
112
|
-
while client.get_job().status != "success":
|
113
|
-
time.sleep(5)
|
114
|
-
print(f"Continued job status: {client.get_job().status}")
|
115
|
-
print(f"Continued job answer: \n{client.get_job().formatted_answer}")
|
116
|
-
```
|
@@ -1,226 +0,0 @@
|
|
1
|
-
{
|
2
|
-
"cells": [
|
3
|
-
{
|
4
|
-
"cell_type": "code",
|
5
|
-
"execution_count": null,
|
6
|
-
"metadata": {},
|
7
|
-
"outputs": [],
|
8
|
-
"source": [
|
9
|
-
"import time\n",
|
10
|
-
"from pathlib import Path\n",
|
11
|
-
"\n",
|
12
|
-
"from futurehouse_client import CrowClient, JobNames\n",
|
13
|
-
"from futurehouse_client.models import (\n",
|
14
|
-
" AuthType,\n",
|
15
|
-
" DockerContainerConfiguration,\n",
|
16
|
-
" FramePath,\n",
|
17
|
-
" JobDeploymentConfig,\n",
|
18
|
-
" JobRequest,\n",
|
19
|
-
" RuntimeConfig,\n",
|
20
|
-
" Stage,\n",
|
21
|
-
")\n",
|
22
|
-
"from ldp.agent import AgentConfig"
|
23
|
-
]
|
24
|
-
},
|
25
|
-
{
|
26
|
-
"cell_type": "code",
|
27
|
-
"execution_count": null,
|
28
|
-
"metadata": {},
|
29
|
-
"outputs": [],
|
30
|
-
"source": [
|
31
|
-
"# Instantiate the client\n",
|
32
|
-
"client = CrowClient(\n",
|
33
|
-
" stage=Stage.DEV,\n",
|
34
|
-
" auth_type=AuthType.API_KEY,\n",
|
35
|
-
" api_key=\"pOxi0pSnsJST0b7+LIp3jg.platformv01.eyJqdGkiOiJlOTI5ZGIxMy1jZDA2LTRkNjUtYTBlYi01NWYzMmQzODM1MDkiLCJzdWIiOiJOaG5kVVRkTUN2ZmkzbUZINm05S1dWTFYwU0gyIiwiaWF0IjoxNzQzMDA0NDkyLCJleHAiOjE3NDU1OTY0OTJ9.GD58gN/lDkMei3Nfw/clejJjrbL0raRKnZejzPbndfE\",\n",
|
36
|
-
")"
|
37
|
-
]
|
38
|
-
},
|
39
|
-
{
|
40
|
-
"cell_type": "code",
|
41
|
-
"execution_count": null,
|
42
|
-
"metadata": {},
|
43
|
-
"outputs": [],
|
44
|
-
"source": [
|
45
|
-
"# Create a simple Job\n",
|
46
|
-
"job_data = JobRequest(\n",
|
47
|
-
" name=JobNames.from_string(\"crow\"),\n",
|
48
|
-
" query=\"How many species of insects are there in the world?\",\n",
|
49
|
-
" n_replicates=2,\n",
|
50
|
-
")\n",
|
51
|
-
"\n",
|
52
|
-
"job_data = {\n",
|
53
|
-
" \"name\": JobNames.from_string(\"crow\"),\n",
|
54
|
-
" \"query\": \"What does the fox say?\",\n",
|
55
|
-
" \"n_replicates\": 2,\n",
|
56
|
-
"}\n",
|
57
|
-
"\n",
|
58
|
-
"\n",
|
59
|
-
"client.create_job(job_data)\n",
|
60
|
-
"\n",
|
61
|
-
"while client.get_job().status != \"success\":\n",
|
62
|
-
" time.sleep(5)\n",
|
63
|
-
"print(client.get_job())"
|
64
|
-
]
|
65
|
-
},
|
66
|
-
{
|
67
|
-
"cell_type": "code",
|
68
|
-
"execution_count": null,
|
69
|
-
"metadata": {},
|
70
|
-
"outputs": [
|
71
|
-
{
|
72
|
-
"name": "stdout",
|
73
|
-
"output_type": "stream",
|
74
|
-
"text": [
|
75
|
-
"The answer depends on the species concept and methods used. Traditional bird taxonomies—based largely on the Biological Species Concept (BSC), which defines species on reproductive isolation—yield totals of roughly 9,000 to 11,000 recognized species. In contrast, applying the Phylogenetic Species Concept (PSC), which emphasizes diagnosable, evolutionarily independent units based on morphological and genetic differences, produces estimates of around 18,000 species or even higher.\n",
|
76
|
-
"\n",
|
77
|
-
"Under traditional counts, Ernst Mayr’s 1946 assessment estimated approximately 8,600 bird species worldwide by relying on morphology and reproductive criteria, a figure that he argued was within 5–10% of the true diversity at that time (mayr1946thenumberof pages 4-7; mayr1946thenumberof pages 7-7). Similarly, Farrand and Bock’s 1980 analysis, which is based on comprehensive reviews of bird families and genera, arrived at a total near 9,021 species by compiling species counts across various families and orders (farrand1980thenumberof pages 5-6; farrand1980thenumberof pages 13-14). These figures reflect the consensus provided by mid-20th century morphological and reproductive studies and are consistent with the counts seen in earlier and contemporary taxonomic references.\n",
|
78
|
-
"\n",
|
79
|
-
"More recent compilations, however, have revised the traditional figures slightly upward. For instance, modern world bird lists such as those by Clements, Gill et al. (2021a), and HBW (2019) report totals of approximately 10,714, 10,964, and 11,135 species, respectively (kiziroglu2022analysisandcomparison pages 4-6; kiziroglu2022analysisandcomparison pages 9-11). These lists incorporate updated morphological analyses, museum records, and expert consensus. They reflect broad agreement among systematists while still showing modest differences—likely due to variations in applying species limits and taxonomic interpretations.\n",
|
80
|
-
"\n",
|
81
|
-
"In contrast to these traditional counts, research that applies the PSC reveals a dramatically higher level of avian diversity. For example, Barrowclough et al. (2016) conducted a detailed study using two independent approaches. First, they sampled 200 species from a list of 9,159 biological species and, through a diagnostic evaluation of plumage, color, and other morphological features, determined that the average biological species comprised approximately 1.97 phylogenetic species. This nearly twofold subdivision of traditional species totals led to an extrapolated estimate of about 18,043 phylogenetic species, with a bootstrap 95% confidence interval ranging from 15,845 to 20,470 species (barrowclough2016howmanykinds pages 1-2; barrowclough2016howmanykinds pages 4-5).\n",
|
82
|
-
"\n",
|
83
|
-
"The second approach employed by Barrowclough and colleagues involved an analysis of intraspecific mitochondrial DNA (mtDNA) variation across 437 traditional species. In this study, they counted an average of 2.4 evolutionary units per traditional species, which they regarded as proxies for distinct phylogenetic species. This molecular-based approach suggested even higher diversification, yielding an estimate on the order of 22,000 species (barrowclough2016howmanykinds pages 5-8). Despite inherent geographic and taxonomic biases in mtDNA data, the consistency between morphological and molecular datasets strongly indicates that traditional taxonomies based on the BSC systematically underestimate true avian diversity by a factor of 2 to 2.5.\n",
|
84
|
-
"\n",
|
85
|
-
"The discrepancy is largely due to the different criteria for what constitutes a “species.” Under the BSC, species are defined by the ability to interbreed and produce fertile offspring, often overlooking populations that are genetically and morphologically distinct but not reproductively isolated under natural conditions. In contrast, the PSC emphasizes unique character states and genetic differences that delineate separate evolutionary lineages even if ongoing hybridization occurs in nature. Thus, many traditional “subspecies” or geographically distinct forms, which may be diagnosably distinct in plumage or DNA, are treated as separate species under the PSC. This shift in definition results in a considerable increase in the number of recognized species (barrowclough2016howmanykinds pages 2-4).\n",
|
86
|
-
"\n",
|
87
|
-
"Furthermore, Barrowclough et al. noted that the degree of hidden diversity is not evenly distributed. Their analyses revealed a strong latitudinal gradient: the average number of phylogenetic units per species rises from about 1.4 in northern temperate regions to roughly 3.5 near the equator. This geographic pattern suggests that tropical regions harbor substantially more cryptic diversity than indicated by classical morphological studies alone (barrowclough2016howmanykinds pages 5-8). Consequently, the phylogenetic species counts, especially within the tropics, are likely to be even higher than those derived from average calculations.\n",
|
88
|
-
"\n",
|
89
|
-
"Historically, estimates offered by different authors have varied widely. For instance, Sharpe’s early 20th-century figures inflated species counts (due in part to treating many subspecies as full species), while Mayr’s mid-century work sought to provide a more conservative count based on reproductive isolation. The developments in molecular techniques and quantitative morphological analysis during the latter part of the 20th century further adjusted the perceived totals. Nonetheless, the progression from an 8,600–9,000 species count in earlier works (mayr1946thenumberof; farrand1980thenumberof) to over 10,000 species in recent checklists (kiziroglu2022analysisandcomparison) and then to the near doubling suggested by evolutionary analyses (barrowclough2016howmanykinds) encapsulates the evolution of species concepts in ornithology.\n",
|
90
|
-
"\n",
|
91
|
-
"In summary, when describing the global number of bird species, it is essential to distinguish between two frameworks:\n",
|
92
|
-
" • Traditional counts based on the Biological Species Concept yield between approximately 8,600 and 11,100 species, as supported by Mayr (1946), Farrand and Bock (1980), and contemporary world bird lists (mayr1946thenumberof pages 4-7; farrand1980thenumberof pages 5-6; kiziroglu2022analysisandcomparison pages 4-6; kiziroglu2022analysisandcomparison pages 9-11).\n",
|
93
|
-
" • Revised estimates based on the Phylogenetic Species Concept—incorporating both morphological (barrowclough2016howmanykinds pages 1-2; barrowclough2016howmanykinds pages 4-5) and molecular data (barrowclough2016howmanykinds pages 5-8)—suggest that avian diversity is underestimated by roughly a factor of two, with potentially around 18,000 phylogenetic species, and mtDNA analyses hinting at figures closer to 22,000 species.\n",
|
94
|
-
"\n",
|
95
|
-
"The choice of species concept has profound implications not only for systematic biology but also for conservation strategies, biogeographic analyses, and our overall understanding of evolutionary history. Recognizing nearly twice as many species under the PSC implies a finer resolution of evolutionary processes, particularly in regions like the tropics where genetic and morphological divergence can be especially pronounced (barrowclough2016howmanykinds pages 5-8).\n",
|
96
|
-
"\n",
|
97
|
-
"Thus, while the current traditional taxonomy records approximately 9,000–11,000 bird species, there is growing evidence that the true evolutionary diversity may be as high as 18,000 to 22,000 species. The answer—there is no single definitive number—is intrinsically tied to how one defines “species” and the methodologies employed to detect and describe genetic and morphological differences within and between bird populations.\n",
|
98
|
-
"\n",
|
99
|
-
"Each of these counts is valid within its methodological framework, and the ongoing debate underscores the dynamic nature of biological classification in the age of genomics and comparative morphology. Future comprehensive studies that integrate extensive geographic sampling and genome-wide data are likely to refine these estimates further, perhaps even revealing additional layers of cryptic diversity within what are currently regarded as single species (barrowclough2016howmanykinds pages 2-4; kiziroglu2022analysisandcomparison pages 9-11).\n",
|
100
|
-
"\n",
|
101
|
-
"In conclusion, if one adheres to traditional taxonomies based on the Biological Species Concept, the world harbors roughly 9,000–11,000 bird species. However, if one embraces the Phylogenetic Species Concept—supported by both morphological and molecular evidence—the actual number of bird species could be roughly double that figure, ranging from approximately 18,000 to 22,000 species (barrowclough2016howmanykinds pages 1-2; barrowclough2016howmanykinds pages 5-8; mayr1946thenumberof pages 4-7; kiziroglu2022analysisandcomparison pages 4-6).\n"
|
102
|
-
]
|
103
|
-
},
|
104
|
-
{
|
105
|
-
"data": {
|
106
|
-
"text/plain": [
|
107
|
-
"{'Barrowclough et al. (2016',\n",
|
108
|
-
" 'barrowclough2016howmanykinds',\n",
|
109
|
-
" 'barrowclough2016howmanykinds pages 1-2',\n",
|
110
|
-
" 'barrowclough2016howmanykinds pages 2-4',\n",
|
111
|
-
" 'barrowclough2016howmanykinds pages 4-5',\n",
|
112
|
-
" 'barrowclough2016howmanykinds pages 5-8',\n",
|
113
|
-
" 'farrand1980thenumberof',\n",
|
114
|
-
" 'farrand1980thenumberof pages 13-14',\n",
|
115
|
-
" 'farrand1980thenumberof pages 5-6',\n",
|
116
|
-
" 'kiziroglu2022analysisandcomparison',\n",
|
117
|
-
" 'kiziroglu2022analysisandcomparison pages 4-6',\n",
|
118
|
-
" 'kiziroglu2022analysisandcomparison pages 9-11',\n",
|
119
|
-
" 'mayr1946thenumberof',\n",
|
120
|
-
" 'mayr1946thenumberof pages 4-7',\n",
|
121
|
-
" 'mayr1946thenumberof pages 7-7'}"
|
122
|
-
]
|
123
|
-
},
|
124
|
-
"execution_count": null,
|
125
|
-
"metadata": {},
|
126
|
-
"output_type": "execute_result"
|
127
|
-
}
|
128
|
-
],
|
129
|
-
"source": [
|
130
|
-
"from paperqa.utils import get_citenames\n",
|
131
|
-
"\n",
|
132
|
-
"bug_id = \"d398d963-1e4c-4191-b9f2-c8df55376cb0\"\n",
|
133
|
-
"job = client.get_job(bug_id)\n",
|
134
|
-
"\n",
|
135
|
-
"print(job.answer)\n",
|
136
|
-
"\n",
|
137
|
-
"get_citenames(job.answer)\n",
|
138
|
-
"# job.environment_frame['state']['state'].keys()"
|
139
|
-
]
|
140
|
-
},
|
141
|
-
{
|
142
|
-
"cell_type": "code",
|
143
|
-
"execution_count": null,
|
144
|
-
"metadata": {},
|
145
|
-
"outputs": [],
|
146
|
-
"source": [
|
147
|
-
"# Create a more complex job with runtime config\n",
|
148
|
-
"\n",
|
149
|
-
"agent = AgentConfig(\n",
|
150
|
-
" agent_type=\"ReActAgent\",\n",
|
151
|
-
" agent_kwargs={\n",
|
152
|
-
" \"model\": \"gpt-4o-mini\",\n",
|
153
|
-
" \"temperature\": 0.0,\n",
|
154
|
-
" },\n",
|
155
|
-
")\n",
|
156
|
-
"job_data = JobRequest(\n",
|
157
|
-
" name=JobNames.from_string(\"dummy\"),\n",
|
158
|
-
" query=\"How many moons does earth have?\",\n",
|
159
|
-
" runtime_config=RuntimeConfig(agent=agent, max_steps=5),\n",
|
160
|
-
")\n",
|
161
|
-
"client.create_job(job_data)\n",
|
162
|
-
"\n",
|
163
|
-
"while client.get_job()[\"status\"] != \"success\":\n",
|
164
|
-
" time.sleep(5)\n",
|
165
|
-
"print(client.get_job())"
|
166
|
-
]
|
167
|
-
},
|
168
|
-
{
|
169
|
-
"cell_type": "code",
|
170
|
-
"execution_count": null,
|
171
|
-
"metadata": {},
|
172
|
-
"outputs": [],
|
173
|
-
"source": [
|
174
|
-
"# Deploy a Crow with Frame Paths\n",
|
175
|
-
"frame_paths = [\n",
|
176
|
-
" FramePath(path=\"state.pdbs\", type=\"pdb\", is_iterable=True),\n",
|
177
|
-
" FramePath(path=\"state.single_pdb\", type=\"pdb\"),\n",
|
178
|
-
"]\n",
|
179
|
-
"\n",
|
180
|
-
"crow = JobDeploymentConfig(\n",
|
181
|
-
" path=Path(\"../../envs/dummy_env\"),\n",
|
182
|
-
" environment=\"dummy_env.env.DummyEnv\",\n",
|
183
|
-
" requires_aviary_internal=False,\n",
|
184
|
-
" environment_variables={\"SAMPLE_ENV_VAR\": \"sample_val\"},\n",
|
185
|
-
" agent=\"ldp.agent.SimpleAgent\",\n",
|
186
|
-
" container_config=DockerContainerConfiguration(cpu=\"1\", memory=\"2Gi\"),\n",
|
187
|
-
" force=True,\n",
|
188
|
-
" frame_paths=frame_paths,\n",
|
189
|
-
" task_description=\"This is a dummy task\",\n",
|
190
|
-
")\n",
|
191
|
-
"client.create_crow(crow)"
|
192
|
-
]
|
193
|
-
},
|
194
|
-
{
|
195
|
-
"cell_type": "code",
|
196
|
-
"execution_count": null,
|
197
|
-
"metadata": {},
|
198
|
-
"outputs": [],
|
199
|
-
"source": [
|
200
|
-
"while client.get_build_status()[\"status\"] != \"SUCCESS\":\n",
|
201
|
-
" time.sleep(5)\n",
|
202
|
-
"print(client.get_build_status())"
|
203
|
-
]
|
204
|
-
}
|
205
|
-
],
|
206
|
-
"metadata": {
|
207
|
-
"kernelspec": {
|
208
|
-
"display_name": ".venv",
|
209
|
-
"language": "python",
|
210
|
-
"name": "python3"
|
211
|
-
},
|
212
|
-
"language_info": {
|
213
|
-
"codemirror_mode": {
|
214
|
-
"name": "ipython",
|
215
|
-
"version": 3
|
216
|
-
},
|
217
|
-
"file_extension": ".py",
|
218
|
-
"mimetype": "text/x-python",
|
219
|
-
"name": "python",
|
220
|
-
"nbconvert_exporter": "python",
|
221
|
-
"pygments_lexer": "ipython3"
|
222
|
-
}
|
223
|
-
},
|
224
|
-
"nbformat": 4,
|
225
|
-
"nbformat_minor": 4
|
226
|
-
}
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
{futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/clients/__init__.py
RENAMED
File without changes
|
{futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/clients/job_client.py
RENAMED
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
{futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client/utils/module_utils.py
RENAMED
File without changes
|
File without changes
|
{futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client.egg-info/requires.txt
RENAMED
File without changes
|
{futurehouse_client-0.0.3 → futurehouse_client-0.0.4}/futurehouse_client.egg-info/top_level.txt
RENAMED
File without changes
|
File without changes
|
File without changes
|
File without changes
|