Decision Pipeline

The decision pipeline is the core of Sparkient. Every call to /decide starts with rules and the deployed classifier. A third, live-LLM stage runs only when escalation is enabled and the configured confidence condition is met.

The Three Stages

Input → [1. Rules] → [2. Classifier] → [3. Optional escalation] → Response
          usually <1ms    <100ms target      model dependent

Stage 1: Hard Rules

Latency: < 1ms

Expression rules are evaluated first. If any rule matches, the decision is returned immediately. This is the fastest path — pure logic, no ML involved.

Use this for:

• Compliance requirements ("always block amounts over $50,000")
• Known patterns ("reject if the user is banned")
• Rate limiting ("escalate if more than 10 requests in 1 minute")

Stage 2: ML Classifier

Target latency: < 100ms on the compiled stage

If no rules match, the classifier runs inference using the deployed compiled classifier model with pre-computed features and optional text embeddings. A deployed model is required — without one, /decide returns 428 Precondition Required.

The classifier returns a decision along with:

• Confidence score (0.0 to 1.0)
• Class probabilities for all options
• Reason codes selected from option-compatible annotations in the training data

Sparkient compares confidence with the higher of the global escalate_below value and the predicted option's per_option threshold. At or above that threshold, the classifier response is returned. Below it, the configured escalation policy determines what happens next.

Reason codes are always constrained to the decision type's configured taxonomy. Add representative reason-code annotations to your examples so the compiled classifier can return useful, option-specific reasons.

Stage 3: LLM Escalation

Latency: model, prompt, provider, and retry dependent

An optional fallback for low-confidence cloud decisions when escalation_policy.enabled is true. The LLM receives the input and decision type context and produces a structured decision with explanation.

This stage includes:

• Automatic retry with exponential backoff
• Structured output parsing
• Timeout protection

Set escalation_policy.enabled to false for a classifier-only deployment. Low-confidence classifier results then return with escalate: true for human review, without an LLM call or escalation charge. If the classifier is not ready, Sparkient returns 503 Service Unavailable; it does not silently call the LLM or fabricate a configured option.

Response Format

Every decision — regardless of which stage produced it — returns the same structured format:

{
  "decision": "approve",
  "confidence": 0.94,
  "reason_codes": ["safe_content"],
  "latency_ms": 8.3,
  "stage": "classifier",
  "escalate": false,
  "fallback_used": false,
  "rules_triggered": [],
  "class_probabilities": {
    "approve": 0.94,
    "flag": 0.04,
    "reject": 0.02
  },
  "request_id": "req_abc123"
}

The stage field tells you which stage produced the decision:

• "rules" — a hard rule matched
• "classifier" — the ML model decided
• "escalation" — the LLM fallback was used
• "fallback" — no compiled or escalation decision was produced, for example because a strict latency budget prevented inference

Latency Breakdown

Training Configuration

Every policy uses the complete text-model and classifier pipeline. Augmentation and hyperparameter tuning are enabled by default and can be configured for a specific run. Duration depends on the dataset and available compute, so clients should follow the live attempt, stage, and heartbeat fields.

You can also set a quality gate (target_f1) and enable auto-deployment (auto_deploy: true). See the quickstart for examples.

Training Example Fields

When adding training examples, use the canonical field names:

The shorter aliases are accepted for convenience but the canonical names are recommended.

Authentication

The /decide endpoint accepts both API key and Firebase JWT authentication. Dashboard-only endpoints (account management, billing, API key CRUD) require a Firebase JWT. See Authentication for details.