Sparkient Docs

How Sparkient uses teacher-generated examples to train fast, purpose-built decision models.

Sparkient's training pipeline uses a teacher-student architecture: a large language model can generate and label examples offline, and a smaller model learns the bounded decision from those examples.

Training a model is required before you can call /decide. Deploying a trained model unlocks the decision endpoint for that decision type.

The Training Pipeline

Define Decision Type
        ↓
  Generate Examples (LLM teacher)
        ↓
  Label Examples (LLM teacher)
        ↓
  Augment Rare Classes (LLM teacher)
        ↓
  Feature Engineering (auto-detected)
        ↓
  Text Encoding
        ↓
  Model Training
        ↓
  Model Export
        ↓
  Deploy to Production

Synthetic Data Generation

You do not need historical customer data to start. Sparkient's teacher LLM can generate candidate examples from the decision definition; review the coverage and add representative real examples when available.

Generation — The teacher LLM creates varied candidate inputs across the defined outcomes
Labelling — The teacher LLM assigns decisions and reason codes according to the definition
Augmentation — Gap analysis identifies underrepresented classes, and the teacher LLM generates targeted examples to balance the dataset

Feature Engineering

Features are auto-detected from your input schema:

Input Type	Feature Strategy
Numbers	Z-score normalization
Booleans	Binary encoding
Strings (short)	Categorical encoding
Strings (long)	Text encoder selected by the training pipeline
Arrays	Length + aggregation features
Nested objects	Flattened with dot notation

For text-heavy decisions, a fine-tuned text encoder is trained on your data and its embeddings are stacked as features for the final classifier.

Model Training

The final classifier is a gradient-boosted model with automated hyperparameter tuning:

Automatic cross-validation
Bayesian hyperparameter optimization
Multi-class classification with probability calibration
Export to a compiled model format for portable, fast inference

Triggering Training

curl -X POST https://api.sparkient.ai/api/v1/decision-types/{id}/train \
  -H "Authorization: Bearer YOUR_API_KEY"

Training runs asynchronously. You can check the status via the dashboard or the policies endpoint.

Minimum data requirements: Training requires at least 38 labelled examples per decision option (the training pipeline requires 30 per class in the 80/20 training split). Check readiness via GET /decision-types/{id}/training-readiness.

Tuning Augmentation Size

Data augmentation is the single biggest lever for model quality. The augment_target_size parameter controls how many total training examples the pipeline targets after augmentation.

Default: number_of_options × 300 (e.g. 4 options → 1,200 examples)

The default is a starting configuration, not a quality guarantee. Increase it when held-out evaluation shows that:

Your decision involves free-text input (descriptions, messages, reviews) — text classifiers benefit from more diverse examples
You have many options (6+) — each class needs enough examples for the model to learn the boundaries
Your model's F1 score is below your target — more data often helps

Increase augmentation target

{
  "augment_target_size": 2000,
  "target_f1": 0.85
}

Start with the default. Check your model's F1 score after training, then increase augment_target_size and retrain if quality is below your threshold. Maximum: 5,000.

Deploying a Model

After training completes, a policy is created containing the trained model. Auto-deployment is enabled by default; if it is disabled or a configured quality gate is not met, activate the reviewed policy manually:

curl -X POST https://api.sparkient.ai/api/v1/decision-types/{id}/policies/{policy_id}/deploy \
  -H "Authorization: Bearer YOUR_API_KEY"

Once deployed, /decide uses the trained model on the normal path. Low-confidence cloud decisions can still use the metered LLM escalation path; exported edge bundles have no cloud fallback.

Training