0
# Text Completion
1

2
Generate text continuations with extensive sampling controls, multiple completions, and streaming support. Provides comprehensive control over text generation including temperature, top-k/top-p sampling, penalties, and stopping conditions.
3

4
## Capabilities
5

6
### Completion Requests
7

8
Configure text generation parameters with fine-grained control over sampling behavior and output formatting.
9

10
```python { .api }
11
class CompletionRequest:
12
    prompt: Prompt
13
    maximum_tokens: Optional[int] = None
14
    temperature: float = 0.0
15
    top_k: int = 0
16
    top_p: float = 0.0
17
    presence_penalty: float = 0.0
18
    frequency_penalty: float = 0.0
19
    stop_sequences: Optional[List[str]] = None
20
    n: int = 1
21
    best_of: Optional[int] = None
22
    log_probs: Optional[int] = None
23
    echo: bool = False
24
    steering_concepts: Optional[List[str]] = None
25
    """
26
    Request configuration for text completion.
27
    
28
    Attributes:
29
    - prompt: Input prompt (multimodal supported)
30
    - maximum_tokens: Maximum tokens to generate
31
    - temperature: Sampling temperature (0.0 = deterministic, higher = more random)
32
    - top_k: Top-k sampling (0 = disabled)
33
    - top_p: Top-p/nucleus sampling (0.0 = disabled)
34
    - presence_penalty: Penalty for token presence (-2.0 to 2.0)
35
    - frequency_penalty: Penalty for token frequency (-2.0 to 2.0)
36
    - stop_sequences: Sequences that stop generation
37
    - n: Number of completions to generate
38
    - best_of: Generate best_of completions, return top n
39
    - log_probs: Number of log probabilities to return per token
40
    - echo: Include prompt in response
41
    - steering_concepts: Concept IDs for content steering
42
    """
43

44
    def to_json(self) -> Mapping[str, Any]:
45
        """Serialize request to JSON format."""
46
```
47

48
### Completion Responses
49

50
Structured response containing generated completions with metadata and usage statistics.
51

52
```python { .api }
53
class CompletionResponse:
54
    model_version: str
55
    completions: Sequence[CompletionResult]
56
    num_tokens_prompt_total: int
57
    num_tokens_generated: int
58
    optimized_prompt: Optional[Prompt] = None
59
    """
60
    Response from completion request.
61
    
62
    Attributes:
63
    - model_version: Version of model used for generation
64
    - completions: Generated completion results
65
    - num_tokens_prompt_total: Total tokens in prompt
66
    - num_tokens_generated: Total tokens generated
67
    - optimized_prompt: Optimized version of input prompt (if applicable)
68
    """
69

70
    @staticmethod
71
    def from_json(json: Dict[str, Any]) -> CompletionResponse:
72
        """Create response from JSON data."""
73
```
74

75
### Individual Completion Results
76

77
Detailed results for each generated completion including log probabilities and finish reasons.
78

79
```python { .api }
80
class CompletionResult:
81
    log_probs: Optional[Sequence[Mapping[str, Optional[float]]]] = None
82
    completion: Optional[str] = None
83
    completion_tokens: Optional[Sequence[str]] = None
84
    finish_reason: Optional[str] = None
85
    raw_completion: Optional[str] = None
86
    """
87
    Individual completion result.
88
    
89
    Attributes:
90
    - log_probs: Log probabilities for each token (if requested)
91
    - completion: Generated text completion
92
    - completion_tokens: Individual tokens in completion
93
    - finish_reason: Reason generation stopped ("stop", "length", etc.)
94
    - raw_completion: Unprocessed completion text
95
    """
96
```
97

98
### Synchronous Completion
99

100
Generate completions using the synchronous client with full parameter control.
101

102
```python { .api }
103
def complete(self, request: CompletionRequest, model: str) -> CompletionResponse:
104
    """
105
    Generate text completion.
106
    
107
    Parameters:
108
    - request: Completion configuration
109
    - model: Model name to use for generation
110
    
111
    Returns:
112
    CompletionResponse with generated completions
113
    """
114
```
115

116
### Asynchronous Completion
117

118
Generate completions asynchronously with optional streaming support.
119

120
```python { .api }
121
async def complete(self, request: CompletionRequest, model: str) -> CompletionResponse:
122
    """
123
    Generate text completion (async).
124
    
125
    Parameters:
126
    - request: Completion configuration  
127
    - model: Model name to use for generation
128
    
129
    Returns:
130
    CompletionResponse with generated completions
131
    """
132

133
async def complete_with_streaming(
134
    self, 
135
    request: CompletionRequest, 
136
    model: str
137
) -> AsyncGenerator[CompletionResponseStreamItem, None]:
138
    """
139
    Generate completion with streaming results.
140
    
141
    Parameters:
142
    - request: Completion configuration
143
    - model: Model name to use for generation
144
    
145
    Yields:
146
    Stream items containing partial completions and final summary
147
    """
148
```
149

150
### Streaming Components
151

152
Data structures for handling streaming completion responses.
153

154
```python { .api }
155
class StreamChunk:
156
    index: int
157
    log_probs: Optional[Sequence[Mapping[str, Optional[float]]]]
158
    completion: str
159
    raw_completion: Optional[str]
160
    completion_tokens: Optional[Sequence[str]]
161
    """
162
    Chunk of streaming completion data.
163
    
164
    Attributes:
165
    - index: Stream index for multiple completions
166
    - log_probs: Log probabilities for chunk tokens
167
    - completion: Text chunk
168
    - raw_completion: Unprocessed text chunk
169
    - completion_tokens: Tokens in this chunk
170
    """
171

172
class StreamSummary:
173
    index: int
174
    model_version: str
175
    finish_reason: str
176
    """
177
    End-of-stream marker for individual completion.
178
    
179
    Attributes:
180
    - index: Stream index
181
    - model_version: Model version used
182
    - finish_reason: Why generation stopped
183
    """
184

185
class CompletionSummary:
186
    optimized_prompt: Optional[Prompt]
187
    num_tokens_prompt_total: int
188
    num_tokens_generated: int
189
    """
190
    Final summary after all streams complete.
191
    
192
    Attributes:
193
    - optimized_prompt: Optimized input prompt
194
    - num_tokens_prompt_total: Total prompt tokens
195
    - num_tokens_generated: Total generated tokens
196
    """
197
```
198

199
### Usage Examples
200

201
Basic text completion with various configurations:
202

203
```python
204
from aleph_alpha_client import Client, CompletionRequest, Prompt
205

206
client = Client(token="your-api-token")
207

208
# Simple completion
209
request = CompletionRequest(
210
    prompt=Prompt.from_text("The future of AI is"),
211
    maximum_tokens=50,
212
    temperature=0.7
213
)
214
response = client.complete(request, model="luminous-extended")
215
print(response.completions[0].completion)
216

217
# Advanced completion with multiple results
218
request = CompletionRequest(
219
    prompt=Prompt.from_text("Write a creative story about:"),
220
    maximum_tokens=200,
221
    temperature=0.8,
222
    top_p=0.9,
223
    n=3,  # Generate 3 completions
224
    stop_sequences=["\n\n", "THE END"],
225
    presence_penalty=0.1,
226
    frequency_penalty=0.1
227
)
228
response = client.complete(request, model="luminous-extended")
229

230
for i, completion in enumerate(response.completions):
231
    print(f"Completion {i+1}: {completion.completion}")
232
    print(f"Finish reason: {completion.finish_reason}")
233

234
# Completion with log probabilities
235
request = CompletionRequest(
236
    prompt=Prompt.from_text("The capital of France is"),
237
    maximum_tokens=10,
238
    temperature=0.0,  # Deterministic
239
    log_probs=5,  # Top 5 log probs per token
240
    echo=True  # Include prompt in response
241
)
242
response = client.complete(request, model="luminous-extended")
243

244
completion = response.completions[0]
245
if completion.log_probs:
246
    for token_logprobs in completion.log_probs:
247
        print(f"Token probabilities: {token_logprobs}")
248

249
# Streaming completion (async)
250
import asyncio
251

252
async def streaming_completion():
253
    async with AsyncClient(token="your-api-token") as client:
254
        request = CompletionRequest(
255
            prompt=Prompt.from_text("Write a long story about space exploration:"),
256
            maximum_tokens=500,
257
            temperature=0.7
258
        )
259
        
260
        async for item in client.complete_with_streaming(request, "luminous-extended"):
261
            if isinstance(item, StreamChunk):
262
                print(item.completion, end="", flush=True)
263
            elif isinstance(item, StreamSummary):
264
                print(f"\nStream {item.index} finished: {item.finish_reason}")
265
            elif isinstance(item, CompletionSummary):
266
                print(f"Total tokens generated: {item.num_tokens_generated}")
267

268
asyncio.run(streaming_completion())
269

270
# Multimodal completion
271
from aleph_alpha_client import Image
272

273
image = Image.from_file("image.jpg")
274
multimodal_prompt = Prompt([
275
    Text.from_text("Describe this image in detail:"),
276
    image
277
])
278

279
request = CompletionRequest(
280
    prompt=multimodal_prompt,
281
    maximum_tokens=150,
282
    temperature=0.5
283
)
284
response = client.complete(request, model="luminous-extended")
285
print(response.completions[0].completion)
286
```