client updates

Author: okaris

README.md

@@ -16,86 +16,144 @@ from inferencesh import Inference, TaskStatus
 # Create client
 client = Inference(api_key="your-api-key")
 
-# Simple synchronous usage
-try:
-    task = client.run({
-        "app": "your-app",
-        "input": {"key": "value"},
-        "infra": "cloud",
-        "variant": "default"
-    })
-    
-    print(f"Task ID: {task.get('id')}")
-
-    if task.get("status") == TaskStatus.COMPLETED:
-        print("✓ Task completed successfully!")
-        print(f"Output: {task.get('output')}")
-    else:
-        status = task.get("status")
-        status_name = TaskStatus(status).name if status is not None else "UNKNOWN"
-        print(f"✗ Task did not complete. Final status: {status_name}")
-
-except Exception as exc:
-    print(f"Error: {type(exc).__name__}: {exc}")
-    raise  # Re-raise to see full traceback
-
-# Streaming updates (recommended)
-try:
-    for update in client.run(
-        {
-            "app": "your-app",
-            "input": {"key": "value"},
-            "infra": "cloud",
-            "variant": "default"
-        },
-        stream=True  # Enable streaming updates
-    ):
-        status = update.get("status")
-        status_name = TaskStatus(status).name if status is not None else "UNKNOWN"
-        print(f"Status: {status_name}")
-        
-        if status == TaskStatus.COMPLETED:
-            print("✓ Task completed!")
-            print(f"Output: {update.get('output')}")
-            break
-        elif status == TaskStatus.FAILED:
-            print(f"✗ Task failed: {update.get('error')}")
-            break
-        elif status == TaskStatus.CANCELLED:
-            print("✗ Task was cancelled")
+# Simple synchronous usage - waits for completion by default
+result = client.run({
+    "app": "your-app",
+    "input": {"key": "value"},
+    "infra": "cloud",
+    "variant": "default"
+})
+
+print(f"Task ID: {result.get('id')}")
+print(f"Output: {result.get('output')}")
+```
+
+### run options
+
+```python
+# Wait for completion (default behavior)
+result = client.run(params)  # wait=True is default
+
+# Return immediately without waiting
+task = client.run(params, wait=False)
+task_id = task["id"]  # Use this to check status later
+
+# Stream updates as they happen
+for update in client.run(params, stream=True):
+    print(f"Status: {TaskStatus(update['status']).name}")
+    if update.get("status") == TaskStatus.COMPLETED:
+        print(f"Output: {update.get('output')}")
+```
+
+### task management
+
+```python
+# Get current task state
+task = client.get_task(task_id)
+print(f"Status: {TaskStatus(task['status']).name}")
+
+# Cancel a running task
+client.cancel(task_id)
+
+# Wait for a task to complete
+result = client.wait_for_completion(task_id)
+
+# Stream updates for an existing task
+with client.stream_task(task_id) as stream:
+    for update in stream:
+        print(f"Status: {TaskStatus(update['status']).name}")
+        if update.get("status") == TaskStatus.COMPLETED:
+            print(f"Result: {update.get('output')}")
             break
 
-except Exception as exc:
-    print(f"Error: {type(exc).__name__}: {exc}")
-    raise  # Re-raise to see full traceback
+# Access final result after streaming
+print(f"Final result: {stream.result}")
+```
 
-# Async support
-async def run_async():
-    from inferencesh import AsyncInference
-    
+### task status values
+
+```python
+from inferencesh import TaskStatus
+
+TaskStatus.RECEIVED    # 1 - Task received by server
+TaskStatus.QUEUED      # 2 - Task queued for processing
+TaskStatus.SCHEDULED   # 3 - Task scheduled to a worker
+TaskStatus.PREPARING   # 4 - Worker preparing environment
+TaskStatus.SERVING     # 5 - Model being loaded
+TaskStatus.SETTING_UP  # 6 - Task setup in progress
+TaskStatus.RUNNING     # 7 - Task actively running
+TaskStatus.UPLOADING   # 8 - Uploading results
+TaskStatus.COMPLETED   # 9 - Task completed successfully
+TaskStatus.FAILED      # 10 - Task failed
+TaskStatus.CANCELLED   # 11 - Task was cancelled
+```
+
+### file upload
+
+```python
+from inferencesh import UploadFileOptions
+
+# Upload from file path
+file_obj = client.upload_file("/path/to/image.png")
+print(f"URI: {file_obj['uri']}")
+
+# Upload from bytes
+file_obj = client.upload_file(
+    b"raw bytes data",
+    UploadFileOptions(
+        filename="data.bin",
+        content_type="application/octet-stream"
+    )
+)
+
+# Upload with options
+file_obj = client.upload_file(
+    "/path/to/image.png",
+    UploadFileOptions(
+        filename="custom_name.png",
+        content_type="image/png",
+        public=True  # Make publicly accessible
+    )
+)
+```
+
+Note: Files in task input are automatically uploaded. You only need `upload_file()` for manual uploads.
+
+## async client
+
+```python
+from inferencesh import AsyncInference, TaskStatus
+
+async def main():
     client = AsyncInference(api_key="your-api-key")
 
-    # Simple usage
+    # Simple usage - wait for completion
     result = await client.run({
         "app": "your-app",
         "input": {"key": "value"},
         "infra": "cloud",
         "variant": "default"
     })
+    print(f"Output: {result.get('output')}")
+    
+    # Return immediately without waiting
+    task = await client.run(params, wait=False)
 
     # Stream updates
-    async for update in await client.run(
-        {
-            "app": "your-app",
-            "input": {"key": "value"},
-            "infra": "cloud",
-            "variant": "default"
-        },
-        stream=True
-    ):
-        status = update.get("status")
-        status_name = TaskStatus(status).name if status is not None else "UNKNOWN"
-        print(f"Status: {status_name}")
+    async for update in await client.run(params, stream=True):
+        print(f"Status: {TaskStatus(update['status']).name}")
+        if update.get("status") == TaskStatus.COMPLETED:
+            print(f"Output: {update.get('output')}")
+    
+    # Task management
+    task = await client.get_task(task_id)
+    await client.cancel(task_id)
+    result = await client.wait_for_completion(task_id)
+    
+    # Stream existing task
+    async with client.stream_task(task_id) as stream:
+        async for update in stream:
+            print(f"Update: {update}")
 ```
 
 ## file handling