0
# File Management
1

2
File upload, listing, retrieval, and deletion operations for fine-tuning datasets, batch processing workflows, and data management. Supports various file formats and provides comprehensive file metadata and content access.
3

4
## Capabilities
5

6
### File Upload
7

8
Upload files for fine-tuning and batch processing operations.
9

10
```python { .api }
11
def upload(
12
    file: str,
13
    purpose: Optional[str] = None
14
) -> FileResponse:
15
    """
16
    Upload a file for use with fine-tuning or batch processing.
17

18
    Args:
19
        file: Path to the file to upload
20
        purpose: File purpose ('fine-tune', 'batch-api', etc.)
21

22
    Returns:
23
        FileResponse with file metadata
24
    """
25
```
26

27
### File Listing
28

29
List all uploaded files with metadata and filtering options.
30

31
```python { .api }
32
def list() -> FileList:
33
    """
34
    List all uploaded files.
35

36
    Returns:
37
        FileList containing file objects
38
    """
39
```
40

41
### File Retrieval
42

43
Retrieve metadata and content for specific files.
44

45
```python { .api }
46
def retrieve(id: str) -> FileObject:
47
    """
48
    Retrieve file metadata by ID.
49

50
    Args:
51
        id: File identifier
52

53
    Returns:
54
        FileObject with file metadata
55
    """
56

57
def retrieve_content(
58
    id: str,
59
    output: Optional[str] = None
60
) -> str:
61
    """
62
    Retrieve file content by ID.
63

64
    Args:
65
        id: File identifier
66
        output: Optional output file path
67

68
    Returns:
69
        File content as string
70
    """
71
```
72

73
### File Deletion
74

75
Delete uploaded files to manage storage and cleanup.
76

77
```python { .api }
78
def delete(id: str) -> FileDeleteResponse:
79
    """
80
    Delete a file by ID.
81

82
    Args:
83
        id: File identifier
84

85
    Returns:
86
        FileDeleteResponse confirming deletion
87
    """
88
```
89

90
### Async File Operations
91

92
All file operations support asynchronous execution for concurrent processing.
93

94
```python { .api }
95
async def upload(file: str, purpose: Optional[str] = None) -> FileResponse: ...
96
async def list() -> FileList: ...
97
async def retrieve(id: str) -> FileObject: ...
98
async def retrieve_content(id: str, output: Optional[str] = None) -> str: ...
99
async def delete(id: str) -> FileDeleteResponse: ...
100
```
101

102
## Usage Examples
103

104
### Basic File Upload
105

106
```python
107
from together import Together
108

109
client = Together()
110

111
# Upload a fine-tuning dataset
112
response = client.files.upload(
113
    file="training_data.jsonl",
114
    purpose="fine-tune"
115
)
116

117
print(f"Uploaded file ID: {response.id}")
118
print(f"File name: {response.filename}")
119
print(f"File size: {response.bytes} bytes")
120
print(f"Purpose: {response.purpose}")
121
```
122

123
### List All Files
124

125
```python
126
file_list = client.files.list()
127

128
print(f"Total files: {len(file_list.data)}")
129

130
for file_obj in file_list.data:
131
    print(f"ID: {file_obj.id}")
132
    print(f"Name: {file_obj.filename}")
133
    print(f"Size: {file_obj.bytes} bytes")
134
    print(f"Purpose: {file_obj.purpose}")
135
    print(f"Created: {file_obj.created_at}")
136
    print("---")
137
```
138

139
### Retrieve File Information
140

141
```python
142
file_id = "file-d0d318cb-b7d9-493a-bd70-1cfe089d3815"
143

144
# Get file metadata
145
file_obj = client.files.retrieve(file_id)
146
print(f"File: {file_obj.filename}")
147
print(f"Status: {file_obj.status}")
148
print(f"Size: {file_obj.bytes} bytes")
149

150
# Get file content
151
content = client.files.retrieve_content(file_id)
152
print(f"Content preview: {content[:200]}...")
153
```
154

155
### Download File Content
156

157
```python
158
file_id = "file-d0d318cb-b7d9-493a-bd70-1cfe089d3815"
159

160
# Download to local file
161
content = client.files.retrieve_content(
162
    id=file_id,
163
    output="downloaded_file.jsonl"
164
)
165

166
print(f"File downloaded to: downloaded_file.jsonl")
167
print(f"Content size: {len(content)} characters")
168
```
169

170
### File Management Workflow
171

172
```python
173
import json
174
import os
175

176
def prepare_fine_tuning_data(conversations: list, output_file: str):
177
    """Prepare conversation data for fine-tuning."""
178
    with open(output_file, 'w') as f:
179
        for conversation in conversations:
180
            training_example = {
181
                "messages": conversation["messages"],
182
                "model": "meta-llama/Llama-3.2-3B-Instruct"
183
            }
184
            f.write(json.dumps(training_example) + '\n')
185
    
186
    return output_file
187

188
def upload_and_track_file(client: Together, file_path: str, purpose: str = "fine-tune"):
189
    """Upload file and return tracking information."""
190
    response = client.files.upload(file=file_path, purpose=purpose)
191
    
192
    tracking_info = {
193
        "file_id": response.id,
194
        "filename": response.filename,
195
        "size_bytes": response.bytes,
196
        "purpose": response.purpose,
197
        "status": response.status,
198
        "local_path": file_path
199
    }
200
    
201
    return tracking_info
202

203
# Example usage
204
sample_conversations = [
205
    {
206
        "messages": [
207
            {"role": "user", "content": "What is Python?"},
208
            {"role": "assistant", "content": "Python is a high-level programming language..."}
209
        ]
210
    },
211
    {
212
        "messages": [
213
            {"role": "user", "content": "Explain machine learning"},
214
            {"role": "assistant", "content": "Machine learning is a subset of AI..."}
215
        ]
216
    }
217
]
218

219
# Prepare and upload training data
220
data_file = prepare_fine_tuning_data(sample_conversations, "training_data.jsonl")
221
file_info = upload_and_track_file(client, data_file)
222

223
print(f"Training file uploaded: {file_info['file_id']}")
224
print(f"Ready for fine-tuning with file: {file_info['filename']}")
225
```
226

227
### Batch File Processing
228

229
```python
230
def upload_multiple_files(client: Together, file_paths: list, purpose: str = "batch-api"):
231
    """Upload multiple files and return their IDs."""
232
    uploaded_files = []
233
    
234
    for file_path in file_paths:
235
        if os.path.exists(file_path):
236
            response = client.files.upload(file=file_path, purpose=purpose)
237
            uploaded_files.append({
238
                "file_id": response.id,
239
                "filename": response.filename,
240
                "local_path": file_path,
241
                "size": response.bytes
242
            })
243
            print(f"Uploaded: {response.filename} ({response.id})")
244
        else:
245
            print(f"File not found: {file_path}")
246
    
247
    return uploaded_files
248

249
# Upload batch processing files
250
batch_files = [
251
    "batch_input_1.jsonl",
252
    "batch_input_2.jsonl", 
253
    "batch_input_3.jsonl"
254
]
255

256
uploaded = upload_multiple_files(client, batch_files, "batch-api")
257
print(f"Successfully uploaded {len(uploaded)} files for batch processing")
258
```
259

260
### File Cleanup
261

262
```python
263
def cleanup_old_files(client: Together, days_old: int = 30):
264
    """Delete files older than specified days."""
265
    import time
266
    
267
    current_time = int(time.time())
268
    cutoff_time = current_time - (days_old * 24 * 60 * 60)
269
    
270
    file_list = client.files.list()
271
    deleted_files = []
272
    
273
    for file_obj in file_list.data:
274
        if file_obj.created_at < cutoff_time:
275
            try:
276
                client.files.delete(file_obj.id)
277
                deleted_files.append(file_obj.filename)
278
                print(f"Deleted: {file_obj.filename}")
279
            except Exception as e:
280
                print(f"Failed to delete {file_obj.filename}: {e}")
281
    
282
    return deleted_files
283

284
# Clean up files older than 30 days
285
deleted = cleanup_old_files(client, days_old=30)
286
print(f"Cleaned up {len(deleted)} old files")
287
```
288

289
### Async File Operations
290

291
```python
292
import asyncio
293
from together import AsyncTogether
294

295
async def async_file_operations():
296
    client = AsyncTogether()
297
    
298
    # Upload files concurrently
299
    file_paths = ["data1.jsonl", "data2.jsonl", "data3.jsonl"]
300
    
301
    upload_tasks = [
302
        client.files.upload(file=path, purpose="fine-tune")
303
        for path in file_paths
304
        if os.path.exists(path)
305
    ]
306
    
307
    uploaded_files = await asyncio.gather(*upload_tasks, return_exceptions=True)
308
    
309
    # Process results
310
    successful_uploads = []
311
    for i, result in enumerate(uploaded_files):
312
        if isinstance(result, Exception):
313
            print(f"Failed to upload {file_paths[i]}: {result}")
314
        else:
315
            successful_uploads.append(result)
316
            print(f"Uploaded: {result.filename} ({result.id})")
317
    
318
    return successful_uploads
319

320
# Run async file operations
321
uploaded_files = asyncio.run(async_file_operations())
322
```
323

324
## Types
325

326
### Request Types
327

328
```python { .api }
329
class FileRequest:
330
    file: str
331
    purpose: Optional[str] = None
332
```
333

334
### Response Types
335

336
```python { .api }
337
class FileResponse:
338
    id: str
339
    object: str
340
    bytes: int
341
    created_at: int
342
    filename: str
343
    purpose: str
344
    status: str
345
    status_details: Optional[str] = None
346

347
class FileObject:
348
    id: str
349
    object: str
350
    bytes: int
351
    created_at: int
352
    filename: str
353
    purpose: str
354
    status: str
355
    status_details: Optional[str] = None
356

357
class FileList:
358
    object: str
359
    data: List[FileObject]
360

361
class FileDeleteResponse:
362
    id: str
363
    object: str
364
    deleted: bool
365
```
366

367
### File Purpose Types
368

369
```python { .api }
370
class FilePurpose:
371
    FINE_TUNE = "fine-tune"
372
    BATCH_API = "batch-api"
373
    ASSISTANTS = "assistants"
374
    VISION = "vision"
375

376
class FileType:
377
    JSONL = "jsonl"
378
    JSON = "json"
379
    TXT = "txt"
380
    CSV = "csv"
381
```