Classification Sets

A classification set is a named collection of class definitions that can be referenced by signature in classification requests. Classification sets enable semantic caching, versioning, and consistent classification across your application.

Why Use Classification Sets?

Instead of passing class definitions inline with every request, you can:

1. Define classes once via the API
2. Reference by signature in subsequent requests
3. Benefit from semantic caching (inline classes bypass cache)
4. Version your classes using signature naming (e.g., sentiment-v1, sentiment-v2)
5. Ensure consistency across all classification requests

Classification Set Structure

{
  "name": "Sentiment Analysis",
  "signature": "sentiment-v1",
  "description": "Classify text sentiment",
  "classes": [
    {
      "label": "positive",
      "description": "Expresses satisfaction or happiness"
    },
    {
      "label": "negative",
      "description": "Expresses dissatisfaction or frustration"
    },
    {
      "label": "neutral",
      "description": "Factual or emotionally neutral"
    }
  ]
}

Signatures and Versioning

The signature is a unique identifier for your classification set. Use it to:

• Reference the set in /v1/classify requests
• Version your classes (e.g., areas-v1, areas-v2)
• Maintain multiple sets for different classification tasks

{
  "data": "I love this product!",
  "classification_set": "sentiment-v1"
}

Content Hashing

When you create or update a classification set, Intentgine generates a content hash based on the class definitions. This hash is used for:

• Cache stability: Same classes = same cache keys
• Change detection: Updates invalidate relevant cache entries
• Deduplication: Identical sets share cache entries

Managing Classification Sets

Classification sets are managed via the API. See the API Reference for full documentation.

Create a Classification Set

curl -X POST https://api.intentgine.dev/v1/classification-sets \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sentiment Analysis",
    "signature": "sentiment-v1",
    "classes": [
      {
        "label": "positive",
        "description": "Expresses satisfaction"
      },
      {
        "label": "negative",
        "description": "Expresses dissatisfaction"
      }
    ]
  }'

List Classification Sets

curl https://api.intentgine.dev/v1/classification-sets \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Update a Classification Set

curl -X PUT https://api.intentgine.dev/v1/classification-sets/sentiment-v1 \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sentiment Analysis",
    "classes": [...]
  }'

Delete a Classification Set

curl -X DELETE https://api.intentgine.dev/v1/classification-sets/sentiment-v1 \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Best Practices

Use Descriptive Labels

Clear, descriptive labels improve classification accuracy:

✅ Good: positive, negative, neutral
❌ Avoid: class1, class2, class3

Provide Context in Descriptions

Detailed descriptions help the model understand nuances:

{
  "label": "urgent",
  "description": "Requires immediate attention or action within 24 hours"
}

Version for Breaking Changes

Create new versions when changing class definitions:

• Minor updates (improved descriptions): Update in place
• Breaking changes (new labels, removed classes): Create new version

Keep Sets Focused

Create separate sets for different classification tasks:

sentiment-v1    → Positive/negative/neutral
priority-v1     → Urgent/normal/low
category-v1     → Product categories

Inline vs Set-Based Classification

Feature	Inline Classes	Classification Sets
Class input	Inline definitions	Set signatures
Semantic caching	❌ No	✅ Yes
Best for	Prototyping, one-off	Production use
Performance	Slower (always compute)	Faster (cache hits)

Multi-Intent Classification

Classification sets support extraction for multi-intent queries. Enable this when creating your set:

{
  "name": "Smart Home Areas",
  "signature": "areas-v1",
  "enable_extraction": true,
  "classes": [
    { "label": "kitchen" },
    { "label": "bedroom" },
    { "label": "living_room" }
  ]
}

With extraction enabled, queries like “Turn on kitchen lights and bedroom fan” are automatically split and classified separately.

Next Steps

• See the API Reference for classification set endpoints
• Learn about Classification
• Explore Classification with Extraction