Model Operations

Validate datasets, train XGBoost models locally, publish artifacts to S3, and activate the serving model.

Sentra's current model maintenance path is local CPU training plus AWS model serving.

The intended loop:

Add or update a contract-format dataset.
Validate the dataset.
Train an XGBoost model locally.
Review metrics, feature importance, and data quality.
Publish model artifacts to S3.
Update the active model pointer.
Confirm /v1/risk/score reports the new model version.

Local dataset shape

partner_batch_001/
  transactions.csv
  labels.csv
  entities.csv
  kyc_docs.jsonl
  manifest.json

transactions.csv is required. labels.csv is required for meaningful supervised training.

Validate

.venv/bin/python scripts/validate_partner_dataset.py /path/to/partner_batch_001

Train

.venv/bin/python scripts/train_local_model.py /path/to/partner_batch_001 \
  --output-dir localdata/models

Example for a larger mapped payment log dataset:

.venv/bin/python scripts/train_local_model.py localdata/datasets/payment_batch_001 \
  --output-dir localdata/models \
  --model-version sentra-score-xgb-20260523 \
  --feature-set pre_decision \
  --evaluation-mode time_split \
  --max-training-rows 100000 \
  --n-estimators 60 \
  --n-jobs 4

Feature sets

Feature set	Use
`pre_decision`	Publishable risk scoring model; avoids leakage from final status/gateway outcome fields.
`online`	API-compatible base model using current `/v1/risk/score` fields.
`post_event`	Operational analysis model using response codes, latency, duplicate-order, amount percentile, and merchant-hour fields.
`all`	Exploration only.

For production pre-authorization decisions, prefer pre_decision.

Output artifacts

Training writes:

model.json
metrics.json
feature_schema.json
feature_importance.json
data_quality_report.json

feature_schema.json is the handoff contract between offline training and online inference.

Evaluation

Use --evaluation-mode time_split before treating a local model as a publish candidate. It trains on earlier rows and tests on later rows, which better reflects production drift.

For imbalanced fraud labels, inspect:

best_f1_threshold
best_f1_precision
best_f1_recall
precision_at_review_rate_0_001
precision_at_review_rate_0_005
precision_at_review_rate_0_01
precision_at_review_rate_0_05
matching recall values

Publish to S3

AWS_DEFAULT_REGION=us-east-1 \
SENTRA_MODEL_BUCKET=sentra-model-registry \
.venv/bin/python scripts/publish_model.py localdata/models/<model_version>

This uploads artifacts to:

s3://sentra-model-registry/models/<model_version>/

and updates:

s3://sentra-model-registry/models/active-model.json

Serve active model

Run the backend with:

SENTRA_MODEL_REGISTRY_MODE=s3_pointer
SENTRA_MODEL_BUCKET=sentra-model-registry
SENTRA_ACTIVE_MODEL_KEY=models/active-model.json

The scoring API loads the active pointer and aligns incoming features to feature_schema.json.

Admin model registry

In the Console Admin page, admins can:

View model versions.
Inspect metrics and provenance.
See active model.
Activate a registered model.
Trigger demo/local training flows where configured.

Dry runs without labels

For early data mapping only:

.venv/bin/python scripts/train_local_model.py /path/to/partner_batch_001 \
  --output-dir localdata/models \
  --allow-heuristic-labels

Heuristic labels are acceptable for dry runs, not for production model acceptance.

On this page