futuresearch 0.6.0__py3-none-any.whl

futuresearch/__init__.py

@@ -0,0 +1,28 @@
+from importlib.metadata import version
+
+from futuresearch.api_utils import create_client
+from futuresearch.billing import BillingResponse, get_billing_balance
+from futuresearch.session import (
+    Session,
+    SessionInfo,
+    SessionListResult,
+    create_session,
+    list_sessions,
+)
+from futuresearch.task import fetch_task_data, print_progress
+
+__version__ = version("futuresearch")
+
+__all__ = [
+    "BillingResponse",
+    "Session",
+    "SessionInfo",
+    "SessionListResult",
+    "__version__",
+    "create_client",
+    "create_session",
+    "fetch_task_data",
+    "get_billing_balance",
+    "list_sessions",
+    "print_progress",
+]

futuresearch/api_utils.py

@@ -0,0 +1,65 @@
+import os
+from typing import TypeVar
+
+from futuresearch.constants import DEFAULT_FUTURESEARCH_API_URL, FuturesearchError
+from futuresearch.generated.client import AuthenticatedClient
+from futuresearch.generated.models.error_response import ErrorResponse
+from futuresearch.generated.models.http_validation_error import HTTPValidationError
+from futuresearch.generated.models.insufficient_balance_response import (
+    InsufficientBalanceResponse,
+)
+
+# Backwards compatibility alias
+EveryrowError = FuturesearchError
+
+
+def create_client() -> AuthenticatedClient:
+    """Create an AuthenticatedClient from environment variables.
+
+    Reads FUTURESEARCH_API_KEY (or legacy EVERYROW_API_KEY) and
+    FUTURESEARCH_API_URL (or legacy EVERYROW_API_URL) from environment variables.
+
+    Returns:
+        AuthenticatedClient: A configured client instance
+
+    Raises:
+        ValueError: If no API key is set in environment
+    """
+    api_key = os.environ.get("FUTURESEARCH_API_KEY") or os.environ.get(
+        "EVERYROW_API_KEY"
+    )
+    if not api_key:
+        raise ValueError("FUTURESEARCH_API_KEY is not set; cannot initialize client")
+    api_url = (
+        os.environ.get("FUTURESEARCH_API_URL")
+        or os.environ.get("EVERYROW_API_URL")
+        or DEFAULT_FUTURESEARCH_API_URL
+    )
+    return AuthenticatedClient(
+        base_url=api_url,
+        token=api_key,
+        raise_on_unexpected_status=True,
+        follow_redirects=True,
+    )
+
+
+T = TypeVar("T")
+
+
+def handle_response[T](
+    response: T
+    | ErrorResponse
+    | HTTPValidationError
+    | InsufficientBalanceResponse
+    | None,
+) -> T:
+    if isinstance(response, ErrorResponse):
+        raise FuturesearchError(response.message)
+    if isinstance(response, HTTPValidationError):
+        raise FuturesearchError(response.detail)
+    if isinstance(response, InsufficientBalanceResponse):
+        raise FuturesearchError(response.message)
+    if response is None:
+        raise FuturesearchError("Unknown error")
+
+    return response

futuresearch/billing.py

@@ -0,0 +1,29 @@
+"""Billing utilities for futuresearch SDK."""
+
+from dataclasses import dataclass
+
+from futuresearch.api_utils import create_client
+from futuresearch.generated.api.billing import get_billing_balance_billing_get
+
+
+@dataclass
+class BillingResponse:
+    """Response containing the user's current billing balance."""
+
+    current_balance_dollars: float
+
+
+async def get_billing_balance() -> BillingResponse:
+    """Get the current billing balance for the authenticated user.
+
+    Returns:
+        BillingResponse containing the user's current balance.
+
+    Raises:
+        RuntimeError: If the request fails
+    """
+    client = create_client()
+    response = await get_billing_balance_billing_get.asyncio(client=client)
+    if response is None:
+        raise RuntimeError("Failed to get billing balance")
+    return BillingResponse(current_balance_dollars=response.current_balance_dollars)

futuresearch/built_in_lists.py

@@ -0,0 +1,104 @@
+"""Built-in lists: browse and import pre-built datasets."""
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from futuresearch.constants import EveryrowError
+from futuresearch.generated.client import AuthenticatedClient
+from futuresearch.session import Session
+
+
+@dataclass
+class BuiltInListItem:
+    """A built-in dataset available for import."""
+
+    name: str
+    artifact_id: UUID
+    category: str
+    fields: list[str]
+
+
+@dataclass
+class UseBuiltInListResult:
+    """Result of importing a built-in list into a session."""
+
+    artifact_id: UUID
+    session_id: UUID
+    task_id: UUID
+
+
+async def list_built_in_datasets(
+    client: AuthenticatedClient,
+    search: str | None = None,
+    category: str | None = None,
+) -> list[BuiltInListItem]:
+    """Fetch available built-in datasets from the API.
+
+    Args:
+        client: Authenticated API client.
+        search: Optional search term to match against list names (case-insensitive).
+        category: Optional category filter.
+
+    Returns:
+        List of available built-in datasets.
+    """
+    params: dict[str, str] = {}
+    if search:
+        params["search"] = search
+    if category:
+        params["category"] = category
+
+    response = await client.get_async_httpx_client().request(
+        method="GET",
+        url="/built-in-lists",
+        params=params,
+    )
+    if response.status_code != 200:
+        raise EveryrowError(f"Failed to list built-in datasets: {response.text}")
+
+    data = response.json()
+    return [
+        BuiltInListItem(
+            name=item["name"],
+            artifact_id=UUID(item["artifact_id"]),
+            category=item["category"],
+            fields=item["fields"],
+        )
+        for item in data.get("lists", [])
+    ]
+
+
+async def use_built_in_list(
+    artifact_id: UUID,
+    session: Session,
+    session_id: UUID | None = None,
+) -> UseBuiltInListResult:
+    """Copy a built-in list into a session, ready for use in operations.
+
+    Args:
+        artifact_id: The artifact_id from browse results.
+        session: Session object (provides client and session_id).
+        session_id: Optional override session_id. Defaults to session.session_id.
+
+    Returns:
+        UseBuiltInListResult with the new artifact_id, session_id, and task_id.
+    """
+    body = {
+        "artifact_id": str(artifact_id),
+        "session_id": str(session_id or session.session_id),
+    }
+
+    response = await session.client.get_async_httpx_client().request(
+        method="POST",
+        url="/built-in-lists/use",
+        json=body,
+    )
+    if response.status_code != 200:
+        raise EveryrowError(f"Failed to use built-in list: {response.text}")
+
+    data = response.json()
+    return UseBuiltInListResult(
+        artifact_id=UUID(data["artifact_id"]),
+        session_id=UUID(data["session_id"]),
+        task_id=UUID(data["task_id"]),
+    )

futuresearch/constants.py

@@ -0,0 +1,13 @@
+DEFAULT_FUTURESEARCH_APP_URL = "https://futuresearch.ai"
+DEFAULT_FUTURESEARCH_API_URL = "https://futuresearch.ai/api/v0"
+
+# Backwards compatibility aliases
+DEFAULT_EVERYROW_APP_URL = DEFAULT_FUTURESEARCH_APP_URL
+DEFAULT_EVERYROW_API_URL = DEFAULT_FUTURESEARCH_API_URL
+
+
+class FuturesearchError(Exception): ...
+
+
+# Backwards compatibility alias
+EveryrowError = FuturesearchError

futuresearch/generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing futuresearch API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

futuresearch/generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

futuresearch/generated/api/artifacts/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

futuresearch/generated/api/artifacts/upload_data_artifacts_upload_post.py

@@ -0,0 +1,212 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.create_artifact_response import CreateArtifactResponse
+from ...models.error_response import ErrorResponse
+from ...models.upload_data_artifacts_upload_post_files_body import UploadDataArtifactsUploadPostFilesBody
+from ...models.upload_data_artifacts_upload_post_json_body import UploadDataArtifactsUploadPostJsonBody
+from ...types import UNSET, Response, Unset
+
+
+def _get_kwargs(
+    *,
+    body: UploadDataArtifactsUploadPostJsonBody | UploadDataArtifactsUploadPostFilesBody | Unset = UNSET,
+    x_cohort_source: None | str | Unset = UNSET,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+    if not isinstance(x_cohort_source, Unset):
+        headers["X-Cohort-Source"] = x_cohort_source
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/artifacts/upload",
+    }
+
+    if isinstance(body, UploadDataArtifactsUploadPostJsonBody):
+        _kwargs["json"] = body.to_dict()
+
+        headers["Content-Type"] = "application/json"
+    if isinstance(body, UploadDataArtifactsUploadPostFilesBody):
+        _kwargs["files"] = body.to_multipart()
+
+        headers["Content-Type"] = "multipart/form-data"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> CreateArtifactResponse | ErrorResponse | None:
+    if response.status_code == 200:
+        response_200 = CreateArtifactResponse.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 422:
+        response_422 = ErrorResponse.from_dict(response.json())
+
+        return response_422
+
+    if response.status_code == 504:
+        response_504 = ErrorResponse.from_dict(response.json())
+
+        return response_504
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[CreateArtifactResponse | ErrorResponse]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: UploadDataArtifactsUploadPostJsonBody | UploadDataArtifactsUploadPostFilesBody | Unset = UNSET,
+    x_cohort_source: None | str | Unset = UNSET,
+) -> Response[CreateArtifactResponse | ErrorResponse]:
+    """Upload data as an artifact (CSV or JSON)
+
+     Unified upload endpoint. Send a CSV/TSV file as multipart/form-data, or send JSON data as
+    application/json. Both paths create an UPLOAD_DATA task and return artifact_id, session_id, and
+    task_id.
+
+    Args:
+        x_cohort_source (None | str | Unset):
+        body (UploadDataArtifactsUploadPostJsonBody):
+        body (UploadDataArtifactsUploadPostFilesBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[CreateArtifactResponse | ErrorResponse]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+        x_cohort_source=x_cohort_source,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+    body: UploadDataArtifactsUploadPostJsonBody | UploadDataArtifactsUploadPostFilesBody | Unset = UNSET,
+    x_cohort_source: None | str | Unset = UNSET,
+) -> CreateArtifactResponse | ErrorResponse | None:
+    """Upload data as an artifact (CSV or JSON)
+
+     Unified upload endpoint. Send a CSV/TSV file as multipart/form-data, or send JSON data as
+    application/json. Both paths create an UPLOAD_DATA task and return artifact_id, session_id, and
+    task_id.
+
+    Args:
+        x_cohort_source (None | str | Unset):
+        body (UploadDataArtifactsUploadPostJsonBody):
+        body (UploadDataArtifactsUploadPostFilesBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        CreateArtifactResponse | ErrorResponse
+    """
+
+    return sync_detailed(
+        client=client,
+        body=body,
+        x_cohort_source=x_cohort_source,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+    body: UploadDataArtifactsUploadPostJsonBody | UploadDataArtifactsUploadPostFilesBody | Unset = UNSET,
+    x_cohort_source: None | str | Unset = UNSET,
+) -> Response[CreateArtifactResponse | ErrorResponse]:
+    """Upload data as an artifact (CSV or JSON)
+
+     Unified upload endpoint. Send a CSV/TSV file as multipart/form-data, or send JSON data as
+    application/json. Both paths create an UPLOAD_DATA task and return artifact_id, session_id, and
+    task_id.
+
+    Args:
+        x_cohort_source (None | str | Unset):
+        body (UploadDataArtifactsUploadPostJsonBody):
+        body (UploadDataArtifactsUploadPostFilesBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[CreateArtifactResponse | ErrorResponse]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+        x_cohort_source=x_cohort_source,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+    body: UploadDataArtifactsUploadPostJsonBody | UploadDataArtifactsUploadPostFilesBody | Unset = UNSET,
+    x_cohort_source: None | str | Unset = UNSET,
+) -> CreateArtifactResponse | ErrorResponse | None:
+    """Upload data as an artifact (CSV or JSON)
+
+     Unified upload endpoint. Send a CSV/TSV file as multipart/form-data, or send JSON data as
+    application/json. Both paths create an UPLOAD_DATA task and return artifact_id, session_id, and
+    task_id.
+
+    Args:
+        x_cohort_source (None | str | Unset):
+        body (UploadDataArtifactsUploadPostJsonBody):
+        body (UploadDataArtifactsUploadPostFilesBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        CreateArtifactResponse | ErrorResponse
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+            body=body,
+            x_cohort_source=x_cohort_source,
+        )
+    ).parsed

futuresearch/generated/api/billing/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

futuresearch/generated/api/billing/get_billing_balance_billing_get.py

@@ -0,0 +1,131 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.billing_response import BillingResponse
+from ...types import Response
+
+
+def _get_kwargs() -> dict[str, Any]:
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/billing",
+    }
+
+    return _kwargs
+
+
+def _parse_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> BillingResponse | None:
+    if response.status_code == 200:
+        response_200 = BillingResponse.from_dict(response.json())
+
+        return response_200
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(*, client: AuthenticatedClient | Client, response: httpx.Response) -> Response[BillingResponse]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+) -> Response[BillingResponse]:
+    """Get billing balance
+
+     Get the current billing balance for the authenticated user.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[BillingResponse]
+    """
+
+    kwargs = _get_kwargs()
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+) -> BillingResponse | None:
+    """Get billing balance
+
+     Get the current billing balance for the authenticated user.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        BillingResponse
+    """
+
+    return sync_detailed(
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+) -> Response[BillingResponse]:
+    """Get billing balance
+
+     Get the current billing balance for the authenticated user.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[BillingResponse]
+    """
+
+    kwargs = _get_kwargs()
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+) -> BillingResponse | None:
+    """Get billing balance
+
+     Get the current billing balance for the authenticated user.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        BillingResponse
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+        )
+    ).parsed

futuresearch/generated/api/built_in_lists/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""