0
# Type Definitions
1

2
Complete TypedDict definitions for all data structures used in OpenInference tracing, ensuring type safety and proper structure validation across the API.
3

4
## Capabilities
5

6
### Message Types
7

8
Type definitions for LLM message structures supporting text, images, and tool calls.
9

10
```python { .api }
11
class Message(TypedDict, total=False):
12
    """
13
    Message structure for LLM interactions.
14
    
15
    Fields:
16
        role (str): Message role ("user", "assistant", "system", etc.)
17
        content (str): Text content of the message
18
        contents (Sequence[MessageContent]): Structured content blocks
19
        tool_call_id (str): ID of tool call this message responds to
20
        tool_calls (Sequence[ToolCall]): Tool calls made in this message
21
    """
22
    role: str
23
    content: str
24
    contents: Sequence[MessageContent]
25
    tool_call_id: str
26
    tool_calls: Sequence[ToolCall]
27

28
MessageContent = Union[TextMessageContent, ImageMessageContent]
29
"""Union type for different message content types."""
30

31
class TextMessageContent(TypedDict):
32
    """Text content block in a message."""
33
    type: Literal["text"]
34
    text: str
35

36
class ImageMessageContent(TypedDict):
37
    """Image content block in a message."""
38
    type: Literal["image"]  
39
    image: Image
40

41
class Image(TypedDict, total=False):
42
    """Image reference structure."""
43
    url: str
44
```
45

46
**Usage Example:**
47

48
```python
49
# Text message
50
text_message: Message = {
51
    "role": "user",
52
    "content": "Hello, how are you?"
53
}
54

55
# Message with structured content
56
structured_message: Message = {
57
    "role": "user",
58
    "contents": [
59
        {"type": "text", "text": "What do you see in this image?"},
60
        {"type": "image", "image": {"url": "data:image/jpeg;base64,..."}}
61
    ]
62
}
63

64
# Assistant message with tool calls
65
assistant_message: Message = {
66
    "role": "assistant", 
67
    "tool_calls": [
68
        {
69
            "id": "call_123",
70
            "function": {
71
                "name": "get_weather",
72
                "arguments": '{"city": "San Francisco"}'
73
            }
74
        }
75
    ]
76
}
77
```
78

79
### Tool Types
80

81
Type definitions for tool calling and function execution.
82

83
```python { .api }
84
class Tool(TypedDict, total=False):
85
    """
86
    Tool definition structure.
87
    
88
    Fields:
89
        json_schema (Required[Union[str, Dict[str, Any]]]): JSON schema for tool parameters
90
    """
91
    json_schema: Required[Union[str, Dict[str, Any]]]
92

93
class ToolCall(TypedDict, total=False):
94
    """
95
    Tool call structure in messages.
96
    
97
    Fields:
98
        id (str): Unique identifier for the tool call
99
        function (ToolCallFunction): Function call details
100
    """
101
    id: str
102
    function: ToolCallFunction
103

104
class ToolCallFunction(TypedDict, total=False):
105
    """
106
    Function details within a tool call.
107
    
108
    Fields:
109
        name (str): Function name to call
110
        arguments (Union[str, Dict[str, Any]]): Function arguments (JSON string or dict)
111
    """
112
    name: str
113
    arguments: Union[str, Dict[str, Any]]
114
```
115

116
**Usage Example:**
117

118
```python
119
# Tool definition
120
calculator_tool: Tool = {
121
    "json_schema": {
122
        "type": "object",
123
        "properties": {
124
            "operation": {"type": "string", "enum": ["+", "-", "*", "/"]},
125
            "a": {"type": "number"},
126
            "b": {"type": "number"}
127
        },
128
        "required": ["operation", "a", "b"]
129
    }
130
}
131

132
# Tool call in message
133
tool_call: ToolCall = {
134
    "id": "call_456",
135
    "function": {
136
        "name": "calculator",
137
        "arguments": {"operation": "+", "a": 10, "b": 5}
138
    }
139
}
140
```
141

142
### Token Count Types
143

144
Type definitions for LLM token usage tracking.
145

146
```python { .api }
147
class TokenCount(TypedDict, total=False):
148
    """
149
    Token usage information.
150
    
151
    Fields:
152
        prompt (int): Number of tokens in the prompt
153
        completion (int): Number of tokens in the completion
154
        total (int): Total number of tokens used
155
        prompt_details (PromptDetails): Detailed prompt token breakdown
156
    """
157
    prompt: int
158
    completion: int
159
    total: int
160
    prompt_details: PromptDetails
161

162
class PromptDetails(TypedDict, total=False):
163
    """
164
    Detailed prompt token usage breakdown.
165
    
166
    Fields:
167
        audio (int): Tokens used for audio input
168
        cache_read (int): Tokens read from cache
169
        cache_write (int): Tokens written to cache
170
    """
171
    audio: int
172
    cache_read: int
173
    cache_write: int
174
```
175

176
**Usage Example:**
177

178
```python
179
# Simple token count
180
simple_tokens: TokenCount = {
181
    "prompt": 50,
182
    "completion": 25,
183
    "total": 75
184
}
185

186
# Detailed token count with cache info
187
detailed_tokens: TokenCount = {
188
    "prompt": 100,
189
    "completion": 50,
190
    "total": 150,
191
    "prompt_details": {
192
        "cache_read": 30,
193
        "cache_write": 10,
194
        "audio": 5
195
    }
196
}
197
```
198

199
### Document Types
200

201
Type definitions for retrieval and reranking operations.
202

203
```python { .api }
204
class Document(TypedDict, total=False):
205
    """
206
    Document structure for retrieval systems.
207
    
208
    Fields:
209
        content (str): Document text content
210
        id (Union[str, int]): Document identifier
211
        metadata (Union[str, Dict[str, Any]]): Document metadata (dict or JSON string)
212
        score (float): Relevance or similarity score
213
    """
214
    content: str
215
    id: Union[str, int]
216
    metadata: Union[str, Dict[str, Any]]
217
    score: float
218
```
219

220
**Usage Example:**
221

222
```python
223
# Document with metadata dict
224
doc_with_metadata: Document = {
225
    "content": "This is the document content...",
226
    "id": "doc-123",
227
    "metadata": {
228
        "source": "database",
229
        "author": "John Doe",
230
        "timestamp": "2024-01-01T10:00:00Z"
231
    },
232
    "score": 0.95
233
}
234

235
# Document with JSON metadata string
236
doc_with_json_metadata: Document = {
237
    "content": "Another document...",
238
    "id": 456,
239
    "metadata": '{"category": "technical", "language": "en"}',
240
    "score": 0.87
241
}
242
```
243

244
### Embedding Types
245

246
Type definitions for embedding operations.
247

248
```python { .api }
249
class Embedding(TypedDict, total=False):
250
    """
251
    Embedding structure.
252
    
253
    Fields:
254
        text (str): Text that was embedded
255
        vector (List[float]): Embedding vector values
256
    """
257
    text: str
258
    vector: List[float]
259
```
260

261
**Usage Example:**
262

263
```python
264
# Text embedding
265
text_embedding: Embedding = {
266
    "text": "Hello world",
267
    "vector": [0.1, 0.2, 0.3, -0.1, 0.5]
268
}
269

270
# List of embeddings
271
embeddings: List[Embedding] = [
272
    {"text": "First document", "vector": [0.1, 0.2, 0.3]},
273
    {"text": "Second document", "vector": [0.4, 0.5, 0.6]}
274
]
275
```
276

277
### OpenInference Type Aliases
278

279
Type aliases for OpenInference-specific enumerations and values.
280

281
```python { .api }
282
OpenInferenceSpanKind = Union[
283
    Literal[
284
        "agent",
285
        "chain", 
286
        "embedding",
287
        "evaluator",
288
        "guardrail",
289
        "llm",
290
        "reranker",
291
        "retriever",
292
        "tool",
293
        "unknown",
294
    ],
295
    OpenInferenceSpanKindValues,
296
]
297
"""OpenInference span kind type allowing string literals or enum values."""
298

299
OpenInferenceMimeType = Union[
300
    Literal["application/json", "text/plain"],
301
    OpenInferenceMimeTypeValues,
302
]
303
"""MIME type for input/output values."""
304

305
OpenInferenceLLMProvider = Union[str, OpenInferenceLLMProviderValues]
306
"""LLM provider identifier (string or enum value)."""
307

308
OpenInferenceLLMSystem = Union[str, OpenInferenceLLMSystemValues]
309
"""LLM system identifier (string or enum value)."""
310
```
311

312
**Usage Example:**
313

314
```python
315
from openinference.semconv.trace import OpenInferenceSpanKindValues
316

317
# Using literal strings (must be lowercase)
318
span_kind: OpenInferenceSpanKind = "llm"
319

320
# Using enum values
321
span_kind_enum: OpenInferenceSpanKind = OpenInferenceSpanKindValues.LLM
322

323
# MIME types
324
mime_json: OpenInferenceMimeType = "application/json"
325
mime_text: OpenInferenceMimeType = "text/plain"
326

327
# Provider names
328
provider: OpenInferenceLLMProvider = "openai"
329
system: OpenInferenceLLMSystem = "gpt"
330
```
331

332
## Type Safety Features
333

334
### Total vs Partial TypedDicts
335

336
- **`total=False`**: All fields are optional
337
- **`total=True` (default)**: All fields are required unless marked Optional
338
- **`Required[]`**: Mark specific fields as required in partial TypedDicts
339

340
### Union Types
341

342
Many types use Union to support multiple formats:
343

344
- `Union[str, int]` for IDs that can be strings or numbers
345
- `Union[str, Dict[str, Any]]` for metadata that can be pre-serialized JSON or dicts
346
- `Union[TextMessageContent, ImageMessageContent]` for different content types
347

348
### Sequence Types
349

350
Use `Sequence` instead of `List` for immutable collections:
351
- More flexible (accepts lists, tuples, etc.)
352
- Indicates the function won't modify the collection
353
- Better for type checking with mypy
354

355
## Usage with Type Checkers
356

357
All types are designed to work well with mypy and other type checkers:
358

359
```python
360
from typing import TYPE_CHECKING
361

362
if TYPE_CHECKING:
363
    from openinference.instrumentation import Message, TokenCount
364

365
def process_llm_response(messages: list[Message], tokens: TokenCount) -> None:
366
    # Type checker will validate structure
367
    for message in messages:
368
        if "role" in message:
369
            print(f"Role: {message['role']}")
370
        if "content" in message:
371
            print(f"Content: {message['content']}")
372
    
373
    print(f"Used {tokens.get('total', 0)} tokens")
374
```