0
# Text Generation
1

2
Large language model integrations for text generation, chat completions, and answer synthesis. Supports multiple providers including OpenAI, Azure OpenAI, and HuggingFace models.
3

4
## Capabilities
5

6
### OpenAI Text Generation
7

8
Generate text using OpenAI's GPT models for completion tasks and answer synthesis.
9

10
```python { .api }
11
class OpenAIGenerator:
12
    def __init__(
13
        self,
14
        api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
15
        model: str = "gpt-4o-mini",
16
        streaming_callback: Optional[StreamingCallbackT] = None,
17
        api_base_url: Optional[str] = None,
18
        organization: Optional[str] = None,
19
        system_prompt: Optional[str] = None,
20
        generation_kwargs: Optional[Dict[str, Any]] = None,
21
        timeout: Optional[float] = None,
22
        max_retries: Optional[int] = None,
23
        http_client_kwargs: Optional[Dict[str, Any]] = None
24
    ) -> None:
25
        """
26
        Initialize OpenAI text generator using chat completion API.
27
        
28
        Args:
29
            api_key: OpenAI API key (defaults to OPENAI_API_KEY env var)
30
            model: OpenAI model name (defaults to gpt-4o-mini)
31
            streaming_callback: Callback for streaming responses
32
            api_base_url: Custom API base URL
33
            organization: OpenAI organization ID
34
            system_prompt: Default system prompt
35
            generation_kwargs: Additional generation parameters
36
            timeout: Request timeout in seconds
37
            max_retries: Maximum number of retries
38
            http_client_kwargs: HTTP client configuration
39
        """
40

41
    def run(
42
        self,
43
        prompt: str,
44
        system_prompt: Optional[str] = None,
45
        streaming_callback: Optional[StreamingCallbackT] = None,
46
        generation_kwargs: Optional[Dict[str, Any]] = None
47
    ) -> Dict[str, List[str]]:
48
        """
49
        Generate text using the OpenAI chat completion API.
50
        
51
        Args:
52
            prompt: Text prompt for generation
53
            system_prompt: System prompt (overrides default if provided)
54
            streaming_callback: Callback for streaming responses
55
            generation_kwargs: Additional generation parameters
56
            
57
        Returns:
58
            Dictionary with 'replies' key containing list of generated texts
59
            and 'meta' key containing response metadata
60
        """
61

62
class AzureOpenAIGenerator:
63
    def __init__(
64
        self,
65
        azure_endpoint: str,
66
        api_version: str,
67
        api_key: Secret = None,
68
        azure_ad_token: Secret = None,
69
        model: str = "gpt-35-turbo-instruct",
70
        max_tokens: Optional[int] = None,
71
        temperature: float = 1.0,
72
        top_p: float = 1.0,
73
        n: int = 1,
74
        stop: Optional[List[str]] = None,
75
        presence_penalty: float = 0.0,
76
        frequency_penalty: float = 0.0
77
    ) -> None:
78
        """
79
        Initialize Azure OpenAI text generator.
80
        
81
        Args:
82
            azure_endpoint: Azure OpenAI endpoint URL
83
            api_version: Azure OpenAI API version
84
            api_key: Azure OpenAI API key
85
            azure_ad_token: Azure AD token for authentication
86
            model: Deployment name of the model
87
            max_tokens: Maximum tokens to generate
88
            temperature: Sampling temperature
89
            top_p: Nucleus sampling parameter
90
            n: Number of completions to generate
91
            stop: Stop sequences
92
            presence_penalty: Presence penalty
93
            frequency_penalty: Frequency penalty
94
        """
95

96
    def run(
97
        self,
98
        prompt: str,
99
        generation_kwargs: Optional[Dict[str, Any]] = None
100
    ) -> Dict[str, List[str]]:
101
        """Generate text using Azure OpenAI."""
102
```
103

104
### OpenAI Chat Generation
105

106
Generate conversational responses using OpenAI's chat models with support for function calling and streaming.
107

108
```python { .api }
109
class OpenAIChatGenerator:
110
    def __init__(
111
        self,
112
        api_key: Secret = None,
113
        model: str = "gpt-3.5-turbo",
114
        max_tokens: Optional[int] = None,
115
        temperature: float = 1.0,
116
        top_p: float = 1.0,
117
        n: int = 1,
118
        stop: Optional[List[str]] = None,
119
        presence_penalty: float = 0.0,
120
        frequency_penalty: float = 0.0,
121
        tools: Optional[List[Tool]] = None,
122
        tool_choice: Optional[Union[str, Dict[str, str]]] = None,
123
        streaming_callback: Optional[Callable[[StreamingChunk], None]] = None
124
    ) -> None:
125
        """
126
        Initialize OpenAI chat generator.
127
        
128
        Args:
129
            api_key: OpenAI API key
130
            model: OpenAI model name
131
            max_tokens: Maximum tokens to generate
132
            temperature: Sampling temperature
133
            top_p: Nucleus sampling parameter
134
            n: Number of chat completion choices
135
            stop: Stop sequences
136
            presence_penalty: Presence penalty
137
            frequency_penalty: Frequency penalty
138
            tools: List of tools available for function calling
139
            tool_choice: How the model should choose tools
140
            streaming_callback: Callback for streaming responses
141
        """
142

143
    def run(
144
        self,
145
        messages: List[ChatMessage],
146
        generation_kwargs: Optional[Dict[str, Any]] = None
147
    ) -> Dict[str, List[ChatMessage]]:
148
        """
149
        Generate chat completions for the given messages.
150
        
151
        Args:
152
            messages: List of chat messages
153
            generation_kwargs: Additional generation parameters
154
            
155
        Returns:
156
            Dictionary with 'replies' key containing list of ChatMessage responses
157
        """
158

159
class AzureOpenAIChatGenerator:
160
    def __init__(
161
        self,
162
        azure_endpoint: str,
163
        api_version: str,
164
        api_key: Secret = None,
165
        azure_ad_token: Secret = None,
166
        model: str = "gpt-35-turbo",
167
        max_tokens: Optional[int] = None,
168
        temperature: float = 1.0,
169
        top_p: float = 1.0,
170
        n: int = 1,
171
        stop: Optional[List[str]] = None,
172
        presence_penalty: float = 0.0,
173
        frequency_penalty: float = 0.0,
174
        tools: Optional[List[Tool]] = None,
175
        tool_choice: Optional[Union[str, Dict[str, str]]] = None,
176
        streaming_callback: Optional[Callable[[StreamingChunk], None]] = None
177
    ) -> None:
178
        """Initialize Azure OpenAI chat generator."""
179

180
    def run(
181
        self,
182
        messages: List[ChatMessage],
183
        generation_kwargs: Optional[Dict[str, Any]] = None
184
    ) -> Dict[str, List[ChatMessage]]:
185
        """Generate chat completions using Azure OpenAI."""
186
```
187

188
### HuggingFace Generation
189

190
Generate text using HuggingFace transformer models, both locally and via API.
191

192
```python { .api }
193
class HuggingFaceLocalGenerator:
194
    def __init__(
195
        self,
196
        model: str = "gpt2",
197
        task: Optional[str] = None,
198
        device: Optional[ComponentDevice] = None,
199
        token: Secret = None,
200
        generation_kwargs: Optional[Dict[str, Any]] = None,
201
        huggingface_pipeline_kwargs: Optional[Dict[str, Any]] = None,
202
        stop_words: Optional[List[str]] = None,
203
        streaming_callback: Optional[Callable[[StreamingChunk], None]] = None
204
    ) -> None:
205
        """
206
        Initialize HuggingFace local generator.
207
        
208
        Args:
209
            model: HuggingFace model name or path
210
            task: Task type (text-generation, text2text-generation)
211
            device: Device for model inference
212
            token: HuggingFace token for private models
213
            generation_kwargs: Generation parameters
214
            huggingface_pipeline_kwargs: Pipeline initialization parameters
215
            stop_words: Stop words for generation
216
            streaming_callback: Callback for streaming responses
217
        """
218

219
    def run(
220
        self,
221
        prompt: str,
222
        generation_kwargs: Optional[Dict[str, Any]] = None
223
    ) -> Dict[str, List[str]]:
224
        """
225
        Generate text using local HuggingFace model.
226
        
227
        Args:
228
            prompt: Input prompt for generation
229
            generation_kwargs: Additional generation parameters
230
            
231
        Returns:
232
            Dictionary with 'replies' key containing generated texts
233
        """
234

235
class HuggingFaceAPIGenerator:
236
    def __init__(
237
        self,
238
        api_type: Literal["serverless_inference_api", "inference_endpoints"] = "serverless_inference_api",
239
        api_url: Optional[str] = None,
240
        token: Secret = None,
241
        model: Optional[str] = None,
242
        max_tokens: Optional[int] = None,
243
        top_k: Optional[int] = None,
244
        top_p: Optional[float] = None,
245
        temperature: Optional[float] = None,
246
        repetition_penalty: Optional[float] = None,
247
        stop_sequences: Optional[List[str]] = None,
248
        streaming_callback: Optional[Callable[[StreamingChunk], None]] = None
249
    ) -> None:
250
        """
251
        Initialize HuggingFace API generator.
252
        
253
        Args:
254
            api_type: Type of HuggingFace API to use
255
            api_url: Custom API endpoint URL
256
            token: HuggingFace API token
257
            model: Model name for serverless inference
258
            max_tokens: Maximum tokens to generate
259
            top_k: Top-k sampling parameter
260
            top_p: Top-p sampling parameter
261
            temperature: Sampling temperature
262
            repetition_penalty: Repetition penalty
263
            stop_sequences: Stop sequences
264
            streaming_callback: Callback for streaming responses
265
        """
266

267
    def run(
268
        self,
269
        prompt: str,
270
        generation_kwargs: Optional[Dict[str, Any]] = None
271
    ) -> Dict[str, List[str]]:
272
        """Generate text using HuggingFace API."""
273

274
class HuggingFaceLocalChatGenerator:
275
    def __init__(
276
        self,
277
        model: str = "microsoft/DialoGPT-medium",
278
        device: Optional[ComponentDevice] = None,
279
        token: Secret = None,
280
        generation_kwargs: Optional[Dict[str, Any]] = None,
281
        huggingface_pipeline_kwargs: Optional[Dict[str, Any]] = None,
282
        stop_words: Optional[List[str]] = None,
283
        streaming_callback: Optional[Callable[[StreamingChunk], None]] = None
284
    ) -> None:
285
        """Initialize HuggingFace local chat generator."""
286

287
    def run(
288
        self,
289
        messages: List[ChatMessage],
290
        generation_kwargs: Optional[Dict[str, Any]] = None
291
    ) -> Dict[str, List[ChatMessage]]:
292
        """Generate chat responses using local HuggingFace model."""
293

294
class HuggingFaceAPIChatGenerator:
295
    def __init__(
296
        self,
297
        api_type: Literal["serverless_inference_api", "inference_endpoints"] = "serverless_inference_api",
298
        api_url: Optional[str] = None,
299
        token: Secret = None,
300
        model: Optional[str] = None,
301
        max_tokens: Optional[int] = None,
302
        top_k: Optional[int] = None,
303
        top_p: Optional[float] = None,
304
        temperature: Optional[float] = None,
305
        repetition_penalty: Optional[float] = None,
306
        stop_sequences: Optional[List[str]] = None,
307
        streaming_callback: Optional[Callable[[StreamingChunk], None]] = None
308
    ) -> None:
309
        """Initialize HuggingFace API chat generator."""
310

311
    def run(
312
        self,
313
        messages: List[ChatMessage],
314
        generation_kwargs: Optional[Dict[str, Any]] = None
315
    ) -> Dict[str, List[ChatMessage]]:
316
        """Generate chat responses using HuggingFace API."""
317
```
318

319
### Image Generation
320

321
Generate images using DALL-E models.
322

323
```python { .api }
324
class DALLEImageGenerator:
325
    def __init__(
326
        self,
327
        api_key: Secret = None,
328
        model: str = "dall-e-2",
329
        size: Literal["256x256", "512x512", "1024x1024", "1792x1024", "1024x1792"] = "1024x1024",
330
        quality: Literal["standard", "hd"] = "standard",
331
        n: int = 1,
332
        response_format: Literal["url", "b64_json"] = "url",
333
        style: Optional[Literal["vivid", "natural"]] = None
334
    ) -> None:
335
        """
336
        Initialize DALL-E image generator.
337
        
338
        Args:
339
            api_key: OpenAI API key
340
            model: DALL-E model name
341
            size: Image size
342
            quality: Image quality
343
            n: Number of images to generate
344
            response_format: Response format
345
            style: Image style (DALL-E 3 only)
346
        """
347

348
    def run(
349
        self,
350
        prompt: str,
351
        generation_kwargs: Optional[Dict[str, Any]] = None
352
    ) -> Dict[str, List[ByteStream]]:
353
        """
354
        Generate images from text prompt.
355
        
356
        Args:
357
            prompt: Text description of desired image
358
            generation_kwargs: Additional generation parameters
359
            
360
        Returns:
361
            Dictionary with 'images' key containing list of generated images
362
        """
363
```
364

365
## Usage Examples
366

367
### Basic Text Generation
368

369
```python
370
from haystack.components.generators import OpenAIGenerator
371
from haystack.utils import Secret
372

373
# Initialize generator
374
generator = OpenAIGenerator(
375
    api_key=Secret.from_env_var("OPENAI_API_KEY"),
376
    model="gpt-3.5-turbo-instruct",
377
    max_tokens=100
378
)
379

380
# Generate text
381
result = generator.run(prompt="Explain quantum computing in simple terms.")
382
print(result["replies"][0])
383
```
384

385
### Chat Completion with Function Calling
386

387
```python
388
from haystack.components.generators.chat import OpenAIChatGenerator
389
from haystack.dataclasses import ChatMessage, ChatRole
390
from haystack.tools import Tool
391

392
# Define a tool
393
def get_weather(location: str) -> str:
394
    """Get weather for a location."""
395
    return f"Weather in {location}: Sunny, 22°C"
396

397
weather_tool = Tool.from_function(get_weather)
398

399
# Initialize chat generator with tools
400
chat_generator = OpenAIChatGenerator(
401
    api_key=Secret.from_env_var("OPENAI_API_KEY"),
402
    model="gpt-3.5-turbo",
403
    tools=[weather_tool]
404
)
405

406
# Create messages
407
messages = [
408
    ChatMessage(content="What's the weather like in Paris?", role=ChatRole.USER)
409
]
410

411
# Generate response
412
result = chat_generator.run(messages=messages)
413
response_message = result["replies"][0]
414

415
print(f"Assistant: {response_message.content}")
416

417
# If the model made a tool call, execute it
418
if response_message.tool_calls:
419
    for tool_call in response_message.tool_calls:
420
        if tool_call.tool_name == "get_weather":
421
            weather_result = get_weather(**tool_call.arguments)
422
            print(f"Weather result: {weather_result}")
423
```
424

425
### Streaming Generation
426

427
```python
428
from haystack.components.generators.chat import OpenAIChatGenerator
429
from haystack.dataclasses import ChatMessage, ChatRole, StreamingChunk
430

431
def streaming_callback(chunk: StreamingChunk) -> None:
432
    """Handle streaming chunks."""
433
    if chunk.content:
434
        print(chunk.content, end="", flush=True)
435

436
# Initialize generator with streaming
437
chat_generator = OpenAIChatGenerator(
438
    api_key=Secret.from_env_var("OPENAI_API_KEY"),
439
    model="gpt-3.5-turbo",
440
    streaming_callback=streaming_callback
441
)
442

443
messages = [
444
    ChatMessage(content="Write a short story about AI.", role=ChatRole.USER)
445
]
446

447
result = chat_generator.run(messages=messages)
448
```
449

450
## Types
451

452
```python { .api }
453
from typing import Literal, Optional, Dict, Any, List, Callable, Union
454
from haystack.dataclasses import ChatMessage, StreamingChunk, ByteStream
455
from haystack.tools import Tool
456
from haystack.utils import Secret, ComponentDevice
457

458
class FinishReason(Enum):
459
    STOP = "stop"
460
    LENGTH = "length"
461
    TOOL_CALLS = "tool_calls"
462
    CONTENT_FILTER = "content_filter"
463
```