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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: futurehouse-client
-Version: 0.0.2
+Version: 0.0.3
 Summary: A client for interacting with endpoints of the FutureHouse service.
 Author-email: FutureHouse technical staff <hello@futurehouse.org>
 Classifier: Operating System :: OS Independent
@@ -70,7 +70,7 @@ from aviary.core import DummyEnv
 import ldp
 
 client = CrowClient(
-    stage=Stage.DEV,
+    stage=Stage.PROD,
     auth_type=AuthType.API_KEY,
     api_key="your_api_key",
 )
@@ -110,7 +110,7 @@ from crow_client import CrowClient
 from crow_client.models import Stage, AuthType
 
 client = CrowClient(
-    stage=Stage.DEV,
+    stage=Stage.PROD,
     organization="your_organization",
     auth_type=AuthType.API_KEY,
     api_key="your_api_key",
@@ -150,7 +150,7 @@ from crow_client import CrowClient, JobNames
 from crow_client.models import AuthType, Stage
 
 client = CrowClient(
-    stage=Stage.DEV,
+    stage=Stage.PROD,
     auth_type=AuthType.API_KEY,
     api_key="your_api_key",
 )
@@ -186,7 +186,7 @@ from crow_client import CrowClient, JobNames
 from crow_client.models import AuthType, Stage
 
 client = CrowClient(
-    stage=Stage.DEV,
+    stage=Stage.PROD,
     auth_type=AuthType.API_KEY,
     api_key="your_api_key",
 )

{futurehouse_client-0.0.2 → futurehouse_client-0.0.3}/README.md

@@ -32,7 +32,7 @@ from aviary.core import DummyEnv
 import ldp
 
 client = CrowClient(
-    stage=Stage.DEV,
+    stage=Stage.PROD,
     auth_type=AuthType.API_KEY,
     api_key="your_api_key",
 )
@@ -72,7 +72,7 @@ from crow_client import CrowClient
 from crow_client.models import Stage, AuthType
 
 client = CrowClient(
-    stage=Stage.DEV,
+    stage=Stage.PROD,
     organization="your_organization",
     auth_type=AuthType.API_KEY,
     api_key="your_api_key",
@@ -112,7 +112,7 @@ from crow_client import CrowClient, JobNames
 from crow_client.models import AuthType, Stage
 
 client = CrowClient(
-    stage=Stage.DEV,
+    stage=Stage.PROD,
     auth_type=AuthType.API_KEY,
     api_key="your_api_key",
 )
@@ -148,7 +148,7 @@ from crow_client import CrowClient, JobNames
 from crow_client.models import AuthType, Stage
 
 client = CrowClient(
-    stage=Stage.DEV,
+    stage=Stage.PROD,
     auth_type=AuthType.API_KEY,
     api_key="your_api_key",
 )

futurehouse_client-0.0.3/docs/client_notebook.ipynb

@@ -0,0 +1,349 @@
+{
+ "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": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Job status: success\n",
+      "Job answer: \n",
+      "Question: What is the molecule known to have the greatest solubility in water?\n",
+      "\n",
+      "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",
+      "\n"
+     ]
+    }
+   ],
+   "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": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Job status: success\n",
+      "Job answer: \n",
+      "Question: How many moons does earth have?\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "To summarize, Earth’s satellite environment consists of:\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "References\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "3. (moonsUnknownyearallmoonsgreat pages 1-2): J Moons. All moons great and small... Unknown journal, Unknown year.\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "11. (petersUnknownyearmanybluemoonsa pages 8-9): ART Peters. Many blue moons. Unknown journal, Unknown year.\n",
+      "\n",
+      "12. (petersUnknownyearmanybluemoons pages 8-9): ART Peters. Many blue moons. Unknown journal, Unknown year.\n",
+      "\n",
+      "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",
+      "\n"
+     ]
+    }
+   ],
+   "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": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "First job status: success\n",
+      "First job answer: \n",
+      "Question: How many species of birds are there?\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "In summary, if one asks “How many species of birds are there?” there are two relevant answers depending on the species concept:\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "References\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n"
+     ]
+    }
+   ],
+   "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": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Continued job status: success\n",
+      "Continued job answer: \n",
+      "Question: You are following up on a prior task: How many species of birds are there?\n",
+      "\n",
+      "To perform a new task using prior context: From the previous answer, specifically,how many species of crows are there?\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "References\n",
+      "\n",
+      "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",
+      "\n",
+      "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",
+      "\n",
+      "3. (degrazio1978worldbirddamage pages 11-12): JW DeGrazio. World bird damage problems. Unknown journal, 1978.\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "continued_job_data = {\n",
+    "    \"name\": JobNames.CROW,\n",
+    "    \"query\": \"From the previous answer, specifically,how many species of crows are there?\",\n",
+    "    \"runtime_config\": {\"continued_job_id\": job_id},\n",
+    "}\n",
+    "\n",
+    "continued_job_id = client.create_job(continued_job_data)\n",
+    "while client.get_job().status != \"success\":\n",
+    "    time.sleep(5)\n",
+    "print(f\"Continued job status: {client.get_job().status}\")\n",
+    "print(f\"Continued job answer: \\n{client.get_job().formatted_answer}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

futurehouse_client-0.0.3/docs/client_notebook.md

@@ -0,0 +1,116 @@
+---
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: "1.3"
+      jupytext_version: 1.16.7
+  kernelspec:
+    display_name: .venv
+    language: python
+    name: python3
+---
+
+# FutureHouse platform client usage example
+
+```python
+import time
+
+from futurehouse_client import CrowClient, JobNames
+from futurehouse_client.models import (
+    AuthType,
+    JobRequest,
+    RuntimeConfig,
+    Stage,
+)
+from ldp.agent import AgentConfig
+```
+
+## Client instantiation
+
+Here we use `auth_type=AuthType.API_KEY` to authenticate with the platform.
+Please log in to the platform and go to your user settings to get your API key.
+
+```python
+client = CrowClient(
+    stage=Stage.DEV,
+    auth_type=AuthType.API_KEY,
+    api_key="your-api-key",
+)
+```
+
+## Submit a job
+
+Submitting jobs is done by calling the `create_job` method, which receives a `JobRequest` object.
+
+```python
+job_data = JobRequest(
+    name=JobNames.from_string("crow"),
+    query="What is the molecule known to have the smallest solubility in water?",
+)
+client.create_job(job_data)
+
+while client.get_job().status != "success":
+    time.sleep(5)
+print(f"Job status: {client.get_job().status}")
+print(f"Job answer: \n{client.get_job().formatted_answer}")
+```
+
+You can also pass a `runtime_config` to the job, which will be used to configure the agent on runtime.
+Here, we will define a agent configuration and pass it to the job. This agent is used to decide the next action to take.
+We will also use the `max_steps` parameter to limit the number of steps the agent will take.
+
+```python
+agent = AgentConfig(
+    agent_type="SimpleAgent",
+    agent_kwargs={
+        "model": "gpt-4o",
+        "temperature": 0.0,
+    },
+)
+job_data = JobRequest(
+    name=JobNames.CROW,
+    query="How many moons does earth have?",
+    runtime_config=RuntimeConfig(agent=agent, max_steps=10),
+)
+client.create_job(job_data)
+
+while client.get_job().status != "success":
+    time.sleep(5)
+print(f"Job status: {client.get_job().status}")
+print(f"Job answer: \n{client.get_job().formatted_answer}")
+```
+
+# Continue a job
+
+The platform allows to keep asking follow-up questions to the previous job.
+To accomplish that, we can use the `runtime_config` to pass the `job_id` of the previous job.
+
+Notice that `create_job` accepts both a `JobRequest` object and a dictionary with keywords arguments.
+
+```python
+job_data = JobRequest(name=JobNames.CROW, query="How many species of birds are there?")
+
+job_id = client.create_job(job_data)
+while client.get_job().status != "success":
+    time.sleep(5)
+print(f"First job status: {client.get_job().status}")
+print(f"First job answer: \n{client.get_job().formatted_answer}")
+```
+
+```python
+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)
+while client.get_job().status != "success":
+    time.sleep(5)
+print(f"Continued job status: {client.get_job().status}")
+print(f"Continued job answer: \n{client.get_job().formatted_answer}")
+```