howso.amlg

;This is a template of a trainee for the Howso API.
;It provides the management functions for the trainee.
;
; Style notes:
; all methods are assumed to have null values as defaults for parameters
; any methods that need non-null default parameters are inside (declare) blocks, where the non-null defaults are explicitly defined
; public "methods" should be lower_case_snake_case
; private "methods" should be !PascalCase
; private "attributes" of the model should be !camelCase
; parameters and "local variables" should be lower_case_snake_case
; parameters/variables and attributes that are sets or assocs should end with "_map" or "Map" respectively for readability (or _set and Set)
;
;A trainee has the following structure of contained entities:
;	cases : system generated entity ids
;	sessions : user specified session ids
;
;	each case has the following labels:
; 		features : model specific feature and its value
;		.session : session id of case when it was trained
;		.session_training_index : 0-based index of the case, ordered by training during the session;  is not changed
;
;   optional built-in features that cases may have are:
;	   .case_weight : weight of this case
;	   .imputed : list of imputed features
;	   .case_edit_history : assoc of edits to this case
;
;	each session has the following labels:
;		.replay_steps : list of case ids in the order they were trained
;		.indices_map : map of each cases's session_training_index to its case_id
;		.metadata : arbitrary dictionary of metadata
;
; 	case (entity name = case_id) : { .session: session, .session_training_index: trained_instance_index}
; 	session (entity name = session) : { .replay_steps: [ case_id(s) ], .indices_map { s_t_i -> case_id },  .trained_instance_count: number, .metadata: {} }

(null

	;case labels that are not features and are used for internal processing should be prepended with a period
	#!internalLabelSession ".session"
	#!internalLabelSessionTrainingIndex ".session_training_index"
	#!internalLabelImputed ".imputed"
	#!internalLabelCaseEditHistory ".case_edit_history"
	#!internalLabelInfluenceWeightEntropy ".influence_weight_entropy"

	;the name of the entity that contains subtrainees
	#!traineeContainer ".trainee_container"

	;the supported prediction stats that users can request from react_aggregate
	#!supportedPredictionStats (list "mae" "confusion_matrix" "r2" "rmse" "adjusted_smape" "smape" "spearman_coeff" "precision" "recall" "accuracy" "mcc" "all" "missing_value_accuracy")

	;all the characters that may not be the first character of a feature when training a dataset
	#!untrainableFeatureCharacterSet
	(assoc "." (null) "!" (null) "#" (null) "^" (null))

	;all the reserved characters that may not be the first character of a feature in any flow
	#!reservedFeatureCharacterSet
	(assoc "!" (null) "#" (null) "^" (null))

	;label for loading modules
	#!loadModulesEndpoint (null)

	;label holding a map of external label names to maps of parameters names to typing specification for each parameter
	;this label is built and assigned in #!BuildParameterValidationMap, which is called in #initialize[_for_deployment]
	;and then used within the #!ValidateParameters
	#!parameterValidationMap (null)

	;value-storing labels, initialized and commented below via the initialize label
	#!numericalPrecision (null)
	#!trainedFeatures (null)
	#!trainedFeaturesContextKey (null)
	#!reactIntoFeaturesList (null)
	#!metaData (null)
	#!categoricalFeaturesSet (null)
	#!ordinalFeatures (null)
	#!hasEncodedFeatures (null)
	#!hasFeaturesNeedEncodingFromInput (null)
	#!hasCyclicFeatures (null)
	#!cyclicFeaturesMap (null)
	#!numericNominalFeaturesMap (null)
	#!editDistanceFeatureTypesMap (null)
	#!stringNominalFeaturesSet (null)
	#!userSpecifiedFeatureErrorsMap (null)
	#!averageModelCaseEntropyAddition (null)
	#!averageModelCaseEntropyRemoval (null)
	#!averageModelCaseDistanceContribution (null)
	#!storedCaseConvictionsFeatureAddition (null)
	#!storedConvictionsFeatureSet (null)
	#!nominalClassProbabilitiesMap (null)
	#!expectedValuesMap (null)
	#!featureNullRatiosMap (null)
	#!defaultNumSamples (null)
	#!ordinalFeaturesValuesMap (null)
	#!ordinalFeaturesRangesMap (null)
	#!uniqueNominalsSet (null)
	#!cachedFeatureMinResidualMap (null)
	#!cachedFeatureHalfMinGapMap (null)
	#!hyperparameterMetadataMap (null)
	#!hyperparameterParamPaths (null)
	#!defaultHyperparameters (null)
	#!staleOrdinalValuesCount (null)
	#!minAblatementModelSize (null)
	#!hasSubstituteFeatureValues (null)
	#!substitutionValueMap (null)
	#!unSubstituteValueMap (null)
	#!featureAttributes (null)
	#!featureRoundingMap (null)
	#!hasRoundedFeatures (null)
	#!hasDateTimeFeatures (null)
	#!hasPopulatedCaseWeight (null)
	#!featureDateTimeMap  (null)
	#!featureBoundsMap (null)
	#!seriesStore (null)
	#!seriesFeatures (null)
	#!autoAblationEnabled (null)
	#!autoAblationMinNumCases (null)
	#!autoAblationMaxNumCases (null)
	#!autoAblationInfluenceWeightEntropyThreshold (null)
	#!reduceDataInfluenceWeightEntropyThreshold (null)
	#!autoAblationExactPredictionFeatures (null)
	#!autoAblationTolerancePredictionThresholdMap (null)
	#!autoAblationRelativePredictionThresholdMap (null)
	#!autoAblationResidualPredictionFeatures (null)
	#!autoAblationConvictionLowerThreshold (null)
	#!autoAblationConvictionUpperThreshold (null)
	#!autoAblationWeightFeature (null)
	#!autoAblationMaxInfluenceWeightEntropy (null)
	#!autoAblationAbsThresholdMap (null)
	#!autoAblationDeltaThresholdMap (null)
	#!autoAblationRelThresholdMap (null)
	#!autoAnalyzeEnabled (null)
	#!autoAnalyzeThreshold (null)
	#!autoAnalyzeGrowthFactorAmount (null)
	#!ablationBatchSize (null)
	#!ablatedCasesDistributionBatchSize (null)
	#!dataMassChangeSinceLastAnalyze (null)
	#!dataMassChangeSinceLastDataReduction (null)
	#!savedAnalyzeParameterMap (null)
	#!derivedFeaturesMap (null)
	#!sourceToDerivedFeatureMap (null)
	#!featureCustomDerivedMethods (null)
	#!tsTimeFeature (null)
	#!tsTimeFeatureUniversal (null)
	#!tsMinTimeInterval (null)
	#!tsSeriesLimitLength (null)
	#!tsModelFeaturesMap (null)
	#!tsSupportedDetails (null)
	#!hasStringOrdinals (null)
	#!ordinalStringToOrdinalMap (null)
	#!ordinalOrdinalToStringMap (null)
	#!ordinalNumericFeaturesSet (null)
	#!hasPostProcessing (null)
	#!postProcessMap (null)
	#!hasDependentFeatures (null)
	#!dependentFeatureMap (null)
	#!sharedDeviationsMap (null)
	#!sharedDeviationGroupByPrimaryMap (null)
	#!sharedDeviationsNonPrimaryFeatures (null)
	#!sharedDeviationsPrimaryFeatures (null)
	#!continuousToNominalDependenciesMap (null)
	#!dependentsBoundaryMap (null)
	#!dependentValuesCombinationsMap (null)
	#!encodingNeededFeaturesSet (null)
	#!nominalsMap (null)
	#!novelSubstitionFeatureSet (null)
	#!inactiveFeaturesMap (null)
	#!inactiveFeaturesNeedCaching (null)
	#!featureMarginalStatsMap (null)
	#!continuousRebalanceFeatures (null)
	#!nominalRebalanceFeatures (null)
	#!cachedRebalanceClassValueWeightMap (null)
	#!cachedRebalanceUnknownValueWeightMap (null)
	#!queryDistanceTypeMap (null)
	#!influenceWeightThreshold (null)
	#!regionalModelMinSize (null)
	#!revision 0
	#!synthesisRetriesPerConvictionLevel 3
	#!sandboxedComputeLimit (null)
	#!sandboxedMemoryLimit (null)
	#!sandboxedOpcodeDepthLimit (null)
	#!containedTraineeIdToNameMap (null)
	#!containedTraineeNameToIdMap (null)
	#!childTraineeIsContainedMap (null)
	#!parentId (null)
	#!traineeId (null)

	;The major version of the Trainee
	;{read_only (true) idempotent (true) attribute "number"}
	#major_version 0

	;The minor version of the Trainee
	;{read_only (true) idempotent (true) attribute "number"}
	#minor_version 0

	;The point version of the Trainee
	;{read_only (true) idempotent (true) attribute "number"}
	#point_version 0

	;flag to indicate if DD submodel should be created and used during each residual computation iteration within analyze
	#!useDynamicDeviationsDuringAnalyze (null)

	;list of modules for trainee template
	#!traineeTemplateModules
	(list
		"ablation"
		"attributes"
		"attribute_maps"
		"analysis"
		"analysis_weights"
		"boundary_values"
		"contributions"
		"conviction"
		"custom_codes"
		"derive_features"
		"derive_utilities"
		"distances"
		"editing"
		"details"
		"details_cases"
		"details_influences"
		"details_residuals"
		"feature_conviction"
		"feature_residuals"
		"generate_features"
		"get_cases"
		"get_sessions"
		"hierarchy"
		"hyperparameters"
		"impute"
		"influences"
		"input_validation"
		"io"
		"marginal"
		"mda_weight"
		"react"
		"react_discriminative"
		"react_group"
		"react_aggregate"
		"react_series"
		"react_series_stationary"
		"react_series_utilities"
		"react_utilities"
		"remove_cases"
		"residuals"
		"return_types"
		"series_store"
		"shared_deviations"
		"substitution"
		"synthesis"
		"synthesis_bounds"
		"synthesis_utilities"
		"synthesis_validation"
		"train"
		"train_ts_ablation"
		"types"
		"update_cases"
		"upgrade"
	)

	;set the private label !file_extension during deployment and clear out this method so that the file extension cannot be edited after deployment.
	;This should be run once by the deployment script.
	#initialize_for_deployment
	(declare
		(assoc
			;{type "string"}
			;file extension, either caml or amlg
			file_extension "caml"
		)
		(assign_to_entities (assoc !file_extension file_extension ))

		(call !LoadModules)
		;clear out this label so that it can't be run again
		(assign_to_entities (assoc initialize_for_deployment (null)))
		(call !BuildParameterValidationMap)
	)

	;load module entities code directly into trainee template only if modules have not been loaded
	#!LoadModules
	(if (= (null) !loadModulesEndpoint)
		(seq
			(direct_assign_to_entities (assoc !loadModulesEndpoint (map (lambda (retrieve_entity_root (current_value))) (retrieve_from_entity "!traineeTemplateModules")) ))
			;delete all contained entities after the specified modules' code has been loaded in
			(apply "destroy_entities" (contained_entities))
			;clear out the list of labels and this labels since models have been loaded and shouldn't be reloaded again
			(assign (assoc
				!traineeTemplateModules (null)
				!LoadModules (null)
			))
		)
	)

	;set all default values
	#initialize
	(declare
		(assoc
			;{type "string" required (true)}
			;unique id for this trainee
			trainee_id (null)
			;{type "string" required (true)}
			;filepath location to where the howso file is stored
			filepath (null)
		)

		;load specified modules' code into the trainee if they have not been loaded yet
		(call !LoadModules)

		(call !BuildParameterValidationMap)

		;can stop initializing if !traineeContainer already exists because this trainee has already been initialized
		(if (contains_entity !traineeContainer) (conclude))

		;create the trainee container entity
		(create_entities !traineeContainer (lambda (null)))

		;set the filepath if specified
		(if filepath (assign_to_entities (assoc filepath filepath)) )

		#!InitializeValues
		(assign_to_entities (assoc
			!revision 0

			;assoc of id of trainee -> name of trainee
			!containedTraineeIdToNameMap (assoc)

			;assoc of trainee name -> id
			!containedTraineeNameToIdMap (assoc)

			;assoc of name of trainee -> is_internal boolean
			; true means the trainee is a contained subtrainee
			; false means it is in the hierarchy but not a contained trainee and communication with it requires routing outside of this trainee
			!childTraineeIsContainedMap (assoc)

			;unique id of parent trainee if this trainee is a subtrainee in a hierarchy
			!parentId (null)

			;unique id of this trainee
			!traineeId trainee_id

			;amount of total influence weight to accumulate among nearest neighbors before stopping (for influential cases)
			!influenceWeightThreshold .99

			;default regional model size
			!regionalModelMinSize 30

			;null defaults to "recompute_precise"
			!numericalPrecision (null)

			;the size of the model when to start ablatement
			!minAblatementModelSize 100

			;the average case entropy for the whole model, used for calculating new case conviction. cleared any time the model is changed
			!averageModelCaseEntropyAddition (null)
			!averageModelCaseEntropyRemoval (null)

			;the average case distance contribution value for the whole model
			!averageModelCaseDistanceContribution (null)

			;name of conviction features, value is set when stored convictions exist and are up-to-date. cleared any time the model is changed
			!storedCaseConvictionsFeatureAddition (null)

			;set of features for which case convictions are stored
			!storedConvictionsFeatureSet (null)

			;the default list of features for the model, derived as the sorted indices of !featureAttributes
			!trainedFeatures (list)

			;the context_key made from the !trainedFeatures of the model
			!trainedFeaturesContextKey ""

			;the list of features computed and cached into cases through #react_into_features
			!reactIntoFeaturesList (list)

			;arbitrary model metadata
			!metaData (assoc)

			;assoc of all feature attributes
			!featureAttributes (assoc)

			;a map of model feature -> bounds used for generation, created automatically from feature attributes
			!featureBoundsMap (assoc)

			;flag set to true if there are features that have rounding specified for output
			!hasRoundedFeatures (false)

			;assoc of feature -> (list int_round decimal_round)
			!featureRoundingMap (assoc)

			;flag set to true if there are features that are date time and need encoding/decoding
			!hasDateTimeFeatures (false)

			;map of every date-time feature and its encoding format
			!featureDateTimeMap  (assoc)

			;flag should be set to true if there are features that were encoded somehow, (substituted, boolean, rounded, datetime, string ordinals), used to decode on output
			;setting to false will skip encoding and decoding
			!hasEncodedFeatures (false)

			;flag should be set to true if there are features that need to be encoded in some way on input
			;such as boolean, datetime, string ordinal, json, yaml and amalgam
			!hasFeaturesNeedEncodingFromInput (false)

			;set of features that need to be encoded for input
			!encodingNeededFeaturesSet (assoc)

			;set of names of features which are categorical (nominal or ordinal) instead of continuous
			; categorical features are taken from a single case instead of interpolated between training cases
			!categoricalFeaturesSet (assoc)

			;map of nominal features for fast lookup
			!nominalsMap (assoc)

			;set of features that will use novel nominal substition once output
			!novelSubstitionFeatureSet (assoc)

			;set of string nominals
			!stringNominalFeaturesSet (assoc)

			;assoc of all string continuous or any json or amalgam features for fast lookup, feature -> data_type
			!editDistanceFeatureTypesMap (assoc)

			;assoc of nominal features names whose values are all uniques
			!uniqueNominalsSet (assoc)

			;assoc of all numeric and boolean nominal features for fast lookup, feature -> data_type
			!numericNominalFeaturesMap (assoc)

			;store class probabilities for each nominal feature;  weight feature -> feature -> probability
			!nominalClassProbabilitiesMap (assoc)

			;map of feature -> type for use in queries. i.e., "nominal", "continuous", "cyclic", "string", "code"
			!queryDistanceTypeMap (assoc)

			;list of ordinal features
			!ordinalFeatures (list)

			;assoc of unique sorted feature values for each ordinal feature, used in case generation
			!ordinalFeaturesValuesMap (assoc)

			;assoc of feature -> range (last value - first value) of cyclic feature
			!ordinalFeaturesRangesMap (assoc)

			;flag set to true if there are string ordinals in this model
			!hasStringOrdinals (false)

			;assoc of feature -> assoc of string -> ordinal value
			!ordinalStringToOrdinalMap (assoc)

			;assoc of feature -> assoc of ordinal value -> string
			!ordinalOrdinalToStringMap (assoc)

			;set of ordinal numeric (non-string) features
			!ordinalNumericFeaturesSet (assoc)

			;flag set when the ordinal values in !ordinalFeaturesValuesMap are out of date
			!staleOrdinalValuesCount (true)

			;flag, set to true when there are values in the !substitutionValueMap
			!hasSubstituteFeatureValues (false)

			;assoc of feature -> feature value -> substitution value used to substitute values on output
			!substitutionValueMap (assoc)

			;assoc of feature -> substitution value -> feature value used to undo substitution on input
			!unSubstituteValueMap (assoc)

			;flag should be set to true if there are cyclic features, will provide the ranges for the features to the query engine
			!hasCyclicFeatures (false)

			;assoc of each cyclic feature -> length of cycle
			;example: (assoc "day" 7 "degrees" 360)
			!cyclicFeaturesMap (null)

			;assoc of feature -> observational_error value as specified by the user
			!userSpecifiedFeatureErrorsMap (assoc)

			;map of inactive feature (i.e., feature that has only null values) -> feature weight, set to null when empty
			!inactiveFeaturesMap (null)

			;flag set to true if there are inactive features but they need to be rechecked if they are still inactive and recached
			!inactiveFeaturesNeedCaching (true)

			;sample size of model to use for calculating deviations
			!defaultNumSamples 100

			;cache smallest residual for each feature, used during case generation
			!cachedFeatureMinResidualMap (assoc)

			!cachedFeatureHalfMinGapMap (assoc)

			;assoc of weight_feature -> feature -> expected feature value
			!expectedValuesMap (assoc)

			;assoc of feature -> assoc of min, max, has_nulls and null_residual values for each feature
			!featureNullRatiosMap (assoc)

			;flag set to true when the .case_weight feature is populated
			!hasPopulatedCaseWeight (false)

			;stores history of reacts for a series (eg, a game or a time series)
			;format of { series:  [ react values ] }
			!seriesStore (assoc)

			;stores features corresponding to stored cases in !seriesStore
			;format of: { series: features }
			!seriesFeatures (assoc)

			;assoc of derived features -> their original value parent feature, e.g.,  ".value_delta_1" -> "value" where ".value_delta_1" is used to derive "value"
			!derivedFeaturesMap (assoc)

			;map of source feature to a list derived features that rely on it
			;format of: { source_feature : [ list of derived features ] }
			!sourceToDerivedFeatureMap (assoc)

			;assoc of feature -> train / single_react / series_react -> corresponding parsed custom method codd
			!featureCustomDerivedMethods (assoc)

			;flag set to true when post_process is specified for a feature attribute
			!hasPostProcessing (false)

			;assoc of feature -> post_process -> custom_code
			!postProcessMap (assoc)

			;a value used to limit the operations of each usage of (call_sandboxed)
			!sandboxedComputeLimit 1000

			;a value used to limit the allocations of each usage of (call_sandboxed), 0 = no limit
			!sandboxedMemoryLimit 100000

			;a value used to limit the depth of opcode operations of each usage of (call_sandboxed)
			!sandboxedOpcodeDepthLimit 50

			;name of the 'time' feature if the model is a time series model
			!tsTimeFeature (null)

			;flag set to true if time series time feature is universal,
			;filtering out all future data during reacts instead of only future data specific to a series
			!tsTimeFeatureUniversal (false)

			;time series minimium time delta
			!tsMinTimeInterval 1e-3

			;maximum allowed length for a series in the dataset, e.g., 215
			!tsSeriesLimitLength 0

			;time series model various feature names
			!tsModelFeaturesMap
				(assoc
					;list of all the lag features e.g., (list ".date_lag_1" ".valueA_lag_1" ".valueB_lag_1")
					"lag_features" (list)
					;list of all the delta features e.g., (list ".date_delta_1")
					"delta_features" (list)
					;list of all the rate features e.g., (list ".valueB_rate_1" ".valueA_rate_2")
					"rate_features" (list)
					;list of order features which are derived from higher orders instead of generated, e.g., (list ".valueA_rate_1")
					"derived_order_features" (list)
					;list of features that make up the ID for the series e.g., (list "sender" "receiver")
					"series_id_features" (list)
					;list of all features that  need to be derived in the order they should be derived
					"ts_derived_features" (list)
					;flag, set to true if series has values that explicitly denote the end of a series
					"series_has_terminators" (false)
					;flag, set to true if a series must end on a terminator value
					"stop_on_terminator" (false)
					;the minimum time to bound queries including the time feature below when using a universal time feature
					"minimum_time_bound" (null)
				)

			;list of supported details for react series
			!tsSupportedDetails (list "categorical_action_probabilities" "influential_cases" "generate_attempts")

			;flag set to true if there are features that are dependent on others
			!hasDependentFeatures (false)

			;assoc of feature -> { 'dependent_features' : [ list of dependent features ] }
			!dependentFeatureMap (assoc)

			;assoc of feature ->  primary feature key from group of shared deviations features
			;  This primary feature key is the first sorted feature in the group of features
			!sharedDeviationsMap (assoc)

			;list of all primary shared features
			!sharedDeviationsPrimaryFeatures (list)

			;list of all non-primary shared features in a group
			!sharedDeviationsNonPrimaryFeatures (list)

			;assoc of primary group feature -> list of shared features in its group
			; e.g.,  { "a": ["a", "b"], "c": ["c", "d"] }
			!sharedDeviationGroupByPrimaryMap (assoc)

			;assoc of continuous feature -> [ list of sorted nominal dependents ]
			!continuousToNominalDependenciesMap (assoc)

			;assoc of continuous feature -> multi-level assoc where each level has values for a dependent feature, and the next level
			;has values for the next dependent feature, with the leaf value being either (null) if no such value combination exists in the dataset,
			;or a pair of values of min,max for the continuous boundary
			;eg: "value" : { "heart rate" : { "BPM" : [ 20, 220] }, "heart rate" : { "mSv": (null) }, "xray": { "mSv" : [ 0.01 - 2.0 ] }, "xray" : { "BPM" : (null) } }
			;the levels are ordered by the sorted order as determined in !continuousToNominalDependenciesMap
			!dependentsBoundaryMap (assoc)

			;assoc of continuous feature -> a 2d list, a list of valid combinations of values of dependent nominal values,
			; e.g., { "value" : (list  (list "heart rate" "BPM") (list "BMI" "ratio")) }
			;the values for features are ordered by the sorted order as determined in !continuousToNominalDependenciesMap
			!dependentValuesCombinationsMap (assoc)

			;when false the model should not automatically ablate cases as they are trained nor cache influence weight entropies
			; during analyze.
			!autoAblationEnabled (false)

			;if !autoAblationEnabled is set, stores the minimum number of cases required to ablate.
			!autoAblationMinNumCases 1000

			;if !autoAblationEnabled is set, stores the minimum number of cases required to reduce data.
			!autoAblationMaxNumCases 500000

			;the influence weight entropy threshold quantile that a case's influence weight entropy must be less than in order to
			; not be ablated. Default 1/e^2.
			!autoAblationInfluenceWeightEntropyThreshold 0.135335283

			;the influence weight entropy threshold quantile that a case's influence weight entropy must be less than in order to
			; not be removed in reduce_data. Default 1-1/e.
			!reduceDataInfluenceWeightEntropyThreshold 0.632120559

			;number of cases in a batch to consider for ablation prior to training and to recompute influence weight entropy.
			!ablationBatchSize 2000

			;number of cases in a batch to distribute ablated cases' influence weights.
			!ablatedCasesDistributionBatchSize 100

			;the features for which a case should be ablated if the predicted value of the feature matches the actual value of the feature.
			!autoAblationExactPredictionFeatures (null)

			;the features for which a case should be ablated if the predicted value of the feature is within a given absolute threshold.
			!autoAblationTolerancePredictionThresholdMap (null)

			;the features for which a case should be ablated if the predicted value of the feature is within a given relative threshold.
			!autoAblationRelativePredictionThresholdMap (null)

			;the features for which a case should be ablated if the residuals of the feature are within the bounds of the stored residuals.
			!autoAblationResidualPredictionFeatures (null)

			;the conviction threshold below which a case should be ablated.
			!autoAblationConvictionUpperThreshold (null)

			;the conviction threshold above which a case should be ablated.
			!autoAblationConvictionLowerThreshold (null)

			;the name of the weight feature to use for auto ablation.
			!autoAblationWeightFeature ".case_weight"

			;cached value of the max influence weight entropy to keep cases cases during ablation
			!autoAblationMaxInfluenceWeightEntropy (null)

			;absolute threshold map for auto-ablation, if these are satisfied then auto-ablation will cease.
			!autoAblationAbsThresholdMap (assoc)

			;delta threshold map for auto-ablation, if these are satisfied then auto-ablation will cease.
			!autoAblationDeltaThresholdMap (assoc)

			;relative threshold map for auto-ablation, if these are satisfied then auto-ablation will cease.
			!autoAblationRelThresholdMap (assoc)

			;when false the model should not be auto-analyzed
			!autoAnalyzeEnabled (false)

			;if specified, stores the threshold for the change in data mass since the last analyze at which the model should be re-analyzed
			!autoAnalyzeThreshold 100

			;if !autoAnalyzeEnabledis set, the factor by which to increase that threshold every time the model grows to that threshold size
			!autoAnalyzeGrowthFactorAmount 7.389056

			;map of parameters used when analyze was called on this model
			!savedAnalyzeParameterMap (null)

			;hyperparameters stored in nested assocs, where full paths are
			; [ targeted/targetless [action_feature] context_features case_weight_feature/.none)
			!hyperparameterMetadataMap (assoc)

			;list of param paths to Hyperparameter assocs in !hyperparameterMetadataMap
			!hyperparameterParamPaths (list)

			;default hyperparameters, these are used when there are no cached hyperparameters
			!defaultHyperparameters
				(assoc
					"k" 8
					"p" 0.1
					"dt" -1
					"featureWeights" (null)
					"featureDeviations" (null)
					"paramPath" (list ".default")
				)

			;assoc of feature -> stat -> value. stored under the name of the weight feature used for the calculation.
			;for marginal stats like min, max, mode, mean, count, etc..
			; { '.none': { 'feat_name': {'min': 2 ... } ... } ... }
			!featureMarginalStatsMap (assoc)

			;cumulative count of the data mass changed since analyze was last called. this is accumulated to by any operations
			;which add, remove, or edit cases.
			!dataMassChangeSinceLastAnalyze 0.0

			;cumulative count of the data mass changed since reduce_data was last called. this is accumulated to by any operations
			;which add, remove, or edit cases.
			!dataMassChangeSinceLastDataReduction 0.0

			;flag to indicate if the DD subtrainee should be recreated and used with each iteration of residuals within Analyze
			!useDynamicDeviationsDuringAnalyze (false)

			;list of rebalance features that are continuous or ordinal, set if case weights are enabled and computed from these features
			!continuousRebalanceFeatures (null)

			;list of rebalance features that are nominal
			!nominalRebalanceFeatures (null)

			;assoc of { feature -> { value -> weight } } for nominal rebalance features, cached during analyze
			!cachedRebalanceClassValueWeightMap (null)

			;assoc of { feature -> unknown class weight } for nominal rebalance features, caching would-be weight of unknown classes
			!cachedRebalanceUnknownValueWeightMap (null)
		))

		(call !Return)
	)

	;default value to use for filepath when calling save or load
	;{read_only (true) idempotent (true) attribute "string"}
	#filepath "./"

	;location of Howso Engine files, used for upgrading trainees (referencing
	;{read_only (true) idempotent (true) attribute "string"}
	#root_filepath "./"

	#!migration_folder "migrations/"

	;default value to use for filename when calling save or load
	;{read_only (true) idempotent (true) attribute "string"}
	#filename "default_trainee"

	;location of trainee template
	#!trainee_template_filename "howso"

	;valid extensions are:
	; amlg : raw amalgam code
	; caml : compressed amalgam, binary format
	#!file_extension "amlg"

	;The version of the trainee set externally
	;{read_only (true) idempotent (true) payload (false)}
	#version (get (load (concat filepath "version.json")) "version")

	;The version stored in trainee
	;{read_only (true) idempotent (true) payload (false)}
	#get_trainee_version
	(declare
		;returns {type "string"}
		(assoc)
		(concat
			(retrieve_from_entity "major_version") "."
			(retrieve_from_entity "minor_version") "."
			(retrieve_from_entity "point_version")
		)
	)

	;returns the trainee's unique id
	;{read_only (true) idempotent (true) payload (false)}
	#get_trainee_id
	(declare
		;returns {type "string"}
		(assoc)
		(retrieve_from_entity "!traineeId")
	)

	;set trainee's unique id
	;{idempotent (true)}
	#set_trainee_id
	(declare
		(assoc
			;{type ["string" "null"]}
			;a unique string identifier for the trainee
			trainee_id (null)
		)
		(call !ValidateParameters)
		(assign_to_entities (assoc !traineeId trainee_id))
		(accum_to_entities (assoc !revision 1))
		(call !Return)
	)

	;set trainee's unique parent id
	;{idempotent (true) protected (true)}
	#set_parent_id
	(declare
		(assoc
			;{type ["string" "null"]}
			;the unique string identifier for the parent of the trainee
			parent_id (null)
		)
		(call !ValidateParameters)
		(assign_to_entities (assoc !parentId parent_id))
		(accum_to_entities (assoc !revision 1))
		(call !Return)
	)

	;get trainee's unique parent id
	;{read_only (true) idempotent (true) }
	#get_parent_id
	(declare
		;returns {type ["string" "null"]}
		(assoc)
		(call !Return (assoc payload (retrieve_from_entity "!parentId")  ))
	)

	;set metadata for model
	;{idempotent (true)}
	#set_metadata
	(declare
		(assoc
			;{type ["assoc" "null"] required (true)}
			;arbitrary map of metadata to store in a trainee
			metadata (null)
		)
		(call !ValidateParameters)
		(assign_to_entities (assoc !metaData metadata))
		(accum_to_entities (assoc !revision 1))
		(call !Return)
	)

	;get metadata for model
	;{read_only (true) idempotent (true)}
	#get_metadata
	(declare
		;returns {type ["assoc" "null"]}
		(assoc)
		(call !Return (assoc payload (retrieve_from_entity "!metaData") ))
	)

	;set the random seed on a trainee
	#set_random_seed
	(declare
		(assoc
			;{type ["number" "string" "null"]}
			;the value of the random seed to set on the trainee, assigns a system-provided 64-bit random number if null is provided
			seed (null)
		)
		(call !ValidateParameters)
		(if (= seed (null))
			(assign (assoc seed (system "rand" 16) ))
		)
		(set_entity_rand_seed seed)
		(accum_to_entities (assoc !revision 1))

		(call !Return)
	)

	;set the influence weight threshold for outputting only the K neighbors whose influence weight is <= to this threshold
	;default value is 0.99
	;{idempotent (true)}
	#set_influence_weight_threshold
	(declare
		(assoc
			;{type "number"}
			;number, amount of total influence weight to accumulate among nearest
			;neighbors before stopping (for influential cases)
			influence_weight_threshold 0.99
		)
		(call !ValidateParameters)
		(assign_to_entities (assoc !influenceWeightThreshold influence_weight_threshold))
		(accum_to_entities (assoc !revision 1))
		(call !Return)
	)

	;returns the trainee's !revision
	;{read_only (true) idempotent (true)}
	#get_revision
	(declare
		;returns {
		; 	type "assoc"
		; 	description "Map containing the revision count of the trainee."
		;	additional_indices (false)
		; 	indices {
		; 		"count" {
		;			type "number"
		;			required (true)
		;		}
		; 	}
		; }
		(assoc)
		(call !Return (assoc payload (assoc "count" (retrieve_from_entity "!revision")) ))
	)

	;returns a structure containing all of the API details for this module
	;{read_only (true) idempotent (true)}
	#get_api
	(declare
		;returns {ref "GetAPIResponse"}
		(assoc)

		(let
			(assoc
				api
					(assoc
						"description"
						(get_entity_comments)

						"version"
						(call get_trainee_version)

						"labels"
						(map
							(lambda
								(let
									(assoc
										label_flags_map
											(let
												(assoc
													rgx_match (last (substr (current_value 2) "\\{.+\\}" "all"))
												)

												(if (!= (null) rgx_match)
													(parse rgx_match)

													;else use an empty assoc
													{}
												)
											)
										parameters
											;when debugging, comments are injected to all lines, these must be removed
											;some parameters may have comments other than the type hint as well
											(map
												(lambda
													;(current_value) is a tuple of [comments of parameter, default value]
													(append
														;regex to just capture the {} information
														(or (parse (substr (first (current_value)) "\\{.+\\}")) (assoc) )
														(assoc
															default (call (last (current_value 1)))
															description
																;replace the typing assoc with an empty string, only get description
																(substr
																	(first (current_value 1))
																	"^\\{.+\\}\\r?\\n?"
																	(null)
																	""
																)
														)
													)
												)
												;first item is the assoc of parameter names to comments/default value
												(first (get_entity_comments (null) (current_index 1) (true)))
											)
									)

									(append
										(assoc
											"description"
												;replace the flags assoc with an empty string, only get description
												(substr
													(current_value 1)
													"\\{.+\\}"
													(null)
													""
												)
											"parameters"
												(if (size parameters)
													parameters
												)

											"returns"
												(let
													(assoc
														return_type_map
															(parse
																(substr
																	(substr
																		;last item is the comment on the (assoc)
																		(last (get_entity_comments (null) (current_index 2) (true)))
																		;replace special chars with spaces
																		"[\\r\\t\\n]"
																		(null)
																		" "
																	)
																	"\\{.+\\}"
																)
															)
													)

													(if (and
															(contains_index return_type_map "ref")
															(contains_index !returnTypes (get return_type_map "ref"))
														)
														(call (get !returnTypes (get return_type_map "ref")))

														;otherwise just return the type
														(call return_type_map)
													)
												)
										)

										label_flags_map
									)
								)
							)
							(get_entity_comments (null) (null) (true))
						)

						"schemas"
						(call (retrieve_from_entity "!customTypes"))
					)
			)

			(call !Return (assoc payload api))
		)
	)

	;debug method to output any internal label, used by unit tests and debugging
	;parameters:
	; label: string or list of strings, name(s) of labels values to output
	;{read_only (true) idempotent (true)}
	#debug_label
	(declare
		(assoc
			;{type "string" required (true)}
			;the string name of the label to be retrieved
			label (null)
		)
		(retrieve_from_entity label)
	)

	;create a return response object in the format of:
	; success:
	; [ 1, { 'payload' : payload, 'warnings' : warnings } ]
	;
	; error:
	; [ 0, { 'detail': error_descriptions, 'code': error_code, 'errors': field_validation_details } ]
	;
	;parameters:
	; errors: optional, list of error strings to output
	; error_code: optional, string defining the error code, e.g., 'validation'
	; error_details: optional, assoc defining field validation errors
	; warnings: optional, list of warning strings to output
	; payload: any value or object
	#!Return
	(if errors
		(list 0
			(append
				(assoc "detail" (if (> (size errors) 1) errors (first errors)) )
				(if error_code (assoc "code" error_code) (assoc))
				(if error_details (assoc "errors" error_details) (assoc))
			)
		)

		warnings
		(list 1 (assoc "payload" payload "warnings" warnings ) )

		(list 1 (assoc "payload" payload) )
	)

)