Training

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.

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

Every new training job generates fresh examples and augments its training data by default. Both stages consume credits; retries reuse completed batches. 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.

1. Generation — The teacher LLM creates varied candidate inputs across the defined outcomes
2. Labelling — The teacher LLM assigns decisions and reason codes according to the definition
3. 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:

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.

Dataset snapshots and limits

Sparkient freezes the exact labelled examples when POST /train is accepted. The response includes a dataset object with a SHA-256 manifest_id, example count, per-option distribution, payload bytes, provenance, and the plan limits used for admission. Examples added later are not silently included in that run.

Each decision type can store 5,000 examples. GET /decision-types/{id}/examples/stats reports total, max_allowed, and remaining, together with the current plan's per-training example and payload allowances. Upload and AI-generation requests are all-or-nothing: if the exact requested count would exceed the remaining capacity, Sparkient returns 409 example_storage_limit_exceeded before adding or generating anything. The response includes the current count, requested count, maximum, remaining capacity, and a recommended action.

The storage capacity and training allowance are deliberately separate. For example, a Starter customer may store 5,000 examples but must select a representative snapshot of no more than 2,500 for one training run.

To train a deliberate subset, pass example_ids. Missing, unlabelled, duplicate, or cross-decision-type IDs are rejected before compute starts. Requests above the plan's example or payload allowance return 413 with the measured snapshot and a recommended action.

Feature extraction uses bounded text micro-batches and persists completed text-model and feature checkpoints. Memory use therefore does not grow with one unbounded transformer call, and a safe retry can resume completed work with a smaller micro-batch.

Progress, failures, and retries

Poll GET /decision-types/{id}/policies/{policy_id}/progress. Every state includes the dataset summary and durable attempt history. Failed runs also return:

• error_code — stable machine-readable category
• error — plain-language explanation
• retryable — whether the same snapshot may be retried safely
• recommended_action — what to do next

For a recoverable resource or infrastructure failure, call POST /decision-types/{id}/policies/{policy_id}/retry. The retry keeps the same policy version and dataset manifest, reuses safe checkpoints, and can produce only one flat completion charge for that policy. Dataset/configuration failures require a new training request instead.

Tuning Augmentation Size

Augmentation adds varied training examples and fills class coverage gaps; it does not guarantee better results. 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

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

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.