From 2e0aeaddefaba1d871918447ecfdd8f4329c5acd Mon Sep 17 00:00:00 2001 From: andf-viam <132301587+andf-viam@users.noreply.github.com> Date: Wed, 26 Jun 2024 18:04:33 -0400 Subject: [PATCH] DOCS-2428: Merge autogen: bill,mltrain (#3038) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> --- .github/workflows/sdk_protos_map.csv | 6 +- .github/workflows/update_sdk_methods.py | 1 - docs/appendix/apis/_index.md | 4 +- docs/appendix/apis/billing-client.md | 105 +----------- docs/appendix/apis/ml-training-client.md | 143 +--------------- .../app/apis/generated/billing-table.md | 7 + static/include/app/apis/generated/billing.md | 112 +++++++++++++ .../app/apis/generated/mltraining-table.md | 8 + .../include/app/apis/generated/mltraining.md | 152 ++++++++++++++++++ ...ython.mltraining.cancel_training_job.id.md | 1 + ...training.submit_training_job.dataset_id.md | 2 + ...training.submit_training_job.model_type.md | 2 + ...ining.submit_training_job.model_version.md | 2 + ...n.mltraining.submit_training_job.org_id.md | 2 + 14 files changed, 296 insertions(+), 251 deletions(-) create mode 100644 static/include/app/apis/generated/billing-table.md create mode 100644 static/include/app/apis/generated/billing.md create mode 100644 static/include/app/apis/generated/mltraining-table.md create mode 100644 static/include/app/apis/generated/mltraining.md create mode 100644 static/include/app/apis/overrides/methods/python.mltraining.cancel_training_job.id.md create mode 100644 static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.dataset_id.md create mode 100644 static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.model_type.md create mode 100644 static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.model_version.md create mode 100644 static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.org_id.md diff --git a/.github/workflows/sdk_protos_map.csv b/.github/workflows/sdk_protos_map.csv index cdcacc411e..7a6146f2e1 100644 --- a/.github/workflows/sdk_protos_map.csv +++ b/.github/workflows/sdk_protos_map.csv @@ -419,13 +419,11 @@ data_sync,FileUploadFromPath,file_upload_from_path,, data_sync,StreamingDataCaptureUpload,streaming_data_capture_upload,, ## MLTraining -## TODO: Something wrong with parsing: submit_training_job in PySDK (??): -mltraining,SubmitTrainingJob,,, +mltraining,SubmitTrainingJob,submit_training_job,, mltraining,GetTrainingJob,get_training_job,, mltraining,ListTrainingJobs,list_training_jobs,, mltraining,CancelTrainingJob,cancel_training_job,, -## Borked in Python: https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.delete_completed_training_job -mltraining,DeleteCompletedTrainingJob,,, +mltraining,DeleteCompletedTrainingJob,delete_completed_training_job,, ## Robot ## Omitting some Flutter methods from now until we can determine what they do diff --git a/.github/workflows/update_sdk_methods.py b/.github/workflows/update_sdk_methods.py index 2979530b8b..06e976c99e 100755 --- a/.github/workflows/update_sdk_methods.py +++ b/.github/workflows/update_sdk_methods.py @@ -388,7 +388,6 @@ 'viam.app.data_client.DataClient.configure_database_user', # unimplemented 'viam.app.data_client.DataClient.create_filter', # deprecated 'viam.app.data_client.DataClient.delete_tabular_data_by_filter', # deprecated - 'viam.app.ml_training_client.MLTrainingClient.submit_training_job', # unimplemented 'viam.components.input.client.ControllerClient.reset_channel', # GUESS ? 'viam.robot.client.RobotClient.transform_point_cloud', # unimplemented 'viam.robot.client.RobotClient.get_component', # GUESS ? diff --git a/docs/appendix/apis/_index.md b/docs/appendix/apis/_index.md index 2a96331d3c..bbfce3d401 100644 --- a/docs/appendix/apis/_index.md +++ b/docs/appendix/apis/_index.md @@ -44,13 +44,13 @@ The [data client API](/appendix/apis/data-client/) supports the following method The ML training API allows you to get information about and cancel ML training jobs taking place on the [Viam app](https://app.viam.com): -{{< readfile "/static/include/services/apis/ml-training-client.md" >}} +{{< readfile "/static/include/app/apis/generated/mltraining-table.md" >}} ### Billing client API The [billing client API](/appendix/apis/billing-client/) supports the following methods to retrieve billing information from the [Viam app](https://app.viam.com): -{{< readfile "/static/include/services/apis/billing-client.md" >}} +{{< readfile "/static/include/app/apis/generated/billing-table.md" >}} ## Component APIs diff --git a/docs/appendix/apis/billing-client.md b/docs/appendix/apis/billing-client.md index f401070523..6e7f2e97c2 100644 --- a/docs/appendix/apis/billing-client.md +++ b/docs/appendix/apis/billing-client.md @@ -71,107 +71,6 @@ Once you have instantiated a `BillingClient`, you can run [API methods](#api) ag The billing client API supports the following methods: -{{< readfile "/static/include/services/apis/billing-client.md" >}} +{{< readfile "/static/include/app/apis/generated/billing-table.md" >}} -### GetCurrentMonthUsage - -Access data usage information for the current month for a given organization. -You can also find your usage data on the [**Payment and billing** page](/billing/). - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- org_id ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): the ID of the organization to request usage data for - -**Returns:** - -- ([viam.proto.app.billing.GetCurrentMonthUsageResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetCurrentMonthUsageResponse)): Current month usage information - -```python {class="line-numbers linkable-line-numbers"} -usage = await viam_client.billing_client.get_current_month_usage("") -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_current_month_usage). - -{{% /tab %}} -{{< /tabs >}} - -### GetInvoicePdf - -Access invoice PDF data and optionally save it to a provided file path. -You can also find your invoices on the [**Payment and billing** page](/billing/). - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `invoice_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): the ID of the invoice being requested -- `org_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): the ID of the org to request data from -- `dest` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): filepath to save the invoice to - -**Returns:** - -- None. - -```python {class="line-numbers linkable-line-numbers"} -await viam_client.billing_client.get_invoice_pdf( - "", "", "") -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_invoice_pdf). - -{{% /tab %}} -{{< /tabs >}} - -### GetInvoicesSummary - -Access total outstanding balance plus invoice summaries for a given org. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- org_id ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): the ID of the org to request data for - -**Returns:** - -- ([viam.proto.app.billing.GetInvoicesSummaryResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetInvoicesSummaryResponse)): Summary of org invoices - -```python {class="line-numbers linkable-line-numbers"} -summary = await viam_client.billing_client.get_invoices_summary("") -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_invoices_summary). - -{{% /tab %}} -{{< /tabs >}} - -### GetOrgBillingInformation - -Access billing information (payment method, billing tier, etc.) for a given org. -You can also find this information on the [**Payment and billing** page](/billing/). - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- org_id (str): the ID of the org to request data for - -**Returns:** - -- ([viam.proto.app.billing.GetOrgBillingInformationResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetOrgBillingInformationResponse)): The org billing information - -```python {class="line-numbers linkable-line-numbers"} -information = await viam_client.billing_client.get_org_billing_information( - "") -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_org_billing_information). - -{{% /tab %}} -{{< /tabs >}} +{{< readfile "/static/include/app/apis/generated/billing.md" >}} diff --git a/docs/appendix/apis/ml-training-client.md b/docs/appendix/apis/ml-training-client.md index f8fb056605..f6940355da 100644 --- a/docs/appendix/apis/ml-training-client.md +++ b/docs/appendix/apis/ml-training-client.md @@ -67,145 +67,6 @@ Once you have instantiated an `MLTrainingClient`, you can run the following [API The ML training client API supports the following methods: -{{< readfile "/static/include/services/apis/ml-training-client.md" >}} +{{< readfile "/static/include/app/apis/generated/mltraining-table.md" >}} -### GetTrainingJob - -Get training job metadata. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `id` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the training job you wish to get metadata from. Retrieve this value with [`ListTrainingJobs()`](#listtrainingjobs). - -**Returns**: - -- [(TrainingJobMetadata)](https://python.viam.dev/autoapi/viam/proto/app/mltraining/index.html#viam.proto.app.mltraining.TrainingJobMetadata): Training job metadata, including status, last modified timestamp, id, and more. - -```python {class="line-numbers linkable-line-numbers"} -job_metadata = await ml_training_client.get_training_job( - id="INSERT YOUR JOB ID") -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.get_training_job). - -{{% /tab %}} -{{< /tabs >}} - -### ListTrainingJobs - -Get training job metadata for all jobs within an organization. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `org_id` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The ID of your organization to request training job metadata from. Retrieve this value with the fleet management API's [`ListOrganizations()`](/appendix/apis/fleet/#listorganizations). -- `training_status` [(Optional[TrainingStatus.ValueType])](https://python.viam.dev/autoapi/viam/gen/app/mltraining/v1/ml_training_pb2/index.html#viam.gen.app.mltraining.v1.ml_training_pb2.TrainingStatus): The status of training jobs you want to filter the list by. If you leave this unspecified, all training jobs for your organization are returned. - -**Returns**: - -- [(List[TrainingJobMetadata])](https://python.viam.dev/autoapi/viam/proto/app/mltraining/index.html#viam.proto.app.mltraining.TrainingJobMetadata): A list of training job metadata, including status, last modified timestamp, id, and more. - -```python {class="line-numbers linkable-line-numbers"} -jobs_metadata = await ml_training_client.list_training_jobs( - org_id="INSERT YOUR ORG ID") - -first_job_id = jobs_metadata[1].id -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.list_training_jobs). - -{{% /tab %}} -{{< /tabs >}} - -### SubmitTrainingJob - -Submit a training job. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `org_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The ID of the organization to submit the training job to. To retrieve this, expand your organization's dropdown in the top right corner of the [Viam app](https://app.viam.com/), select **Settings**, and copy **Organization ID**. -- `dataset_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The ID of the dataset to train the ML model on. To retrieve this, navigate to your dataset's page in the [Viam app](https://app.viam.com/data/datasets), click **...** in the left-hand menu, and click **Copy dataset ID**. -- `model_name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the ML model you wish to train. -- `model_version` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The version of the ML model you're training. This string must be unique from any previous versions you've set. -- `model_type` ([ModelType.ValueType](https://python.viam.dev/autoapi/viam/gen/app/mltraining/v1/ml_training_pb2/index.html#viam.gen.app.mltraining.v1.ml_training_pb2.ModelType)) (required): The type of the ML model. Options: `ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION`, `ModelType.MODEL_TYPE_MULTI_LABEL_CLASSIFICATION`, `ModelType.MODEL_TYPE_OBJECT_DETECTION`. -- `tags` ([List(str)](https://docs.python.org/3/library/stdtypes.html#typesseq-list)) (required): The labels to train on. - -**Returns:** - -- ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): The ID of the training job created. - -```python {class="line-numbers linkable-line-numbers"} -job_id = await ml_training_client.submit_training_job( - "3988fd7d-b1c0-4f36-9842-0c666f374d3c", - "66491a0666a6c8aa4a33e43e", - "your-model-name", - "1", - "ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION", - tags) -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.submit_training_job). - -{{% /tab %}} -{{% tab name="Flutter" %}} - -**Parameters:** - -- `datasetId` [(String)](https://api.flutter.dev/flutter/dart-core/String-class.html) (required): The ID of the dataset to train the ML model on. To retrieve this, navigate to your dataset's page in the [Viam app](https://app.viam.com/data/datasets), click **...** in the left-hand menu, and click **Copy dataset ID**. -- `modelName` [(String)](https://api.flutter.dev/flutter/dart-core/String-class.html) (required): The name of the ML model to train. -- `modelType` [(ModelType)](https://flutter.viam.dev/viam_protos.app.ml_training/ModelType-class.html) (required): The type of the ML model. Options: `MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION`, `MODEL_TYPE_MULTI_LABEL_CLASSIFICATION`, or `MODEL_TYPE_OBJECT_DETECTION`. -- `modelVersion` [(String)](https://api.flutter.dev/flutter/dart-core/String-class.html) (required): The version of the ML model you're training. This string must be unique from any previous versions you've set. -- `organizationId` [(String)](https://api.flutter.dev/flutter/dart-core/String-class.html) (required): The ID of the organization to submit the training job to. To retrieve this, expand your organization's dropdown in the top right corner of the [Viam app](https://app.viam.com/), select **Settings**, and copy **Organization ID**. -- `tags` [(List)](https://api.flutter.dev/flutter/dart-core/List-class.html)<[String](https://api.flutter.dev/flutter/dart-core/String-class.html)> (required): The labels to train on. - -**Returns:** - -- [(String)](https://api.flutter.dev/flutter/dart-core/String-class.html) (required): The ID of the training job created. - -```dart {class="line-numbers linkable-line-numbers"} -final tags = ['A', 'B', 'C']; // Creates list of tags. - -String jobID = ml_training.submitTrainingJob("66491a0666a6c8aa4a33e43e", "your-model-name", "MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION", "1", "3988fd7d-b1c0-4f36-9842-0c666f374d3c", tags); -``` - -For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_protos.app.ml_training/MLTrainingServiceClient/submitTrainingJob.html). - -{{% /tab %}} -{{< /tabs >}} - -### CancelTrainingJob - -Cancel the specified training job. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `id` [(str)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the training job you wish to get metadata from. Retrieve this value with [`ListTrainingJobs()`](#listtrainingjobs). - -**Returns**: - -- None - -**Raises**: - -- `GRPCError`: If no training job exists with the given ID or cancellation was otherwise unsuccessful. - -```python {class="line-numbers linkable-line-numbers"} -await ml_training_client.cancel_training_job( - id="INSERT YOUR JOB ID") -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.cancel_training_job). - -{{% /tab %}} -{{< /tabs >}} +{{< readfile "/static/include/app/apis/generated/mltraining.md" >}} diff --git a/static/include/app/apis/generated/billing-table.md b/static/include/app/apis/generated/billing-table.md new file mode 100644 index 0000000000..dfe394e5d5 --- /dev/null +++ b/static/include/app/apis/generated/billing-table.md @@ -0,0 +1,7 @@ + +| Method Name | Description | +| ----------- | ----------- | +| [`GetCurrentMonthUsage`](/appendix/apis/billing-client/#getcurrentmonthusage) | Access data usage information for the current month for a given organization. | +| [`GetOrgBillingInformation`](/appendix/apis/billing-client/#getorgbillinginformation) | Access billing information (payment method, billing tier, etc.) for a given org. | +| [`GetInvoicesSummary`](/appendix/apis/billing-client/#getinvoicessummary) | Access total outstanding balance plus invoice summaries for a given org. | +| [`GetInvoicePdf`](/appendix/apis/billing-client/#getinvoicepdf) | Access invoice PDF data and optionally save it to a provided file path. | diff --git a/static/include/app/apis/generated/billing.md b/static/include/app/apis/generated/billing.md new file mode 100644 index 0000000000..42d1509412 --- /dev/null +++ b/static/include/app/apis/generated/billing.md @@ -0,0 +1,112 @@ +### GetCurrentMonthUsage + +Access data usage information for the current month for a given organization. +You can also find your usage data on the [**Payment and billing** page](/billing/). + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `org_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the organization to request usage data for. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([viam.proto.app.billing.GetCurrentMonthUsageResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetCurrentMonthUsageResponse)): Current month usage information. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +usage = await viam_client.billing_client.get_current_month_usage("") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_current_month_usage). + +{{% /tab %}} +{{< /tabs >}} + +### GetOrgBillingInformation + +Access billing information (payment method, billing tier, etc.) for a given org. +You can also find this information on the [**Payment and billing** page](/billing/). + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `org_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the org to request data for. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([viam.proto.app.billing.GetOrgBillingInformationResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetOrgBillingInformationResponse)): The org billing information. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +information = await viam_client.billing_client.get_org_billing_information("") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_org_billing_information). + +{{% /tab %}} +{{< /tabs >}} + +### GetInvoicesSummary + +Access total outstanding balance plus invoice summaries for a given org. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `org_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the org to request data for. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([viam.proto.app.billing.GetInvoicesSummaryResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetInvoicesSummaryResponse)): Summary of org invoices. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +summary = await viam_client.billing_client.get_invoices_summary("") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_invoices_summary). + +{{% /tab %}} +{{< /tabs >}} + +### GetInvoicePdf + +Access invoice PDF data and optionally save it to a provided file path. +You can also find your invoices on the [**Payment and billing** page](/billing/). + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `invoice_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the invoice being requested. +- `org_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the org to request data from. +- `dest` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): filepath to save the invoice to. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- None. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +await viam_client.billing_client.get_invoice_pdf("", "", "") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_invoice_pdf). + +{{% /tab %}} +{{< /tabs >}} diff --git a/static/include/app/apis/generated/mltraining-table.md b/static/include/app/apis/generated/mltraining-table.md new file mode 100644 index 0000000000..3abbb860bd --- /dev/null +++ b/static/include/app/apis/generated/mltraining-table.md @@ -0,0 +1,8 @@ + +| Method Name | Description | +| ----------- | ----------- | +| [`SubmitTrainingJob`](/appendix/apis/ml-training-client/#submittrainingjob) | Submit a training job. | +| [`GetTrainingJob`](/appendix/apis/ml-training-client/#gettrainingjob) | Get training job metadata. | +| [`ListTrainingJobs`](/appendix/apis/ml-training-client/#listtrainingjobs) | Get training job metadata for all jobs within an organization. | +| [`CancelTrainingJob`](/appendix/apis/ml-training-client/#canceltrainingjob) | Cancel the specified training job. | +| [`DeleteCompletedTrainingJob`](/appendix/apis/ml-training-client/#deletecompletedtrainingjob) | Delete a completed training job from the database, whether the job succeeded or failed. | diff --git a/static/include/app/apis/generated/mltraining.md b/static/include/app/apis/generated/mltraining.md new file mode 100644 index 0000000000..7699dfa3bb --- /dev/null +++ b/static/include/app/apis/generated/mltraining.md @@ -0,0 +1,152 @@ +### SubmitTrainingJob + +Submit a training job. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `org_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The ID of the organization to submit the training job to. To retrieve this, expand your organization's dropdown in the top right corner of the [Viam app](https://app.viam.com/), select **Settings**, and copy **Organization ID**. +- `dataset_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The ID of the dataset to train the ML model on. To retrieve this, navigate to your dataset's page in the [Viam app](https://app.viam.com/data/datasets), click **...** in the left-hand menu, and click **Copy dataset ID**. +- `model_name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the model name. +- `model_version` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The version of the ML model you're training. This string must be unique from any previous versions you've set. +- `model_type` (viam.proto.app.mltraining.ModelType.ValueType) (required): The type of the ML model. Options: `ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION`, `ModelType.MODEL_TYPE_MULTI_LABEL_CLASSIFICATION`, `ModelType.MODEL_TYPE_OBJECT_DETECTION`. +- `tags` (List[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)]) (required): the tags. + +**Returns:** + +- ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): the id of the training job. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +job_id = await ml_training_client.submit_training_job( + organization_id=organization_id, + dataset_id=dataset_id, + model_name="your-model-name", + model_version="1", + model_type="ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION", + tags=tags +) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.submit_training_job). + +{{% /tab %}} +{{< /tabs >}} + +### GetTrainingJob + +Get training job metadata. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the id of the requested training job. + +**Returns:** + +- ([viam.proto.app.mltraining.TrainingJobMetadata](https://python.viam.dev/autoapi/viam/proto/app/mltraining/index.html#viam.proto.app.mltraining.TrainingJobMetadata)): training job data. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +job_metadata = await ml_training_client.get_training_job( + id="INSERT YOUR JOB ID") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.get_training_job). + +{{% /tab %}} +{{< /tabs >}} + +### ListTrainingJobs + +Get training job metadata for all jobs within an organization. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `org_id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the id of the org to request training job data from. +- `training_status` ([viam.proto.app.mltraining.TrainingStatus.ValueType](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.TrainingStatus)) (optional): status of training jobs to filter the list by. If unspecified, all training jobs will be returned. + +**Returns:** + +- ([List[viam.proto.app.mltraining.TrainingJobMetadata]](https://python.viam.dev/autoapi/viam/proto/app/mltraining/index.html#viam.proto.app.mltraining.TrainingJobMetadata)): a list of training job data. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +jobs_metadata = await ml_training_client.list_training_jobs( + org_id="INSERT YOUR ORG ID") + +first_job_id = jobs_metadata[1].id +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.list_training_jobs). + +{{% /tab %}} +{{< /tabs >}} + +### CancelTrainingJob + +Cancel the specified training job. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): ID of the training job you wish to get metadata from. Retrieve this value with [`ListTrainingJobs()`](#listtrainingjobs). + +**Returns:** + +- None. + +**Raises:** + +- (GRPCError): if no training job exists with the given id. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +await ml_training_client.cancel_training_job( + id="INSERT YOUR JOB ID") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.cancel_training_job). + +{{% /tab %}} +{{< /tabs >}} + +### DeleteCompletedTrainingJob + +Delete a completed training job from the database, whether the job succeeded or failed. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the id of the training job. + +**Returns:** + +- None. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +await ml_training_client.delete_completed_training_job( + id="INSERT YOUR JOB ID") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.delete_completed_training_job). + +{{% /tab %}} +{{< /tabs >}} diff --git a/static/include/app/apis/overrides/methods/python.mltraining.cancel_training_job.id.md b/static/include/app/apis/overrides/methods/python.mltraining.cancel_training_job.id.md new file mode 100644 index 0000000000..b7212c0423 --- /dev/null +++ b/static/include/app/apis/overrides/methods/python.mltraining.cancel_training_job.id.md @@ -0,0 +1 @@ +ID of the training job you wish to get metadata from. Retrieve this value with [`ListTrainingJobs()`](#listtrainingjobs). diff --git a/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.dataset_id.md b/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.dataset_id.md new file mode 100644 index 0000000000..b133fae6d7 --- /dev/null +++ b/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.dataset_id.md @@ -0,0 +1,2 @@ +The ID of the dataset to train the ML model on. +To retrieve this, navigate to your dataset's page in the [Viam app](https://app.viam.com/data/datasets), click **...** in the left-hand menu, and click **Copy dataset ID**. diff --git a/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.model_type.md b/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.model_type.md new file mode 100644 index 0000000000..ac5f4565a8 --- /dev/null +++ b/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.model_type.md @@ -0,0 +1,2 @@ +The type of the ML model. +Options: `ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION`, `ModelType.MODEL_TYPE_MULTI_LABEL_CLASSIFICATION`, `ModelType.MODEL_TYPE_OBJECT_DETECTION`. diff --git a/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.model_version.md b/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.model_version.md new file mode 100644 index 0000000000..ec73c74d6f --- /dev/null +++ b/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.model_version.md @@ -0,0 +1,2 @@ +The version of the ML model you're training. +This string must be unique from any previous versions you've set. diff --git a/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.org_id.md b/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.org_id.md new file mode 100644 index 0000000000..4ba99cda22 --- /dev/null +++ b/static/include/app/apis/overrides/methods/python.mltraining.submit_training_job.org_id.md @@ -0,0 +1,2 @@ +The ID of the organization to submit the training job to. +To retrieve this, expand your organization's dropdown in the top right corner of the [Viam app](https://app.viam.com/), select **Settings**, and copy **Organization ID**.