0
# Text Completions
1

2
Legacy text completion API for non-chat models, supporting streaming and all OpenAI-compatible parameters with Portkey enhancements.
3

4
## Capabilities
5

6
### Text Completion Creation
7

8
Generate text completions using prompt-based models with support for streaming, multiple completions, and advanced parameters.
9

10
```python { .api }
11
class Completion:
12
    """Synchronous text completion API"""
13
    
14
    def create(
15
        self,
16
        *,
17
        prompt: Union[str, List[str]],
18
        model: str,
19
        best_of: Optional[int] = None,
20
        echo: Optional[bool] = None,
21
        frequency_penalty: Optional[float] = None,
22
        logit_bias: Optional[dict] = None,
23
        logprobs: Optional[int] = None,
24
        max_tokens: Optional[int] = None,
25
        n: Optional[int] = None,
26
        presence_penalty: Optional[float] = None,
27
        seed: Optional[int] = None,
28
        stop: Union[Optional[str], List[str]] = None,
29
        stream: Optional[bool] = None,
30
        suffix: Optional[str] = None,
31
        temperature: Optional[float] = None,
32
        top_p: Optional[float] = None,
33
        user: Optional[str] = None,
34
        **kwargs
35
    ) -> Union[TextCompletion, Iterator[TextCompletionChunk]]:
36
        """
37
        Create a text completion.
38
        
39
        Parameters:
40
        - prompt: Text prompt or list of prompts
41
        - model: Model identifier (e.g., 'text-davinci-003', 'gpt-3.5-turbo-instruct')
42
        - max_tokens: Maximum tokens to generate
43
        - temperature: Sampling temperature (0-2)
44
        - top_p: Nucleus sampling parameter (0-1)
45
        - n: Number of completions to generate
46
        - stream: Enable streaming responses
47
        - stop: Stop sequences
48
        - presence_penalty: Presence penalty (-2 to 2)
49
        - frequency_penalty: Frequency penalty (-2 to 2)
50
        - best_of: Generate best_of completions server-side and return the best
51
        - echo: Echo back the prompt in addition to the completion
52
        - logprobs: Include log probabilities on the logprobs most likely tokens
53
        - logit_bias: Modify likelihood of specified tokens
54
        - suffix: Suffix that comes after completion of inserted text
55
        - seed: Seed for deterministic generation
56
        - user: User identifier for tracking
57
        
58
        Returns:
59
        TextCompletion object or Iterator of TextCompletionChunk for streaming
60
        """
61

62
class AsyncCompletion:
63
    """Asynchronous text completion API"""
64
    
65
    async def create(
66
        self,
67
        *,
68
        prompt: Union[str, List[str]],
69
        model: str,
70
        **kwargs
71
    ) -> Union[TextCompletion, AsyncIterator[TextCompletionChunk]]:
72
        """Async version of text completion creation"""
73
```
74

75
## Usage Examples
76

77
### Basic Text Completion
78

79
```python
80
from portkey_ai import Portkey
81

82
portkey = Portkey(
83
    api_key="PORTKEY_API_KEY",
84
    virtual_key="VIRTUAL_KEY"
85
)
86

87
# Simple text completion
88
response = portkey.completions.create(
89
    prompt="The future of artificial intelligence is",
90
    model="gpt-3.5-turbo-instruct",
91
    max_tokens=100,
92
    temperature=0.7
93
)
94

95
print(response.choices[0].text)
96
```
97

98
### Multiple Prompts
99

100
```python
101
# Multiple prompts in one request
102
prompts = [
103
    "The capital of France is",
104
    "The largest planet in our solar system is",
105
    "Python is a programming language that"
106
]
107

108
response = portkey.completions.create(
109
    prompt=prompts,
110
    model="gpt-3.5-turbo-instruct",
111
    max_tokens=50,
112
    temperature=0.5
113
)
114

115
for i, choice in enumerate(response.choices):
116
    print(f"Prompt {i+1}: {choice.text.strip()}")
117
```
118

119
### Streaming Completion
120

121
```python
122
# Streaming text completion
123
stream = portkey.completions.create(
124
    prompt="Write a short story about a robot discovering emotions:",
125
    model="gpt-3.5-turbo-instruct",
126
    max_tokens=200,
127
    stream=True
128
)
129

130
for chunk in stream:
131
    if chunk.choices[0].text:
132
        print(chunk.choices[0].text, end="")
133
```
134

135
### Code Completion with Suffix
136

137
```python
138
# Code completion with suffix (fill-in-the-middle)
139
response = portkey.completions.create(
140
    prompt="def calculate_fibonacci(n):\n    if n <= 1:\n        return n\n    else:\n        ",
141
    suffix="\n    return result",
142
    model="gpt-3.5-turbo-instruct",
143
    max_tokens=100,
144
    temperature=0.2
145
)
146

147
print(response.choices[0].text)
148
```
149

150
### Advanced Parameters
151

152
```python
153
# Using advanced parameters
154
response = portkey.completions.create(
155
    prompt="Explain quantum computing in simple terms:",
156
    model="gpt-3.5-turbo-instruct",
157
    max_tokens=150,
158
    temperature=0.8,
159
    top_p=0.9,
160
    frequency_penalty=0.1,
161
    presence_penalty=0.1,
162
    best_of=3,  # Generate 3 completions, return the best
163
    n=1,        # Return 1 completion
164
    echo=True,  # Include the prompt in the response
165
    logprobs=3, # Include log probabilities for top 3 tokens
166
    stop=["\n\n", "###"],  # Stop at double newline or ###
167
    user="user123"
168
)
169

170
print("Full response with prompt:", response.choices[0].text)
171
if response.choices[0].logprobs:
172
    print("Token log probabilities:", response.choices[0].logprobs)
173
```
174

175
### Async Usage
176

177
```python
178
import asyncio
179
from portkey_ai import AsyncPortkey
180

181
async def completion_example():
182
    portkey = AsyncPortkey(
183
        api_key="PORTKEY_API_KEY",
184
        virtual_key="VIRTUAL_KEY"
185
    )
186
    
187
    # Async completion
188
    response = await portkey.completions.create(
189
        prompt="The benefits of renewable energy include:",
190
        model="gpt-3.5-turbo-instruct",
191
        max_tokens=100
192
    )
193
    
194
    print(response.choices[0].text)
195
    
196
    # Async streaming
197
    async for chunk in await portkey.completions.create(
198
        prompt="List the planets in our solar system:",
199
        model="gpt-3.5-turbo-instruct",
200
        max_tokens=100,
201
        stream=True
202
    ):
203
        if chunk.choices[0].text:
204
            print(chunk.choices[0].text, end="")
205

206
asyncio.run(completion_example())
207
```
208

209
### Deterministic Generation
210

211
```python
212
# Reproducible completions with seed
213
response1 = portkey.completions.create(
214
    prompt="Generate a random story idea:",
215
    model="gpt-3.5-turbo-instruct", 
216
    max_tokens=50,
217
    temperature=0.9,
218
    seed=42
219
)
220

221
response2 = portkey.completions.create(
222
    prompt="Generate a random story idea:",
223
    model="gpt-3.5-turbo-instruct",
224
    max_tokens=50, 
225
    temperature=0.9,
226
    seed=42
227
)
228

229
# These should be identical
230
print("Response 1:", response1.choices[0].text)
231
print("Response 2:", response2.choices[0].text)
232
```
233

234
### Logit Bias Control
235

236
```python
237
# Modify token probabilities with logit bias
238
response = portkey.completions.create(
239
    prompt="The weather today is",
240
    model="gpt-3.5-turbo-instruct",
241
    max_tokens=20,
242
    logit_bias={
243
        # Increase likelihood of positive weather words
244
        1180: 2,   # "sunny"
245
        4771: 2,   # "beautiful"
246
        # Decrease likelihood of negative weather words  
247
        21281: -2, # "rainy"
248
        4172: -2   # "cloudy"
249
    }
250
)
251

252
print(response.choices[0].text)
253
```
254

255
## Model Compatibility
256

257
### Supported Models
258

259
Text completions work with various model types:
260

261
```python
262
# GPT-3.5 Instruct models
263
model = "gpt-3.5-turbo-instruct"
264

265
# Legacy GPT-3 models (deprecated)
266
model = "text-davinci-003"
267
model = "text-curie-001" 
268
model = "text-babbage-001"
269
model = "text-ada-001"
270

271
# Code-specific models
272
model = "code-davinci-002"
273
model = "code-cushman-001"
274

275
# Provider-specific models through Portkey
276
model = "anthropic/claude-instant-1"
277
model = "cohere/command"
278
model = "huggingface/gpt2"
279
```
280

281
### Migration from Legacy Models
282

283
```python
284
# Old GPT-3 usage
285
response = portkey.completions.create(
286
    prompt="Translate to French: Hello, how are you?",
287
    model="text-davinci-003",
288
    max_tokens=60
289
)
290

291
# Recommended migration to GPT-3.5 Instruct
292
response = portkey.completions.create(
293
    prompt="Translate to French: Hello, how are you?", 
294
    model="gpt-3.5-turbo-instruct",
295
    max_tokens=60
296
)
297

298
# Or better: migrate to chat completions
299
response = portkey.chat.completions.create(
300
    messages=[
301
        {"role": "user", "content": "Translate to French: Hello, how are you?"}
302
    ],
303
    model="gpt-3.5-turbo",
304
    max_tokens=60
305
)
306
```
307

308
## Common Use Cases
309

310
### Text Generation
311

312
```python
313
# Creative writing
314
response = portkey.completions.create(
315
    prompt="Write a haiku about programming:",
316
    model="gpt-3.5-turbo-instruct",
317
    max_tokens=30,
318
    temperature=0.8
319
)
320

321
# Technical documentation
322
response = portkey.completions.create(
323
    prompt="Function documentation for bubble sort algorithm:",
324
    model="gpt-3.5-turbo-instruct", 
325
    max_tokens=100,
326
    temperature=0.3
327
)
328
```
329

330
### Code Completion
331

332
```python
333
# Python function completion
334
response = portkey.completions.create(
335
    prompt="def merge_sort(arr):\n    if len(arr) <= 1:\n        return arr\n    \n    mid = len(arr) // 2\n    left = arr[:mid]\n    right = arr[mid:]\n    \n    ",
336
    model="gpt-3.5-turbo-instruct",
337
    max_tokens=200,
338
    temperature=0.2,
339
    stop=["\n\n"]
340
)
341
```
342

343
### Data Processing
344

345
```python
346
# Text classification
347
response = portkey.completions.create(
348
    prompt="Classify the sentiment of this text as positive, negative, or neutral:\n\n\"I absolutely love this new restaurant! The food was amazing.\"\n\nSentiment:",
349
    model="gpt-3.5-turbo-instruct",
350
    max_tokens=10,
351
    temperature=0
352
)
353
```