Package: thamos
A CLI tool and library for communicating with Thoth backend.Using Thamos as a CLI toolThamos is released onPyPI. See
installation instructions bellow to setup Thoth/Thamos for your repository:#InstallThamosCLItool:$pip3installthamos# keep in mind: requires Python 3.6+!!#GotorepositorythatshouldbemanagedbyThothwhichalreadyhasPipfilepresent:$cd~/git/repo/#SetupThamosconfiguration:$thamosconfig#Addpackages.$thamosaddtensorflow#AskThothforsoftwarestackrecommendations:$thamosadvise#Installpackages:$thamosinstall# can be merged using `thamos advise --install`#Retrievelogsofthelastanalysis:$thamoslogAs Thamos notes analysis ids for better UX ofthamos log, it’s recommended to
add.thoth_last_analysis_idfile to.gitignore. Adding also.venvmight be useful if virtual environment management is turned on.Seethoth-station/cli-examplesrepository with examples.Recommendation typesSeethis documentfor a
detailed info on the recommendation types Thoth provides.Adjusting configuration based on environment variablesYou can adjust content of configuration file each time Thamos CLI or Thamos
library loads it by expanding entries with environment variables. This can be
handy if you would like to parameterize some of the options at
runtime (e.g. in deployment).This behaviour is (due to security reasons) explicitly turned off by default.
However you can turn it on by settingTHAMOS_CONFIG_EXPAND_ENVenvironment
variable to1(0explicitly turns this behaviour off, default value):THOTH_HOST=test.thoth-station.ninja THAMOS_CONFIG_EXPAND_ENV=1 thamos advise
2019-03-13 11:22:59,562 [18639] INFO     thamos.config: Expanding configuration file based on environment variablesEntries which should be expanded have environment variables in curly braces
like the following example:host:{THOTH_HOST}Note the expansion is done by replacing these values directly with values of
environment variable, this means types need to be taken into account
(environment variable with value"true"is put into configuration file astrue).Using custom configuration file templateYou can use your own custom configuration file as a template. This is
especially useful if you want to have some configuration entries constant and
let expand only some of the configuration options. In other words, you can
parametrize configuration file.An example of configuration file template can be:host:{THOTH_SERVICE_HOST}tls_verify:truerequirements_format:{requirements_format}runtime_environments:-name:'{runtime_environment_name}'operating_system:name:{os_name}version:'{os_version}'labels:foo:barkey:valuehardware:cpu_family:{cpu_family}cpu_model:{cpu_model}gpu_model:{gpu_model}python_version:'{python_version}'cuda_version:{cuda_version}recommendation_type:stableplatform:'{platform}'Then, you need to supply this configuration file to the following command:thamos config --template template.yamlListing of automatically expanded configuration options which are supplied the
config sub-command (these options are optional and will be expanded based on HW
or SW discovery):Configuration optionExplanationExampleruntime_environment_namename of operating systemfedora-35os_namename of operating systemfedoraos_versionversion of operating system35cpu_familyCPU family identifier6cpu_modelCPU model identifier94python_versionPython version (major.minor)3.10cuda_versionCUDA version (major.minor)11.1platformPlatform used.linux-x86_64requirements_formatRequirements format.pipenvbase_imageThoth base image used.quay.io/thoth-station/s2i-thoth-ubi8-py36:v1.0.0Platform corresponds tosysconfig.get_platform()call.These configuration options are optional and can be mixed with adjustment based
on environment variables (seeTHOTH_SERVICE_HOSTexample above). Note the
environment variables are not expanded onthamos configcall but rather on
other sub-commands issued (e.g.thamos adviseor others).The output format coming out of recommendations can be compatible withPipenv,raw pipor similar to the one
provided bypip-tools(actually same as forpipas these formats are interchangeable). The format is configured usingrequirements_formatconfiguration option, available options are:requirements_format: pipenvforPipenvcompatible outputrequirements_format: piporrequirements_format:pip-toolsforpiporpip-toolscompatible outputLabelsIt is possible to label requests for user-specific needs. In such a case,
resolver will include pipeline units that match labels with the ones provided
on the request.An example can be a CI system that is asking for an advise and labels the
request withrequester=ci_foo;team=thoth. In such a case, the resolution
engine includes pipeline units that are specific to the CI system and the team
specified (besides the ones that are added by default). Labels can be specified
in the.thoth.yamlconfiguration file or using CLI (labels passed via CLI
take precedence):thamos advise --labels requester=ci_foo;team=thothSee the followingdemo for more information.Support for multiple runtime environmentsThoth performs recommendations based on your hardware and software environment,
so called runtime environments. You can specify more than just one runtime
environment that should be targetted during recommendations. This might be
suitable if you would like to tweak some runtime environment specific
configuration options. An example could be a deployment of a machine learning
model to the cluster that uses CUDA, but you do not run CUDA locally (fast
iterative development locally, subsequently training a model in the cluster on
a large dataset). In such cases, you can specify two configuration entries in.thoth.yamlfile:host:{THOTH_SERVICE_HOST}tls_verify:truerequirements_format:pipenvruntime_environments:-name:'cuda'# <<<operating_system:name:fedoraversion:'32'hardware:cpu_family:6cpu_model:94gpu_model:'GeForceGTX680'python_version:'3.8'# <<< HEREcuda_version:'10.1'# <<<# <<< HERErecommendation_type:stableplatform:'linux-x86_64'openblas_version:'0.3.13'openmpi_version:'4.1'cudnn_version:'8'mkl_version:'2021.1.1'base_image:'quay.io/thoth-station/s2i-thoth-ubi8-py36-mkl:v0.23.0'-name:'no_cuda'# <<<operating_system:name:fedoraversion:'32'hardware:cpu_family:6cpu_model:94gpu_model:nullpython_version:'3.8'# <<< HEREcuda_version:null# <<<# <<< HERErecommendation_type:stableplatform:'linux-x86_64'openblas_version:'0.3.13'openmpi_version:'4.1'cudnn_version:nullmkl_version:'2021.1.1'base_image:'quay.io/thoth-station/s2i-thoth-ubi8-py36:v0.23.0'The two runtime environments stated in the.thoth.yamldiffer incuda_versionconfiguration and their names.To trigger advises for runtime environment namedcuda, issue:thamos advise --runtime-environment cudaTo target the latter runtime environment namedno_coda, you can issue:thamos advise --runtime-environment no_cudaThis option can be also supplied via environment variable usingTHAMOS_RUNTIME_ENVIRONMENT=no_cuda.If the runtime environment is not provided explictly, Thamos will take the
first runtime environment entry stated in theruntime_environmentlisting.
For the example showed above it will default tocudaenvironment:#defaultstothefirstone-"cuda"thamos adviseMultiple runtime environments can be used in conjunction with the automatically
expanded configuration options and configuration file templating naturally.By default, all the files produced during advises are stored in the project
root directory. To maintain multiple lock files specific for runtime
environments, it is possible to configure “overlays” directory in Thamos
configuration file.Listing available environments and container imagesTo list available environments for which the resolver can resolve dependencies,
issue:thamos environmentsEach entry states configuration of operating system, its version and Python
interpreter version that can be configured in each runtime environment section
in.thoth.yaml.If you wish to list available container images ready to be used:thamos imagesEach entry stated can be set as abase_imagein.thoth.yamlin the
respective runtime environment section and used as a base for running the
Python applications.Overlays directoryMultiple directories carrying requirement files can be configured usingoverlays_dirconfiguration option in.thoth.yamlfile. This
configuration is configured on a global scope and all the runtime environments
inherit path from it.An example configuration file statesoverlays_dir:host:{THOTH_SERVICE_HOST}tls_verify:truerequirements_format:pipenvoverlays_dir:overlaysruntime_environments:-name:'fedora-33'operating_system:name:fedoraversion:'33'python_version:'3.8'-name:'ubi-8'operating_system:name:rhelversion:'8'python_version:'3.8'In such case, the directrory structure respecting the configuration supplied
should be:.
├── app.py
├── overlays
│   ├── fedora-33
│   │   ├── Pipfile
│   │   ├── Pipfile.lock
│   │   ├── .env
│   │   └── constraints.txt
│   └── ubi-8
│   │   ├── Pipfile
│   │   ├── Pipfile.lock
│   │   ├── .env
│   │   └── constraints.txt
└── .thoth.yamlEach directory in theoverlaysdirectory should respect the runtime
environment name stated in.thoth.yamlfile and carries files specific for
the given runtime environment.Similarly as for Pipenv files, requirement files respectingpip-toolscan be used (requirements.inandrequirements.txt).Constraints files(constraints.txt) are optional.Optionally, users can provide.envfile that can state environment
variables that should be passed to the process whenthamos runis executed.
The.envfile states each environment variable on a single line in a form
ofENV_NAME=VALUE. Optionally, lines can be commented out with hash
(#).  An example of the file content:# This is an example .env file.
FOO=bar
ANOTHER_FOO=another_barEach.envfile can be specified per overlay. If no overlay directories are
used,.envfile can be placed in the top level project directory (the
directory where.thoth.yamlis present).Installing requirementsOnce a lock file is resolved after callingthamos advise, the application stack
can be installed by usingthamos installcommand. If you wish to pass additional
options that should be used bypip, you can do so by passing them after--.An example could be installing packages in a corporate network where packages should
be installed through a proxy tunnel:thamos install -- --proxy socks5h://127.0.0.1:8029 --trusted-host pypi.orgAdvise report structureThe structure of the advise report in JSON format produced with thethamos advise--jsoncommand is available in theThoth API advise endpointto retrieve advise results and in the correspondingschema specificationfor this endpoint.Using Thoth and thamos in OpenShift’s s2iUsing configuration templates is especially useful for OpenShift builds where
you can specify your template in an s2i repository (omitPipfile.lockto
enable call tothamos adviseas shown inthis repository).Then, you need to provide following environment variables:THAMOS_CONFIG_TEMPLATE- holds path to template - use/tmp/srcprefix to point to root of s2i repository (e.g./tmp/src/template.yamliftemplate.yamlis the configuration template and is stored in root of your Git repository).THAMOS_NO_INTERACTIVE- set to1if you don’t want to omit interactive thamos (suitable for automated s2i builds happening in the cluster).THAMOS_NO_PROGRESSBAR- set to1to disable progressbar while waiting for response from Thoth backend - it can cause annoying too verbose output printed to OpenShift console during the build.THAMOS_CONFIG_EXPAND_ENV- set to1to enable expansion based on environment variables when generating.thoth.yamlfile - this needs to be explicitly turned on due to possible security implications.THAMOS_FORCE- set to1not use cached results, always force analysis on Thoth’s side (note this option can be ignored by a Thoth operator based on deployment configuration).THAMOS_VERBOSE- set to1to run thamos in verbose mode to show what’s going on (verbosity on client side).THAMOS_DEBUG- set to1to run analyzes (adviser, provenance checker, …) on Thoth’s backend side in debug mode, you can obtain logs by runningthamos logsor directly on Thoth’s user API; the analysis id gets printed into the console during the build process in OpenShift (verbosity on server side).THAMOS_DEV- set to1to consider also development dependencies, this flag defaults to0- by enabling development dependencies, adviser will need to browse larger space of software stacks possibly ending with a worse software stack advised (development dependencies are usually not used during application deployment)THAMOS_DISABLE_CUDA- set to1to disable CUDA detectionTHAMOS_NO_EMOJI- set to1to disable UTF-8 emojis (useful for dummy terminals)THAMOS_NO_USER_STACK- set to1to disable sending lock file present in the directory - this lock file is used as a base when searching a better lock file for user needsTHAMOS_RETRY_ON_ERROR_COUNT- number of retries performed if the API server is responding with an error HTTP status (defaults to 3), this option is not usually needed to be adjustedTHAMOS_RETRY_ON_ERROR_SLEEP- sleep time when an error on the API server is spotted (seeTHAMOS_RETRY_ON_ERROR_COUNT), defaults to 3 secondsTHAMOS_NO_PROGRESSBAR- disable progress bar visualization, useful for dummy terminalsTHAMOS_TIMEOUT- timeout period in seconds after which Thamos stops trying to fetch resultsTHAMOS_DISABLE_LAST_ANALYSIS_ID_FILE- set to1if you do not want to create a file that states last analysis id (used not to memorize the last analysis id across commands)THAMOS_REQUIREMENTS_FORMAT- style of requirements used for managing dependencies - one ofpip,pip-tools,pipenv, defaults topipenvif not specifiedTHAMOS_TOKEN- token used for authenticated requests to the backendSeeOpenShift s2i documentationon how to pin build to a specific node in the cluster. This is needed if you
would like to perform automatic hardware discovery to get optimized stacks on
your hardware.Using Thamos as a libraryfromthamos.libimportimage_analysisfromthamos.configimportconfig# Set global context.# Host to Thoth's User API. API discovery will be done# transparently and the most appropriate API version will be used.config.explicit_host="khemenu.thoth-station.ninja"# TLS verification when communicating with Thoth API.config.tls_verify=Trueimage_analysis(image="registry.redhat.com/fedora:29",registry_user="fridex",registry_password="secret!",# TLS verification when communicating with registry.verify_tls=True,nowait=False)Disabling TLS related warningsIf you communicate with Thoth’s user API without TLS (you have set thetls_verifyconfiguration option tofalsein the.thoth.yamlfile),
Thamos CLI and Thamos library issue a warning each time there is done
communication with the API server. To suppress this warning, set theTHAMOS_DISABLE_TLS_WARNINGenvironment variable to a non-zero value:$exportTHAMOS_DISABLE_TLS_WARNING=1$thamosadviseAutogenerated client from OpenAPIMost parts of Thamos consist of automatic generated code. You can update Thamos
by running the following command:$./swagger-codegen.shThe command above will download and run automatic code generation tool against
the most recent OpenAPI specification ofUser API. Results of the tool are
automatically placed into this repository inthamos/swagger_client/andDocumentation/. They consist of automatically generated code as well asdocumentation on how to use the code.  Thamos
itself provides routines built on top of this automated generated code to
simplify usage inthamos/lib.