0
# Text Analysis
1

2
Advanced text intelligence capabilities including sentiment analysis, topic detection, intent recognition, and content summarization. The Read/Analyze module processes text content to extract insights and understanding, providing detailed analysis results for various natural language processing tasks.
3

4
## Capabilities
5

6
### Analyze Client
7

8
Synchronous and asynchronous clients for comprehensive text analysis with configurable analysis options.
9

10
```python { .api }
11
class AnalyzeClient:
12
    def analyze_url(
13
        self,
14
        source: UrlSource,
15
        options: AnalyzeOptions = None,
16
        headers: dict = None,
17
        timeout = None
18
    ) -> AnalyzeResponse:
19
        """
20
        Analyze text content from URL.
21
        
22
        Args:
23
            source: URL source containing text to analyze
24
            options: Analysis configuration options
25
            headers: Additional HTTP headers
26
            timeout: Request timeout
27
            
28
        Returns:
29
            AnalyzeResponse: Complete analysis results with metadata
30
        """
31
    
32
    def analyze_text(
33
        self,
34
        source: TextSource,
35
        options: AnalyzeOptions = None,
36
        headers: dict = None,
37
        timeout = None
38
    ) -> AnalyzeResponse:
39
        """
40
        Analyze text content directly.
41
        
42
        Args:
43
            source: Text source to analyze
44
            options: Analysis configuration options
45
            headers: Additional HTTP headers
46
            timeout: Request timeout
47
            
48
        Returns:
49
            AnalyzeResponse: Complete analysis results with metadata
50
        """
51

52
class AsyncAnalyzeClient:
53
    async def analyze_url(
54
        self,
55
        source: UrlSource,
56
        options: AnalyzeOptions = None,
57
        headers: dict = None,
58
        timeout = None
59
    ) -> AsyncAnalyzeResponse:
60
        """Async version of analyze_url method"""
61
    
62
    async def analyze_text(
63
        self,
64
        source: TextSource,
65
        options: AnalyzeOptions = None,
66
        headers: dict = None,
67
        timeout = None
68
    ) -> AsyncAnalyzeResponse:
69
        """Async version of analyze_text method"""
70

71
# Alternative client names
72
class ReadClient(AnalyzeClient): ...
73
class AsyncReadClient(AsyncAnalyzeClient): ...
74
```
75

76
### Router Access
77

78
Access text analysis clients through the main client's read router.
79

80
```python { .api }
81
class ReadRouter:
82
    @property
83
    def analyze(self) -> AnalyzeClient: ...
84
    @property 
85
    def asyncanalyze(self) -> AsyncAnalyzeClient: ...
86
```
87

88
### Options Classes
89

90
```python { .api }
91
class AnalyzeOptions:
92
    def __init__(self, **kwargs): ...
93
    
94
    # Language settings
95
    language: str = "en"  # Language code for analysis
96
    
97
    # Analysis features
98
    topics: bool = False  # Topic detection and classification
99
    intents: bool = False  # Intent recognition
100
    sentiment: bool = False  # Sentiment analysis
101
    summarize: bool = False  # Text summarization
102
    
103
    # Custom models
104
    custom_intent: list = None  # Custom intent models
105
    custom_intent_mode: str = None  # Custom intent processing mode
106
    custom_topic: list = None  # Custom topic models
107
    custom_topic_mode: str = None  # Custom topic processing mode
108
    
109
    # Additional options
110
    callback: str = None  # Webhook callback URL
111
    callback_method: str = "POST"  # Callback HTTP method
112
    extra: dict = None  # Additional analysis options
113
```
114

115
### Source Types
116

117
Input sources for text data in various formats.
118

119
```python { .api }
120
class AnalyzeSource:
121
    """Base class for text analysis sources"""
122

123
class TextSource(AnalyzeSource):
124
    def __init__(self, text: str):
125
        """
126
        Text from string.
127
        
128
        Args:
129
            text: Text content to analyze
130
        """
131

132
class BufferSource(AnalyzeSource):
133
    def __init__(self, buffer: bytes):
134
        """
135
        Text from byte buffer.
136
        
137
        Args:
138
            buffer: Text content as bytes
139
        """
140

141
class StreamSource(AnalyzeSource):
142
    def __init__(self, stream):
143
        """
144
        Text from stream object.
145
        
146
        Args:
147
            stream: File-like stream object
148
        """
149

150
class FileSource(AnalyzeSource):
151
    def __init__(self, file: str):
152
        """
153
        Text from local file.
154
        
155
        Args:
156
            file: Path to local text file
157
        """
158

159
class UrlSource(AnalyzeSource):
160
    def __init__(self, url: str):
161
        """
162
        Text from URL.
163
        
164
        Args:
165
            url: HTTP/HTTPS URL to text content
166
        """
167

168
class AnalyzeStreamSource(AnalyzeSource):
169
    """Stream-specific source for analysis"""
170
```
171

172
### Response Types
173

174
```python { .api }
175
class AnalyzeResponse:
176
    """Main text analysis response"""
177
    metadata: AnalyzeMetadata
178
    results: AnalyzeResults
179

180
class AsyncAnalyzeResponse(AnalyzeResponse):
181
    """Async analysis response"""
182

183
class SyncAnalyzeResponse(AnalyzeResponse):
184
    """Sync analysis response"""
185

186
class AnalyzeMetadata:
187
    """Analysis request metadata"""
188
    request_id: str
189
    created: str
190
    language: str
191
    intents_info: IntentsInfo = None
192
    sentiment_info: SentimentInfo = None
193
    topics_info: TopicsInfo = None
194
    summary_info: SummaryInfo = None
195

196
class AnalyzeResults:
197
    """Analysis results container"""
198
    sentiments: Sentiments = None
199
    topics: Topics = None
200
    intents: Intents = None
201
    summary: AnalyzeSummary = None
202

203
class AnalyzeSummary:
204
    """Text summary results"""
205
    text: str
206
    start_word: int = None
207
    end_word: int = None
208
```
209

210
### Analysis Result Types
211

212
#### Sentiment Analysis
213

214
```python { .api }
215
class Sentiments:
216
    """Collection of sentiment analysis results"""
217
    segments: list[Segment]
218
    average: Average
219

220
class Sentiment:
221
    """Individual sentiment result"""
222
    sentiment: str  # "positive", "negative", "neutral"
223
    confidence: float
224

225
class SentimentInfo:
226
    """Sentiment analysis metadata"""
227
    input_tokens: int
228
    model_uuid: str
229
```
230

231
#### Topic Detection
232

233
```python { .api }
234
class Topics:
235
    """Collection of topic detection results"""
236
    segments: list[Segment] 
237
    
238
class Topic:
239
    """Individual topic result"""
240
    topic: str
241
    confidence: float
242

243
class TopicsInfo:
244
    """Topic detection metadata"""
245
    input_tokens: int
246
    model_uuid: str
247
```
248

249
#### Intent Recognition
250

251
```python { .api }
252
class Intents:
253
    """Collection of intent recognition results"""
254
    segments: list[Segment]
255

256
class Intent:
257
    """Individual intent result"""
258
    intent: str
259
    confidence: float
260

261
class IntentsInfo:
262
    """Intent recognition metadata"""
263
    input_tokens: int
264
    model_uuid: str
265
```
266

267
#### Common Analysis Types
268

269
```python { .api }
270
class Segment:
271
    """Analysis segment with results"""
272
    text: str
273
    start_word: int
274
    end_word: int
275
    sentiments: list[Sentiment] = None
276
    topics: list[Topic] = None
277
    intents: list[Intent] = None
278

279
class Average:
280
    """Average analysis metrics"""
281
    sentiment: str
282
    confidence: float
283

284
class SummaryInfo:
285
    """Summary generation metadata"""
286
    input_tokens: int
287
    model_uuid: str
288
```
289

290
## Usage Examples
291

292
### Basic Text Analysis
293

294
```python
295
from deepgram import DeepgramClient, TextSource, AnalyzeOptions
296

297
client = DeepgramClient(api_key="your-api-key")
298

299
# Analyze text for multiple insights
300
text = """
301
I absolutely love this new product! It's innovative and well-designed. 
302
The customer service team was incredibly helpful when I had questions about pricing and features.
303
I'm definitely planning to recommend this to my colleagues for our upcoming project.
304
"""
305

306
source = TextSource(text)
307
options = AnalyzeOptions(
308
    language="en",
309
    sentiment=True,
310
    topics=True,
311
    intents=True,
312
    summarize=True
313
)
314

315
response = client.read.analyze.analyze_text(source, options)
316

317
# Access analysis results
318
if response.results.sentiments:
319
    avg_sentiment = response.results.sentiments.average
320
    print(f"Overall sentiment: {avg_sentiment.sentiment} ({avg_sentiment.confidence:.2f})")
321

322
if response.results.topics:
323
    for segment in response.results.topics.segments:
324
        for topic in segment.topics:
325
            print(f"Topic: {topic.topic} ({topic.confidence:.2f})")
326

327
if response.results.intents:
328
    for segment in response.results.intents.segments:
329
        for intent in segment.intents:
330
            print(f"Intent: {intent.intent} ({intent.confidence:.2f})")
331

332
if response.results.summary:
333
    print(f"Summary: {response.results.summary.text}")
334
```
335

336
### Sentiment Analysis Only
337

338
```python
339
from deepgram import DeepgramClient, TextSource, AnalyzeOptions
340

341
client = DeepgramClient(api_key="your-api-key")
342

343
# Focus on sentiment analysis
344
reviews = [
345
    "This product exceeded my expectations! Highly recommend.",
346
    "The service was okay, nothing special but not bad either.",
347
    "Very disappointed with the quality. Would not buy again."
348
]
349

350
for i, review in enumerate(reviews):
351
    source = TextSource(review)
352
    options = AnalyzeOptions(sentiment=True)
353
    
354
    response = client.read.analyze.analyze_text(source, options)
355
    
356
    if response.results.sentiments:
357
        sentiment = response.results.sentiments.average
358
        print(f"Review {i+1}: {sentiment.sentiment} ({sentiment.confidence:.2f})")
359
        
360
        # Detailed segment analysis
361
        for segment in response.results.sentiments.segments:
362
            for sent in segment.sentiments:
363
                print(f"  Segment: '{segment.text}' -> {sent.sentiment} ({sent.confidence:.2f})")
364
```
365

366
### Topic Detection
367

368
```python
369
from deepgram import DeepgramClient, TextSource, AnalyzeOptions
370

371
client = DeepgramClient(api_key="your-api-key")
372

373
# Analyze topics in longer content
374
content = """
375
The quarterly financial results show strong performance across all business units.
376
Revenue increased by 15% compared to last quarter, driven primarily by growth in our software division.
377
Customer satisfaction scores remain high, with 92% reporting positive experiences.
378
The marketing team launched several successful campaigns that contributed to brand awareness.
379
Our technology infrastructure investments are paying dividends with improved system reliability.
380
Looking ahead, we're optimistic about market expansion opportunities in the coming year.
381
"""
382

383
source = TextSource(content)
384
options = AnalyzeOptions(
385
    topics=True,
386
    language="en"
387
)
388

389
response = client.read.analyze.analyze_text(source, options)
390

391
if response.results.topics:
392
    print("Detected Topics:")
393
    topics_found = set()
394
    
395
    for segment in response.results.topics.segments:
396
        for topic in segment.topics:
397
            if topic.topic not in topics_found:
398
                topics_found.add(topic.topic)
399
                print(f"- {topic.topic} (confidence: {topic.confidence:.2f})")
400
```
401

402
### Intent Recognition
403

404
```python
405
from deepgram import DeepgramClient, TextSource, AnalyzeOptions
406

407
client = DeepgramClient(api_key="your-api-key")
408

409
# Analyze customer service interactions for intent
410
interactions = [
411
    "I need help with canceling my subscription",
412
    "Can you tell me about your pricing plans?", 
413
    "I want to upgrade my account to the premium tier",
414
    "There's an issue with my recent order, it hasn't arrived yet",
415
    "How do I reset my password?"
416
]
417

418
for interaction in interactions:
419
    source = TextSource(interaction)
420
    options = AnalyzeOptions(intents=True)
421
    
422
    response = client.read.analyze.analyze_text(source, options)
423
    
424
    print(f"Text: '{interaction}'")
425
    
426
    if response.results.intents:
427
        for segment in response.results.intents.segments:
428
            for intent in segment.intents:
429
                print(f"  Intent: {intent.intent} (confidence: {intent.confidence:.2f})")
430
    print()
431
```
432

433
### Text Summarization
434

435
```python
436
from deepgram import DeepgramClient, FileSource, AnalyzeOptions
437

438
client = DeepgramClient(api_key="your-api-key")
439

440
# Summarize content from file
441
source = FileSource("long_article.txt")
442
options = AnalyzeOptions(
443
    summarize=True,
444
    language="en"
445
)
446

447
response = client.read.analyze.analyze_text(source, options)
448

449
if response.results.summary:
450
    print("Summary:")
451
    print(response.results.summary.text)
452
    
453
    if response.results.summary.start_word is not None:
454
        print(f"Summary covers words {response.results.summary.start_word} to {response.results.summary.end_word}")
455
```
456

457
### Async Text Analysis
458

459
```python
460
import asyncio
461
from deepgram import DeepgramClient, TextSource, AnalyzeOptions
462

463
async def async_analysis_example():
464
    client = DeepgramClient(api_key="your-api-key")
465
    
466
    texts = [
467
        "This is the first text to analyze.",
468
        "Here's another piece of content for analysis.",
469
        "And this is the third text sample."
470
    ]
471
    
472
    options = AnalyzeOptions(
473
        sentiment=True,
474
        topics=True,
475
        language="en"
476
    )
477
    
478
    # Analyze multiple texts concurrently
479
    tasks = []
480
    for text in texts:
481
        source = TextSource(text)
482
        task = client.read.asyncanalyze.analyze(source, options)
483
        tasks.append(task)
484
    
485
    responses = await asyncio.gather(*tasks)
486
    
487
    for i, response in enumerate(responses):
488
        print(f"Analysis {i+1}:")
489
        if response.results.sentiments:
490
            sentiment = response.results.sentiments.average
491
            print(f"  Sentiment: {sentiment.sentiment} ({sentiment.confidence:.2f})")
492
        print()
493

494
# Run async example
495
asyncio.run(async_analysis_example())
496
```
497

498
### Custom Models
499

500
```python
501
from deepgram import DeepgramClient, TextSource, AnalyzeOptions
502

503
client = DeepgramClient(api_key="your-api-key")
504

505
# Use custom trained models
506
source = TextSource("Text for analysis with custom models")
507
options = AnalyzeOptions(
508
    intents=True,
509
    topics=True,
510
    custom_intent=["custom-intent-model-id"],
511
    custom_intent_mode="strict",
512
    custom_topic=["custom-topic-model-id"],
513
    custom_topic_mode="extended"
514
)
515

516
response = client.read.analyze.analyze_text(source, options)
517

518
# Process results from custom models
519
if response.results.intents:
520
    print("Custom Intent Results:")
521
    for segment in response.results.intents.segments:
522
        for intent in segment.intents:
523
            print(f"  {intent.intent}: {intent.confidence:.2f}")
524

525
if response.results.topics:
526
    print("Custom Topic Results:")
527
    for segment in response.results.topics.segments:
528
        for topic in segment.topics:
529
            print(f"  {topic.topic}: {topic.confidence:.2f}")
530
```
531

532
### Error Handling
533

534
```python
535
from deepgram import DeepgramClient, DeepgramApiError, TextSource, AnalyzeOptions
536

537
client = DeepgramClient(api_key="your-api-key")
538

539
try:
540
    source = TextSource("Text to analyze")
541
    options = AnalyzeOptions(
542
        sentiment=True,
543
        language="invalid-language-code"  # This may cause an error
544
    )
545
    
546
    response = client.read.analyze.analyze_text(source, options)
547
    
548
    # Process results
549
    if response.results.sentiments:
550
        sentiment = response.results.sentiments.average
551
        print(f"Sentiment: {sentiment.sentiment}")
552
        
553
except DeepgramApiError as e:
554
    print(f"API Error: {e}")
555
except Exception as e:
556
    print(f"Unexpected error: {e}")
557
```