Package: teradatamodelops
Teradata ModelOps ClientInstallationCLISDKRelease NotesInstallationThe teradatamodelops is available frompypipipinstallteradatamodelopsNote: previously Teradata ModelOps was known as AnalyticsOps Accelerator (AOA), so you might encounter mentions of AOA or aoa, it's referring to an older version of ModelOpsCLIconfigurationBy default, the CLI looks for configuration stored in~/.aoa/config.yaml. Copy the config from ModelOps UI -> Session Details -> CLI Config. This will provide the command to create or update theconfig.yaml. If required, one can override this configuration at runtime by specifying environment variables (seeapi_client.py)helpThe cli can be used to perform a number of interactions and guides the user to perform those actions.>tmo-h
usage:tmo[-h][--debug][--version]{list,add,run,init,clone,link,connection,feature,doctor}...

TMOCLI

optionalarguments:-h,--helpshowthishelpmessageandexit--debugEnabledebuglogging--versionDisplaytheversionofthistool

actions:validactions{list,add,run,init,clone,link,connection,feature,doctor}listListprojects,models,localmodelsordatasetsaddAddmodeltoworkingdirrunTrainandEvaluatemodellocallyinitInitializemodeldirectorywithbasicstructurecloneCloneProjectRepositorylinkLinklocalrepotoprojectconnectionManagelocalconnectionsfeatureManagefeaturestatisticsdoctorDiagnoseconfigurationissuescloneTheclonecommand provides a convenient way to perform a git clone of the repository associated with a given project. The command can be run interactively and will allow you to select the project you wish to clone. Note that by default it clones to the current working directory so you either need to make sure you create an empty folder and run it from within there or else provide the--pathargument.>tmoclone-h
usage:tmoclone[-h][--debug][-idPROJECT_ID][-pPATH]optionalarguments:-h,--helpshowthishelpmessageandexit--debugEnabledebuglogging-idPROJECT_ID,--project-idPROJECT_IDIdofProjecttoclone-pPATH,--pathPATHPathtoclonerepositorytoinitWhen you create a git repository, its empty by default. Theinitcommand allows you to initialize the repository with the structure required by the AOA. It also adds a default README.md and HOWTO.md.>tmoinit-h
usage:tmoinit[-h][--debug]optionalarguments:-h,--helpshowthishelpmessageandexit--debugEnabledebuglogginglistAllows to list the aoa resources. In the cases of listing models (pushed / committed) and datasets, it will prompt the user to select a project prior showing the results. In the case of local models, it lists both committed and non-committed models.>tmolist-h
usage:tmolist[-h][--debug][-p][-m][-lm][-t][-d][-c]optionalarguments:-h,--helpshowthishelpmessageandexit--debugEnabledebuglogging-p,--projectsListprojects-m,--modelsListregisteredmodels(committed/pushed)-lm,--local-modelsListlocalmodels.Includesregisteredandnon-registered(non-committed/non-pushed)-t,--templatesListdatasettemplates-d,--datasetsListdatasets-c,--connectionsListlocalconnectionsAll results are shown in the format[index] (id of the resource) namefor example:List of models for project Demo:
--------------------------------
[0] (03c9a01f-bd46-4e7c-9a60-4282039094e6) Diabetes Prediction
[1] (74eca506-e967-48f1-92ad-fb217b07e181) IMDB Sentiment AnalysisaddAdd a new model to a given repository based on a model template. A model in any other existing ModelOps git repository (specified via the-t <giturl>) can be used.>tmoadd-h
usage:tmoadd[-h][--debug]-tTEMPLATE_URL-bBRANCH

optionalarguments:-h,--helpshowthishelpmessageandexit--debugEnabledebuglogging-tTEMPLATE_URL,--template-urlTEMPLATE_URLGitURLfortemplaterepository-bBRANCH,--branchBRANCHGitbranchtopulltemplates(defaultismain)Example usage>tmoadd-thttps://github.com/Teradata/modelops-demo-models-bmasterrunThe cli can be used to validate the model training and evaluation logic locally before committing to git. This simplifies the development lifecycle and allows you to test and validate many options. It also enables you to avoid creating the dataset definitions in the AOA UI until you are ready and have a finalised version.>tmorun-h
usage:tmorun[-h][--debug][-idMODEL_ID][-mMODE][-dDATASET_ID][-tDATASET_TEMPLATE_ID][-ldLOCAL_DATASET][-ltLOCAL_DATASET_TEMPLATE][-cCONNECTION]optionalarguments:-h,--helpshowthishelpmessageandexit--debugEnabledebuglogging-idMODEL_ID,--model-idMODEL_IDIdofmodel-mMODE,--modeMODEMode(trainorevaluate)-dDATASET_ID,--dataset-idDATASET_IDRemotedatasetId-tDATASET_TEMPLATE_ID,--dataset-template-idDATASET_TEMPLATE_IDRemotedatasetTemplateId-ldLOCAL_DATASET,--local-datasetLOCAL_DATASETPathtolocaldatasetmetadatafile-ltLOCAL_DATASET_TEMPLATE,--local-dataset-templateLOCAL_DATASET_TEMPLATEPathtolocaldatasettemplatemetadatafile-cCONNECTION,--connectionCONNECTIONLocalconnectionidYou can run all of this as a single command or interactively by selecting some optional arguments, or none of them.For example, if you want to run the cli interactively you just selecttmo runbut if you wanted to run it non interactively to train a given model with a given datasetId you would expect>tmorun-id<modelId>-m<mode>-d<datasetId>connectionThe connection credentials stored in the ModelOps service cannot be accessed remotely through the CLI for security reasons. Instead, users can manage connection information locally for the CLI. These connections are used by other CLI commands which access Vantage.>tmoconnection-h
usage:tmoconnection[-h]{list,add,remove,export,test,create-byom-table}...

optionalarguments:-h,--helpshowthishelpmessageandexitactions:validactions{list,add,remove,export,test,create-byom-table}listListalllocalconnectionsaddAddalocalconnectionremoveRemovealocalconnectionexportExportalocalconnectiontobeusedasashellscripttestTestalocalconnectioncreate-byom-tableCreateatabletostoreBYOMmodelsfeatureManage feature metadata by creating and populating feature metadata table(s). The feature metadata tables contain information required when computing statistics during training, scoring etc. This metadata depends on the feature type (categorical or continuous).As this metadata can contain sensitive profiling information (such as categories), it is recommended to treat this metadata in the same manner as you treat the features for a given use case. That is, the feature metadata should live in a project or use case level database.>tmofeature-h
usage:tmofeature[-h]{compute-stats,list-stats,create-stats-table,import-stats}...

optionalarguments:-h,--helpshowthishelpmessageandexitaction:validactions{compute-stats,list-stats,create-stats-table,import-stats}compute-statsComputefeaturestatisticslist-statsListavailablestatisticscreate-stats-tableCreatestatisticstableimport-statsImportcolumnstatisticsfromlocalJSONfiletmo feature compute metadataCompute the feature metadata information required when computing statistics during training, scoring etc. This metadata depends on the feature type (categorical or continuous).Continuous: the histograms edgesCategorical: the categories>tmofeaturecompute-stats-h
usage:tmofeaturecompute-stats[-h][--debug]-sSOURCE_TABLE-mMETADATA_TABLE[-t{continuous,categorical}]-cCOLUMNS

optionalarguments:-h,--helpshowthishelpmessageandexit--debugEnabledebuglogging-sSOURCE_TABLE,--source-tableSOURCE_TABLEFeaturesourcetable/view-mMETADATA_TABLE,--metadata-tableMETADATA_TABLEMetadatatableforfeaturestats,includingdatabasename-t{continuous,categorical},--feature-type{continuous,categorical}Featuretype:continuousorcategorical(defaultiscontinuous)-cCOLUMNS,--columnsCOLUMNSListoffeaturecolumnsExample usagetmofeaturecompute-stats\-s<feature-db>.<feature-data>\-m<feature-metadata-db>.<feature-metadata-table>\-tcontinuous-cnumtimesprg,plglcconc,bloodp,skinthick,twohourserins,bmi,dipedfunc,ageAuthenticationA number of authentication methods are supported for both the CLI and SDK.device_code (interactive)client_credentials (service-service)bearer (raw bearer token)When working interactively, the recommended auth method for the CLI isdevice_code. It will guide you through the auth automatically. For the SDK, usebearerif working interactively.
For both CLI and SDK, if working in an automated service-service manner, useclient_credentials.SDKThe SDK for ModelOps allows users to interact with ModelOps APIs from anywhere they can execute python such as notebooks, IDEs etc. It can also be used for devops to automate additional parts of the process and integrate into the wider organization.Create ClientBy default, creating an instance of theAoaClientlooks for configuration stored in~/.aoa/config.yaml. When working with the SDK, we recommend that you specify (and override) all the necessary configuration as part of theAoaClientinvocation.An example to create a client using a bearer token for a given project isfromaoaimportAoaClientclient=AoaClient(aoa_url="<modelops-endpoint>",auth_mode="bearer",auth_bearer="<bearer-token>",project_id="23e1df4b-b630-47a1-ab80-7ad5385fcd8d",)To get the values to use for bearer token and aoa_url, go to the ModelOps UI -> Session Details -> SDK Config.Read EntitiesWe provide an extensive sdk implementation to interact with the APIs. You can find, create, update, archive, etc any entity that supports it via the SDK. In addition, most if not all search endpoints are also implemented in the sdk. Here are some examplesfromaoaimportAoaClient,DatasetApi,JobApiimportpprintclient=AoaClient(project_id="23e1df4b-b630-47a1-ab80-7ad5385fcd8d")dataset_api=DatasetApi(aoa_client=client)datasets=dataset_api.find_all()pprint.pprint(datasets)dataset=dataset_api.find_by_id("11e1df4b-b630-47a1-ab80-7ad5385fcd8c")pprint.pprint(dataset)job_api=JobApi(aoa_client=client)jobs=job_api.find_by_id("21e1df4b-b630-47a1-ab80-7ad5385fcd1c")pprint.pprint(jobs)Deploy Model VersionLet's assume we have a model version4131df4b-b630-47a1-ab80-7ad5385fcd15which we want to deploy In-Vantage and schedule it to execute once a month at midnight of the first day of the month using dataset connection11e1df4b-b630-47a1-ab80-7ad5385fcd8cand dataset templated8a35d98-21ce-47d0-b9f2-00d355777de1. We can use the SDK as follows to perform this.fromaoaimportAoaClient,TrainedModelApi,JobApiclient=AoaClient(project_id="23e1df4b-b630-47a1-ab80-7ad5385fcd8d")trained_model_api=TrainedModelApi(aoa_client=client)job_api=JobApi(aoa_client=client)trained_model_id="4131df4b-b630-47a1-ab80-7ad5385fcd15"deploy_request={"engineType":"IN_VANTAGE","publishOnly":False,"language":"PMML","cron":"0 0 1 * *","byomModelLocation":{"database":"<db-name>","table":"<table-name>"},"datasetConnectionId":"11e1df4b-b630-47a1-ab80-7ad5385fcd8c","datasetTemplateId":"d8a35d98-21ce-47d0-b9f2-00d355777de1","engineTypeConfig":{"dockerImage":"","engine":"byom","resources":{"memory":"1G","cpu":"1"}}}job=trained_model_api.deploy(trained_model_id,deploy_request)# wait until the job completes (if the job fails it will raise an exception)job_api.wait(job['id'])Import Model VersionLet's assume we have a PMML model which we have trained in another data science platform. We want to import the artefacts for this version (model.pmml and data_stats.json) against a BYOM modelf937b5d8-02c6-5150-80c7-1e4ff07fea31.fromaoaimport(AoaClient,ModelApi,TrainedModelApi,TrainedModelArtefactsApi,JobApi)importuuidclient=AoaClient(project_id="23e1df4b-b630-47a1-ab80-7ad5385fcd8d")model_api=ModelApi(aoa_client=client)trained_model_api=TrainedModelApi(aoa_client=client)trained_model_artefacts_api=TrainedModelArtefactsApi(aoa_client=client)job_api=JobApi(aoa_client=client)artefacts_import_id=uuid.uuid4()artefacts=["model.pmml","data_stats.json"]# first, upload the artefacts which we want to associate with the BYOM model versiontrained_model_artefacts_api.upload_artefacts(artefacts_import_id,artefacts)import_request={"artefactImportId":str(artefacts_import_id),"externalId":"my-byom-version-id"}# update with id of your modelmodel_id="<model-uuid>"job=model_api.import_byom(model_id,import_request)# wait until the job completes (if the job fails it will raise an exception)job_api.wait(job["id"])# now you can list the artefacts which were uploaded and linked to the model versiontrained_model_id=job["metadata"]["trainedModel"]["id"]artefacts=trained_model_artefacts_api.list_artefacts(trained_model_id)Release Notes7.0.5WARNINGPlease recreate statistics metadata if you are using this version. It will produce more accurate results and correct behaviour.Fixed computing statistics metadata for continuous features with all NULLsFixed training/eval/scoring statistics on columns with all NULLsAdded a workaround for VAL Histograms failure due to SP argument being longer than 31000 charactersRounding all Decimal and Float bin edges to Teradata-supported FLOAT literals (15 digits max)Fixed CLI error computing continuous statistics metadata related to mixed case column names7.0.4WARNINGPlease recreate statistics metadata if you are using this version. It will produce more accurate results and correct behaviour.Fixed STO helper functions to pick up correct python environmentComputing statistics metadata:Allow less than 10 bins for continuous integer featuresIgnore continuous features that have single value for all rowsAllow different precision for decimal and float continuous featuresFix a bug with repeating edges for decimal/float continuous featuresUsing rounded edges for integer continuous featuresIgnore NULLs for categorical featuresIgnore categorical features that have NULL value for all rowsAllow collecting training statistics without providing a target (unsupervised learning)Report right and left outliers when computing statistics on continuous featuresAllow collecting training/evaluation/scoring statistics when statistics metadata is missing for some columns (missing columns are reported in data_stats.json)For categorical features, report outlier categories in "unmonitored_frequency"Assume statistics metadata is empty, in case it could not be read from the databaseMinor fixes and improvements7.0.3Fixed statistics computation for symmetric distributionsAdded automatic retry for device_code expired session or refresh token7.0.2Updated dependencies7.0.1Updates to new nameChanges to support both 1.x and 2.x version of SQLAlchemyAdded a command to create BYOM tableVarious quality of life and performance improvements7.0.0.0Refactor: Refactor data statistics API / internals to be simpler (breaking changes)Feature: Switch CLI authentication to usedevice_codegrant flowFeature: Add raw Bearer token support for authentication (SDK)6.1.4Feature: Document user facing stats functionsFeature: Improve end user error messaging related to statsBug: Fixaoa initandaoa addnot working due to refactor in 6.1.36.1.3Feature: Improve error messages for statistics calculations and validationFeature: Useaiafor AIA chasing for missing intermediate certificatesBug: No defaults for set when BYOM and VAL DBs not configured on connectionsBug: Fixed requirement versions to ensure more stability across python versionsBug: Fixed slow CLI for some commands due to repeated server initialization6.1.2Bug: Work around problems with special character in passwords for teradataml6.1.0Cleanup: Remove all non OAuth2 (JWT) authentication methodsCleanup: Removeaoa configureFeature: Improve error messages to user on CLIFeature: Addaoa linkfor linking project to repo locallyBug: Don't show archived datasetsBug: Fix issue withaoa feature create-table6.0.0Feature: Support API changes on ModelOps 06.00Feature: CLI DX improvementsFeature: Add Telemetry query bands to sessionFeature:aoa featuresupport for managing feature metadataFeature:aoa adduses reference git repository for model templatesFeature: Improve DX from Notebooks5.0.0Feature: Add simpler teradataml context creation via aoa_create_contextFeature: Add database to connectionsFeature: Support for human-readable model folder namesFeature: Improve UX of aoa runFeature: Improved error messages for users related to auth and configureRefactor: Package refactor of aoa.sto.util to aoa.util.stoBug: cli listing not filtering archived entitiesCleanup: Remove pyspark support from CLI4.1.12Bug: aoa connection add now hides password symbolsBug: sto.util.cleanup_cli() used hardcoded models tableFeature: sto.util.check_sto_version() checks In-Vantage Python version compatibilityFeature: sto.util.collect_sto_versions() fetches dict with Python and packages versions4.1.11Bug: aoa run (evaluation) for R now uses the correct scoring file4.1.10Bug: aoa init templates were out of dateBug: aoa run (score) didn't read the dataset template correctlyBug: aoa run (score) tried to publish to prometheusBug: aoa run (score) not passing model_table kwargs4.1.9Bug: Histogram buckets incorrectly offset by 1 for scoring metrics4.1.7Bug: Quoted and escaped exported connection environmental variablesBug: aoa clone withpathargument didn't create .aoa/config.yaml in correct directoryFeature: aoa clone withoutpathnow uses repository name by defaultFeature: update BYOM import to upload artefacts before creating version4.1.6Feature: Added local connections feature with Stored Password ProtectionFeature: Self creation of .aoa/config.yaml file when cloning a repoBug: Fix argparse to use of common argumentsFeature: Support dataset templates for listing datasets and selecting dataset for train/evalBug: Fix aoa run for batch scoring, prompts for dataset template instead of datasetBug: Fix batch scoring histograms as cumulative4.1.5Bug: Fix computing statsFeature: Autogenerate category labels and support for overriding themFeature: Prompt for confirmation when retiring/archiving4.1.4Feature: Retiring deployments and archiving projects supportFeature: Added support for batch scoring monitoring4.1.2Bug: Fix computing statsBug: Fix local SQL model training and evaluation4.1Bug: CLI shows archived entities when listing datasets, projects, etcBug: Adapt histogram bins depending on range of integer types.4.0Feature: Extract and record dataset statistics for Training, Evaluation3.1.1Feature:aoa clonerespects project branchBug: support Source Model ID from the backend3.1Feature: ability to separate evaluation and scoring logic into separate files for Python/R3.0Feature: Add support for Batch Scoring in run commandFeature: Added STO utilities to extract metadata for micro-models2.7.2Feature: Add support for OAUTH2 token refresh flowsFeature: Add dataset connections api support2.7.1Feature: Add TrainedModelArtefactsApiBug: pyspark cli only accepted old resources formatBug: Auth mode not picked up from environment variables2.7.0Feature: Add support for dataset templatesFeature: Add support for listing models (local and remote), datasets, projectsFeature: Remove pykerberos dependency and update docsBug: Fix tests for new dataset template api structureBug: Unable to view/list more than 20 datasets / entities of any type in the cli2.6.2Bug: Added list resources command.Bug: Remove all kerberos dependencies from standard installation, as they can be now installed as an optional feature.Feature: Add cli support for new artefact path formats2.6.1Bug: Remove pykerberos as an installation dependency.