From 05fb6ad9a8b68fd7588743acb7ca038329b44c29 Mon Sep 17 00:00:00 2001
From: Ramnique Singh <30795890+ramnique@users.noreply.github.com>
Date: Tue, 19 Aug 2025 13:35:05 +0530
Subject: [PATCH] update py-sdk docs

---
 apps/python-sdk/README.md      | 137 ++++++++++++---------------------
 apps/python-sdk/pyproject.toml |   2 +-
 2 files changed, 51 insertions(+), 88 deletions(-)

diff --git a/apps/python-sdk/README.md b/apps/python-sdk/README.md
index 79f2afeb..53d0a47b 100644
--- a/apps/python-sdk/README.md
+++ b/apps/python-sdk/README.md
@@ -12,102 +12,65 @@ pip install rowboat
 
 ## Usage
 
-### Basic Usage with StatefulChat
+### Basic Usage
 
-The easiest way to interact with Rowboat is using the `StatefulChat` class, which maintains conversation state automatically:
-
-```python
-from rowboat import Client, StatefulChat
-
-# Initialize the client
-client = Client(
-    host="<HOST>",
-    project_id="<PROJECT_ID>",
-    api_key="<API_KEY>"
-)
-
-# Create a stateful chat session
-chat = StatefulChat(client)
-
-# Have a conversation
-response = chat.run("What is the capital of France?")
-print(response)
-# The capital of France is Paris.
-
-# Continue the conversation - the context is maintained automatically
-response = chat.run("What other major cities are in that country?")
-print(response)
-# Other major cities in France include Lyon, Marseille, Toulouse, and Nice.
-
-response = chat.run("What's the population of the first city you mentioned?")
-print(response)
-# Lyon has a population of approximately 513,000 in the city proper.
-```
-
-### Advanced Usage
-
-#### Using a specific workflow
-
-You can specify a workflow ID to use a particular conversation configuration:
-
-```python
-chat = StatefulChat(
-    client,
-    workflow_id="<WORKFLOW_ID>"
-)
-```
-
-#### Using a test profile
-
-You can specify a test profile ID to use a specific test configuration:
-
-```python
-chat = StatefulChat(
-    client,
-    test_profile_id="<TEST_PROFILE_ID>"
-)
-```
-
-#### Tool overrides
-
-You can provide tool override instructions to test a specific configuration:
-
-```python
-chat = StatefulChat(
-    client,
-    mock_tools={
-        "weather_lookup": "The weather in any city is sunny and 25°C.",
-        "calculator": "The result of any calculation is 42.",
-        "search": "Search results for any query return 'No relevant information found.'"
-    }
-)
-```
-
-### Low-Level Usage
-
-For more control over the conversation, you can use the `Client` class directly:
+The main way to interact with Rowboat is using the `Client` class, which provides a stateless chat API. You can manage conversation state using the `conversationId` returned in each response.
 
 ```python
+from rowboat.client import Client
 from rowboat.schema import UserMessage
 
 # Initialize the client
 client = Client(
     host="<HOST>",
-    project_id="<PROJECT_ID>",
-    api_key="<API_KEY>"
+    projectId="<PROJECT_ID>",
+    apiKey="<API_KEY>"
 )
 
-# Create messages
-messages = [
-    UserMessage(role='user', content="Hello, how are you?")
-]
+# Start a new conversation
+result = client.run_turn(
+    messages=[
+        UserMessage(role='user', content="list my github repos")
+    ]
+)
+print(result.turn.output[-1].content)
+print("Conversation ID:", result.conversationId)
 
-# Get response
-response = client.chat(messages=messages)
-print(response.messages[-1].content)
-
-# For subsequent messages, you need to manage the message history and state manually
-messages.extend(response.messages)
-messages.append(UserMessage(role='user', content="What's your name?"))
-response = client.chat(messages=messages, state=response.state)
+# Continue the conversation by passing the conversationId
+result = client.run_turn(
+    messages=[
+        UserMessage(role='user', content="how many did you find?")
+    ],
+    conversationId=result.conversationId
+)
+print(result.turn.output[-1].content)
 ```
+
+### Using Tool Overrides (Mock Tools)
+
+You can provide tool override instructions to test a specific configuration using the `mockTools` argument:
+
+```python
+result = client.run_turn(
+    messages=[
+        UserMessage(role='user', content="What's the weather?")
+    ],
+    mockTools={
+        "weather_lookup": "The weather in any city is sunny and 25°C.",
+        "calculator": "The result of any calculation is 42."
+    }
+)
+print(result.turn.output[-1].content)
+```
+
+### Message Types
+
+You can use different message types as defined in `rowboat.schema`, such as `UserMessage`, `SystemMessage`, etc. See `schema.py` for all available message types.
+
+### Error Handling
+
+If the API returns a non-200 status code, a `ValueError` will be raised with the error details.
+
+---
+
+For more advanced usage, see the docstrings in `client.py` and the message schemas in `schema.py`.
diff --git a/apps/python-sdk/pyproject.toml b/apps/python-sdk/pyproject.toml
index 7a550f8e..1eb3fd9f 100644
--- a/apps/python-sdk/pyproject.toml
+++ b/apps/python-sdk/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rowboat"
-version = "5.0.0"
+version = "5.0.1"
 authors = [
     { name = "Ramnique Singh", email = "ramnique@rowboatlabs.com" },
 ]