1
import json
2
from twelvelabs import TwelveLabs, TextParam
3
from twelvelabs.types.text_param_format import TextParamFormat_JsonSchema
4
5
client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
STORE_ID = "<YOUR_KNOWLEDGE_STORE_ID>"
7
8
# Request a collection overview
9
print("Understanding your collection...")
10
response = client.responses.create(
11
    knowledge_store_id=STORE_ID,
12
    input=[{"type": "message", "role": "user", "content": "Give me a high-level overview of this video collection. What themes, subjects, and patterns do you see?"}],
13
)
14
15
# Read the overview and store the session ID
16
session_id = response.session_id
17
for output in response.output:
18
    if output.type == "message":
19
        for content in output.content:
20
            print(content.text)
21
22
# Define the organization axes schema
23
axes_schema = {
24
    "type": "object",
25
    "properties": {
26
        "recommended_axes": {
27
            "type": "array",
28
            "items": {
29
                "type": "object",
30
                "properties": {
31
                    "axis": {"type": "string"},                  # Name of the categorization dimension
32
                    "reason": {"type": "string"},                # Why this axis works well
33
                    "expected_categories": {                      # Sample category names
34
                        "type": "array",
35
                        "items": {"type": "string"},
36
                    },
37
                    "score": {"type": "number"},                 # 0-1 effectiveness score
38
                },
39
            },
40
        },
41
        "best_axis": {"type": "string"},                         # Top-ranked axis name
42
        "reasoning": {"type": "string"},                         # Overall recommendation rationale
43
    },
44
}
45
46
# Discover organization strategies
47
print("\nFinding the best organization strategy...")
48
response = client.responses.create(
49
    knowledge_store_id=STORE_ID,
50
    session_id=session_id,
51
    input=[{"type": "message", "role": "user", "content": "What are the best ways to organize this collection? Rank the top 3 axes by how well they'd separate the content into useful groups."}],
52
    text=TextParam(format=TextParamFormat_JsonSchema(name="organization_axes", schema_=axes_schema)),
53
)
54
55
# Parse the organization strategies
56
for output in response.output:
57
    if output.type == "message":
58
        for content in output.content:
59
            axes = json.loads(content.text)
60
            print(f"Best axis: {axes['best_axis']}")
61
            print(f"Reasoning: {axes['reasoning']}")
62
            for ax in axes["recommended_axes"]:
63
                print(f"  {ax['axis']} (score: {ax['score']}): {ax['reason']}")
64
65
# Define the catalog schema
66
catalog_schema = {
67
    "type": "object",
68
    "properties": {
69
        "organization_axis": {"type": "string"},             # The axis used for categorization
70
        "categories": {
71
            "type": "array",
72
            "items": {
73
                "type": "object",
74
                "properties": {
75
                    "name": {"type": "string"},              # Category name
76
                    "description": {"type": "string"},       # What this category contains
77
                    "videos": {
78
                        "type": "array",
79
                        "items": {
80
                            "type": "object",
81
                            "properties": {
82
                                "reference": {"type": "string"},  # Source video identifier
83
                                "title": {"type": "string"},      # Video title
84
                                "summary": {"type": "string"},    # Brief description
85
                            },
86
                        },
87
                    },
88
                },
89
            },
90
        },
91
        "total_videos": {"type": "integer"},                 # Total number of videos categorized
92
    },
93
}
94
95
# Categorize videos
96
print(f"\nOrganizing by '{axes['best_axis']}'...")
97
response = client.responses.create(
98
    knowledge_store_id=STORE_ID,
99
    session_id=session_id,
100
    input=[{"type": "message", "role": "user", "content": f"Now organize every video by '{axes['best_axis']}'. Include all videos."}],
101
    text=TextParam(format=TextParamFormat_JsonSchema(name="video_catalog", schema_=catalog_schema)),
102
)
103
104
# Parse the catalog
105
for output in response.output:
106
    if output.type == "message":
107
        for content in output.content:
108
            catalog = json.loads(content.text)
109
            print(f"\nLibrary Catalog ({catalog['total_videos']} videos)")
110
            print(f"Organized by: {catalog['organization_axis']}")
111
            for cat in catalog["categories"]:
112
                print(f"\n  [{cat['name']}] - {cat['description']}")
113
                for v in cat["videos"]:
114
                    print(f"    {v['title']}: {v['summary']}")