SDK

The Lumigator SDK is a Python library that provides a simple interface to interact with the Lumigator API. You can use it to create, update, delete, and list datasets, submit and monitor jobs, download the results, request completions, and more.

Lumigator Client

The main entry point to the SDK is the LumigatorClient class. You can create an instance of this class by providing the Lumigator API host and your Ray cluster address.

class lumigator_sdk.lumigator.LumigatorClient(api_host: str, ray_host: str = '127.0.0.1:8265', retry_conf: Retry | None = Retry(total=10, connect=5, read=None, redirect=None, status=None))

__init__(api_host: str, ray_host: str = '127.0.0.1:8265', retry_conf: Retry | None = Retry(total=10, connect=5, read=None, redirect=None, status=None))

Construct a new LumigatorClient instance.

Construct a new LumigatorClient instance with a given API and Ray host. The client provides access to the Lumigator API, permitting users to interact with the Lumigator services.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")

Parameters:

api_host (str) – The API host to connect to.
ray_host (str) – The Ray host to connect to. Defaults to 127.0.0.1:8265.

Returns:

A new LumigatorClient instance.

Return type:

LumigatorClient

Health

The Health class provides a simple interface to check the health of the Lumigator API and the status of the Ray jobs running on the cluster.

class lumigator_sdk.health.Health(c: ApiClient)

HEALTH_ROUTE = 'health'

__init__(c: ApiClient)

Construct a new instance of the Health class.

Parameters:: c (ApiClient) – The API client to use for requests.
Returns:: A new Health instance.
Return type:: Health

healthcheck() → HealthCheck | None

Return healthcheck information.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.health.healthcheck()

Returns:: The healthcheck information.
Return type:: HealthCheck | None

class lumigator_sdk.health.HealthCheck

__init__()

Construct a new instance of the HealthCheck class.

status

The status of the healthcheck.

Type:: str

deployment_type

The deployment type of the healthcheck.

Type:: str

Returns:: A new HealthCheck instance.
Return type:: HealthCheck

ok()

Always return status OK.

Returns:: Status OK.
Return type:: str

Datasets

The Datasets class provides a simple interface to create, update, delete, and list datasets.

class lumigator_sdk.lm_datasets.Datasets(c: ApiClient)

DATASETS_ROUTE = 'datasets'

__init__(c: ApiClient)

Construct a new instance of the Datasets class.

Parameters:: c (ApiClient) – The API client to use for requests.
Returns:: A new Datasets instance.
Return type:: Datasets

create_dataset(dataset: IOBase, format: DatasetFormat) → DatasetResponse

Create a new dataset.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.datasets.create_dataset(dataset, dataset_format)

Parameters:

dataset (IOBase) – a bytes-like object containing the dataset itself.
format (DatasetFormat) – currently, always DatasetFormat.JOB.

Returns:

the information for the newly created dataset.

Return type:

DatasetResponse

delete_dataset(id: UUID) → None

Delete a specific dataset.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.datasets.delete_dataset(dataset_id)

Parameters:: id (UUID) – the ID of the dataset to retrieve

get_dataset(id: UUID) → DatasetResponse

Return information on a specific dataset.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.datasets.get_dataset(dataset_id)

Parameters:: id (UUID) – The ID of the dataset to retrieve
Returns:: the dataset information for the provided ID.
Return type:: DatasetResponse

get_dataset_link(id: UUID) → DatasetDownloadResponse

Return the download link for a specific dataset.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.datasets.get_dataset_link(dataset_id)

Parameters:

id (UUID) – the ID of the dataset whose download link we want to obtain.

Returns:

the download link for the requested: dataset.

Return type:

DatasetDownloadResponse

get_datasets() → ListingResponse[DatasetResponse]

Return information on all datasets.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.datasets.get_datasets()

Returns:: All existing datasets.
Return type:: ListingResponse[DatasetResponse]

Jobs

The Jobs class provides a simple interface to submit and monitor jobs. Currently, we support two types of jobs: Inference and Evaluation.

Jobs SDK

Provides a class to manipulate jobs in Lumigator.

class lumigator_sdk.jobs.Jobs(c: ApiClient)

JOBS_ROUTE = 'jobs'

__init__(c: ApiClient)

Construct a new instance of the Jobs class.

Parameters:: c (ApiClient) – the API client to use for requests.
Returns:: a new Jobs instance.
Return type:: Jobs

create_job(type: JobType, request: JobEvalCreate | JobInferenceCreate) → JobResponse

Create a new job.

Example

from sdk.lumigator import LumigatorClient
from lumigator_schemas.jobs import JobType, JobEvalCreate

lm_client = LumigatorClient("http://localhost:8000")
lm_client.jobs.create_job(JobType.EVALUATION, JobEvalCreate(...))

Parameters:

type (JobType) – The kind of job to create. It can be either EVALUATION or INFERENCE.
request (JobEvalCreate) – The job’s configuration.

Returns:

The information for the newly created job.

Return type:

JobResponse

get_job(id: UUID) → Job

Return information on a specific job.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.jobs.get_job(job_id)

Parameters:: id (UUID) – the ID of the job to retrieve
Returns:: The job information for the provided ID.
Return type:: JobResponse

get_job_download(id: UUID) → JobResultDownloadResponse

Return the download link for the results of a specific job.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.jobs.get_job_download(job_id)

Parameters:

id (str) – The ID of the job download link to retrieve.

Returns:

The job download link for the provided: ID.

Return type:

JobResultDownloadResponse

get_job_result(id: UUID) → JobResultResponse

Return the results of a specific job.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.jobs.get_job_result(job_id)

Parameters:: id (str) – The ID of the job results to retrieve.
Returns:: The job results for the provided ID.
Return type:: JobResultResponse

get_jobs() → ListingResponse[Job]

Return information on all jobs.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.jobs.get_jobs()

Returns:: All existing jobs.
Return type:: ListingResponse[JobResponse]

wait_for_job(id: UUID, retries: int = 180, poll_wait: int = 5) → JobResponse

Wait for a job to succeed and return latest retrieved information.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
job = lm_client.jobs.wait_for_job(job_id)

Parameters:

id (UUID) – The ID of the job to wait for.
retries (int) – The number of times to poll for the job status.
poll_wait (int) – The time to wait between polling attempts.

Returns:

the most recently job information for the ID, when the: job has finished

Return type:

JobResponse

Completions

The Completions class provides a simple interface to request completions from external APIs. Currently, we support two APIs: OpenAI’s and Mistral’s.

class lumigator_sdk.completions.Completions(c: ApiClient)

COMPLETIONS_ROUTE = 'completions'

__init__(c: ApiClient)

Construct a new instance of the Completions class.

Parameters:: c (ApiClient) – The API client to use for requests.
Returns:: A new Completions instance.
Return type:: Completions

get_completion(vendor: str, text: str) → CompletionResponse | None

Return completions from the specified vendor for given prompt.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.completions.get_completion("openai", "Once upon a time")

Parameters:

vendor (str) – The vendor to use for completion.
text (str) – The prompt text to generate completions for.

Returns:

The completion response or None if: the request failed.

Return type:

CompletionResponse | None

get_vendors() → list[str]

Return the list of supported external vendors.

Example

from sdk.lumigator import LumigatorClient

lm_client = LumigatorClient("http://localhost:8000")
lm_client.completions.get_vendors()

Returns:: A list of supported vendors.
Return type:: list[str]

Base Client

The BaseClient class provides a base class for the LumigatorClient. You can use this class to create your own client with custom methods.

class lumigator_sdk.client.ApiClient(api_host: str, ray_host: str, retry_conf: Retry)

__init__(api_host: str, ray_host: str, retry_conf: Retry)

Base class for the Lumigator API client.

Parameters:

api_host (str) – The host of the Lumigator backend API.
ray_host (str) – The host of the Ray cluster.
retry_conf – an optional urllib3 retry strategy

get_ray_job_response(api_path, method=<HTTPMethod.GET>, data=None, files=None, json_data=None, verbose=True) → Response

Make a request to the specified endpoint.

Parameters:

api_path (str) – The path to make the request to.
method (HTTPMethod, optional) – The HTTP method to use. Defaults to HTTPMethod.GET.
data (optional) – Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
files (optional) – Dictionary of {'name': file-like-objects} (or {'name': file-tuple}) for multipart encoding upload. file-tuple can be a 2-tuple ('filename', fileobj), 3-tuple ('filename', fileobj, 'content_type') or a 4-tuple ('filename', fileobj, 'content_type', custom_headers), where content_type is a string defining the content type of the given file and custom_headers a dict-like object containing additional headers to add for the file.
json_data (optional) – A JSON serializable Python object to send in the body of the Request.
verbose (bool, optional) – Whether to log the response. Defaults to True.

Returns:

The response object from the request.

Return type:

requests.Response

Raises:

HTTPError – Raises an exception for any error other than 404 - NOT FOUND.
requests.RequestException – Raises an exception for any other request-related error.

get_response(api_path, method=<HTTPMethod.GET>, data=None, files=None, json_data=None, verbose: bool = True) → Response

Make a request to the specified endpoint.

Parameters:

api_path (str) – The path to make the request to.
method (HTTPMethod, optional) – The HTTP method to use. Defaults to HTTPMethod.GET.
data (optional) – Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
files (optional) – Dictionary of {'name': file-like-objects} (or {'name': file-tuple}) for multipart encoding upload. file-tuple can be a 2-tuple ('filename', fileobj), 3-tuple ('filename', fileobj, 'content_type') or a 4-tuple ('filename', fileobj, 'content_type', custom_headers), where content_type is a string defining the content type of the given file and custom_headers a dict-like object containing additional headers to add for the file.
json_data (optional) – A JSON serializable Python object to send in the body of the Request.
verbose (bool, optional) – Whether to log the response. Defaults to True.

Returns:

The response object from the request.

Return type:

requests.Response

Raises:

HTTPError – Raises an exception for any error other than 404 - NOT FOUND.
requests.RequestException – Raises an exception for any other request error.