Core Concepts
Decision Types
Define what decisions your application needs to make.
A decision type is the core building block of Sparkient. It defines a specific kind of decision your application needs to make — content moderation, fraud detection, agent action gating, or anything else.
Anatomy of a Decision Type
Every decision type has:
| Field | Description |
|---|---|
| Name | Unique identifier (e.g., content_moderation). Used in API calls. |
| Description | Human-readable explanation of what this decision does. |
| Options | The possible outcomes (e.g., ["approve", "flag", "reject"]). |
| Reason Codes | Why a particular decision was made (e.g., ["safe_content", "spam"]). |
| Rules | Hard-coded CEL rules that fire before the ML classifier. |
| Input Schema | Optional JSON Schema to validate inputs before processing. |
Creating a Decision Type
curl -X POST https://api.sparkient.ai/api/v1/decision-types \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "agent_action_gate",
"description": "Should an AI agent proceed with this action?",
"options": ["act", "ask_user", "escalate", "block"],
"reason_codes": ["safe_action", "needs_confirmation", "high_risk"],
"rules": [
{
"name": "block_destructive",
"condition": "ctx.action_type == \"delete\" && ctx.scope == \"all\"",
"then": "block",
"reason_code": "high_risk",
"priority": 1
}
]
}'Versioning
Decision types are immutable by version. When you update a decision type (change options, rules, or thresholds), a new version is created. The active version is always the latest.
This means:
- You can roll back by re-activating an older version
- Training history is tied to specific versions
- Deployed models reference the version they were trained on
Confidence Thresholds
You can configure how confident the classifier must be before making a decision autonomously:
{
"confidence_thresholds": {
"auto_decide": 0.85,
"escalation": 0.5
}
}- Above
auto_decide— the classifier's decision is returned directly - Between
escalationandauto_decide— depends on the escalation policy - Below
escalation— always escalates to the LLM fallback