Recipes

Find organization axes

Discover the best dimensions for organizing your video collection. Jockey analyzes the content and recommends categorization strategies, scored by effectiveness.

Prerequisites

  • Complete the Quickstart to create a knowledge store with at least one item in ready status.
  • Read Create a response to understand the request and response format.

When to use this

  • You have a new collection and don’t know the best way to organize it
  • You want data-driven organization rather than arbitrary categories
  • You need to choose an organization strategy before categorizing

Discover the best organization strategy

Ask Jockey to recommend organization axes. The schema captures each axis with a description, expected number of groups, example categories, an effectiveness score, and a rationale - so you can compare strategies programmatically.

1import json
2import requests
3
4API_KEY = "YOUR_API_KEY"
5BASE_URL = "https://api.twelvelabs.io/v1.3"
6HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
7STORE_ID = "your_knowledge_store_id"
8
9axes_schema = {
10    "type": "object",
11    "properties": {
12        "axes": {
13            "type": "array",
14            "items": {
15                "type": "object",
16                "properties": {
17                    "axis": {"type": "string"},
18                    "description": {"type": "string"},
19                    "expected_groups": {"type": "integer"},
20                    "example_categories": {"type": "array", "items": {"type": "string"}},
21                    "effectiveness_score": {"type": "number"},
22                    "rationale": {"type": "string"}
23                }
24            }
25        },
26        "recommendation": {"type": "string"}
27    }
28}
29
30response = requests.post(
31    f"{BASE_URL}/responses",
32    headers=HEADERS,
33    json={
34        "model": "jockey1.0",
35        "instructions": "You are a content strategist. Analyze the video collection and recommend the most effective ways to organize it. Score each axis by how well it separates content into distinct, useful groups.",
36        "input": [
37            {
38                "type": "message",
39                "role": "user",
40                "content": "What are the top 5 best ways to organize this video collection? Score each from 0-1 based on how cleanly it separates the content."
41            }
42        ],
43        "tools": [
44            {"type": "knowledge_store", "knowledge_store_id": STORE_ID}
45        ],
46        "text": {"format": "json_schema", "json_schema": axes_schema}
47    }
48)
49
50result = response.json()
51for output in result["output"]:
52    if output["type"] == "message":
53        for content in output["content"]:
54            data = json.loads(content["text"])
55            print(f"Recommendation: {data['recommendation']}\n")
56            for ax in data["axes"]:
57                print(f"  {ax['axis']} (score: {ax['effectiveness_score']})")
58                print(f"    {ax['description']}")
59                print(f"    Groups: {ax['expected_groups']} - {', '.join(ax['example_categories'])}")
60                print(f"    Why: {ax['rationale']}\n")

Variations

  • Domain-constrained: “What are the best ways to organize these for a marketing team?”
  • User-centric: “How would different audiences want this organized?”
  • Hierarchical: “Suggest a two-level taxonomy: primary axis and sub-axes”

Jupyter notebook

Download the notebook to run this recipe interactively.

See also