Fix python-sdk readme and add docs

apps/docs/docs/building_in_studio.md

@@ -0,0 +1,90 @@
+# Building Assistants in Studio
+This is a guide to building your first assistant on RowBoat Studio, with examples.<br>
+**Prerequisite:** Complete the [installation steps](/installation/) to set up RowBoat Studio.
+
+## Create the set of initial agents
+Copilot can sets up agents for you from scratch.
+
+### Instruct copilot
+First, tell it about the initial set of agents that make up your assistant.
+
+![Create Initial Agents](img/copilot-create.png)
+
+Using copilot to create your initial set of agents helps you leverage best practices in formatting agent instructions and connecting agents to each other as a graph, all of which have been baked into copilot.
+
+### Inspect the agents
+Once you apply changes, inspect the agents to see how copilot has built them. Specifically, note the Instructions, Examples and Connected Agents in each agent.
+
+![Agent Config](img/agent-config.png)
+
+Also notice that copilot would likely have created a "Hub" agent that is "connected" to other agents.
+
+![Hub Agent Config](img/hub-config.png)
+
+### Make changes if needed
+Tweak the instructions and examples manually if needed.
+
+![Edit Agent Manually](img/edit-agent-manually.png)
+
+## Try an example chat in the playground
+
+### Chat with the assistant
+
+The playground is intended to test out the assistant as you build it. The User and Assistant messages represent the conversation that your end-user will have if your assistant is deployed in production. The playground also has debug elements which show the flow of control between different agents in your system, as well as which agent finally responded to the user.
+
+![Try Chat](img/try-chat.png)
+
+### Ask copilot questions
+You can ask copilot clarifications about the chat, such as why the agents responded a certain way or why an agent was invoked.
+
+![Copilot Clarifications](img/copilot-clarifications.png)
+
+## Add tools to agents
+Copilot can help you add tools to agents.
+
+#### Instruct copilot to add tools
+![Add Tool](img/add-tool.png)
+
+![Example Tool](img/example-tool.png)
+
+### Inspect tools and agents
+Note how copilot not only creates the tool definitions for you, but also updates the relevant agent instructions to use the tool and connects the tool to the agent.
+
+![Inspect Agent Tools](img/inspect-agent-tools.png)
+![Inspect Agent Tool Connections](img/inspect-agent-tool-connections.png)
+
+### Debug tool calls in the playground
+When agents call tools during a chat in the playground, the tool call parameters and response are available for debugging real-time. For testing purposes, the platform can produce mock tool responses in the playground, without integrating actual tools.
+
+![Mock Tool Responses](img/mock-tool-responses.png)
+![Debug Tool Calls](img/debug-tool-calls.png)
+
+## Update agent behavior
+
+Copilot can help you update agent behavior. It is also aware of the current chat in the playground so you can make references to the current chat while instructing copilot to update agents.
+
+![Update Agent Behavior](img/update-agent-with-copilot.png)
+
+
+Playground:
+![Test Updated Agent](img/test-updated-agent.png)
+
+## Simulate real-world user scenarios
+Create a test-bench of real-world scenarios in the simulator.
+![Scenarios](img/scenarios.png)
+
+Run the scenarios as simulated chats betweeen a user (role-played) and the assistant, in the playground.
+![Simulation](img/simulate.png)
+
+
+
+
+
+
+
+
+
+
+
+
+

apps/docs/docs/installation.md

@@ -53,14 +53,6 @@ Refer to our [Github Readme for Local Development](https://github.com/rowboatlab
 ![Testing Chat](img/testing-chat.png)
 <br>
 
-6. Ask copilot to make minor modifications to one of the agents and apply the changes:
-![Update Agent](img/update-agent.png)
-<br>
-
-7. Test out another chat in the playground to verify the changes:
-![Re-Test Chat](img/re-test-chat.png)
-<br>
-
 ### Testing the Chat API
 
 You can use the API directly at [http://localhost:3000/api/v1/](http://localhost:3000/api/v1/)

apps/docs/docs/quickstart.md

@@ -1,6 +0,0 @@
-# Quick Start
-Follow the [installation steps](/installation/) to set up RowBoat Studio, API and SDK.
-
-## Building your first assistant
-
-Coming soon.

apps/docs/docs/using_the_api.md

@@ -0,0 +1,273 @@
+# Using the API
+
+This is a guide on using the HTTP API to power conversations with the assistant created in Studio.
+
+## Deploy your assistant to production on Studio
+![Prod Deploy](img/prod-deploy.png)
+
+## Obtain API key and Project ID
+
+Generate API keys via the developer configs in your project. Copy the Project ID from the same page.
+![Developer Configs](img/dev-config.png)
+
+## Call the API
+
+When you provide your Project ID in the API call, RowBoat uses the version of your assistant deployed to production. 
+
+The API takes as input: a) history of all messages till now (system, user, tool and assistant messages) and b) state generated from the previous turn (this is needed because the API does not maintain state on its own). 
+
+The API produces as response: a) assistant responses (user-facing responses or tool calls) for the current and b) the state to be passed to the next turn.
+
+### Example first turn of a chat
+
+#### Request
+
+```bash
+curl --location 'http://localhost:3000/api/v1/<PROJECT_ID>/chat' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <API_KEY>' \
+--data '{
+    "messages": [
+        {
+            "content": "UserID: 345227",
+            "role": "system"
+            // Provide context to be passed to all agents in the assistant
+            // E.g. user identity info (user ID) for logged in users
+        },
+        {
+            "content": "What is my outstanding balance and how do I make the payment?",
+            "role": "user"
+        }
+    ],
+    "state": {
+        "last_agent_name": "Credit Card Hub"
+        // This the last agent used in the previous turn.
+        // Set to the "start agent" for first turn of chats
+    }
+}'
+```
+#### Response
+```json
+{
+    "messages": [
+        {
+            "role": "assistant",
+            "sender": "Credit Card Hub",
+            "content": null,
+            "created_at": "2025-02-03T05:22:30.194879",
+            "current_turn": true,
+            "response_type": "internal",
+            "tool_calls": [
+                {
+                  "function": {
+                    "name": "transfer_to_outstanding_payments",
+                    "arguments": "{\"args\":\"\",\"kwargs\":\"\"}"
+                  },
+                  "id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5",
+                  "type": "function"
+                }
+            ]
+        },
+        {
+          "tool_name": "transfer_to_outstanding_payments",
+          "role": "tool",
+          "content": "{\"assistant\": \"Outstanding Payments\"}",
+          "tool_call_id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5"
+        },
+        {
+            "role": "assistant",
+            "sender": "Outstanding Payments",
+            "content": null,
+            "created_at": "2025-02-03T05:22:30.716012",
+            "current_turn": true,
+            "response_type": "internal",
+            "tool_calls": [
+                {
+                  "function": {
+                    "name": "get_outstanding_balance",
+                    "arguments": "{\"user_id\":\"345227\"}"
+                  },
+                  "id": "call_MNAUg7UTszYMt5RL4n5QqUTw",
+                  "type": "function"
+                }
+            ]
+        }
+    ],
+    "state": {
+        "agent_data": [
+            // agents that were involved in this turn
+            {
+                "name": "Credit Card Hub",
+                "instructions": "// agent instructions",
+                "history": [ 
+                  // history of agent-relevant messages
+                  // in the same format as "messages"
+                ],
+                "internal_tools": [],
+                "external_tools": [],
+                "child_functions": [
+                  "transfer_to_outstanding_payments",
+                  "transfer_to_transaction_disputes",
+                  "transfer_to_rewards_redemption"
+                ],
+                "most_recent_parent_name": "",
+                "parent_function": null
+            },
+            {
+                "name": "Outstanding Payments",
+                "instructions": // agent instructions,
+                "history": [ 
+                  // history of agent-relevant messages 
+                  // in the same format as "messages"
+                ],
+                "internal_tools": [],
+                "external_tools": [
+                  "get_outstanding_balance",
+                  "get_saved_credit_card"
+                ],
+                "child_functions": [],
+                "most_recent_parent_name": "",
+                "parent_function": null
+            },
+
+            // other agents - have not yet participated in the conversation
+            {
+                "name": "Rewards Redemption",
+                "instructions": // agent instructions,
+                "history": [], // 
+                "internal_tools": [],
+                "external_tools": [],
+                "child_functions": [],
+                "most_recent_parent_name": "",
+                "parent_function": null
+            },
+            {
+                "name": "Transaction Disputes",
+                "instructions": // agent instructions,
+                "history": [],
+                "internal_tools": [],
+                "external_tools": [],
+                "child_functions": [],
+                "most_recent_parent_name": "",
+                "parent_function": null
+            },
+            {
+                "name": "Escalation",
+                "instructions": // agent instructions,
+                "history": [],
+                "internal_tools": [],
+                "external_tools": [],
+                "child_functions": [],
+                "most_recent_parent_name": "",
+                "parent_function": null
+            },
+        ],
+        "last_agent_name": "Outstanding Payments"
+    }
+}
+
+```
+
+### Example where the assistant is expecting a tool response
+#### Request
+```bash
+curl --location 'http://localhost:3000/api/v1/<PROJECT_ID>/chat' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <API_KEY>' \
+--data '{
+    "messages": [
+        {
+            "content": "UserID: 345227",
+            "role": "system",
+        },
+        {
+            "content": "What is my outstanding balance and how do I make the payment?",
+            "role": "user",
+        },
+        {
+            "content": null,
+            "role": "assistant",
+            "sender": "Credit Card Hub",
+            "tool_calls": [
+                {
+                "function": {
+                    "arguments": "{\"args\":\"\",\"kwargs\":\"\"}",
+                    "name": "transfer_to_outstanding_payments"
+                },
+                "id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5",
+                "type": "function"
+                }
+            ],
+            "tool_call_id": null,
+            "tool_name": null,
+            "response_type": "internal"
+        },
+        {
+            "content": "{\"assistant\": \"Outstanding Payments\"}",
+            "role": "tool",
+            "sender": null,
+            "tool_calls": null,
+            "tool_call_id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5",
+            "tool_name": "transfer_to_outstanding_payments"
+        },
+        {
+            "content": null,
+            "role": "assistant",
+            "sender": "Outstanding Payments",
+            "tool_calls": [
+                {
+                "function": {
+                    "arguments": "{\"user_id\":\"345227\"}",
+                    "name": "get_outstanding_balance"
+                },
+                "id": "call_MNAUg7UTszYMt5RL4n5QqUTw",
+                "type": "function"
+                }
+            ],
+            "tool_call_id": null,
+            "tool_name": null,
+            "response_type": "internal"
+        },
+        {
+            "content": "{\"result\":{\"outstanding_balance\":\"$250.00\",\"due_date\":\"2025-02-15\",\"payment_methods\":[\"Credit Card\",\"Bank Transfer\",\"PayPal\"]}}",
+            "role": "tool",
+            "sender": null,
+            "tool_calls": null,
+            "tool_call_id": "call_MNAUg7UTszYMt5RL4n5QqUTw",
+            "tool_name": "get_outstanding_balance"
+        },
+    ],
+    "state": {
+        // State returned by the API in the previous turn
+    }
+}'
+```
+#### Response
+```json
+{
+    "messages": [
+      {
+        "content": "Your outstanding balance is $250.00, due by February 15, 2025.\n\nYou have several payment options available, including:\n- **Credit Card**\n- **Bank Transfer**\n- **PayPal**\n\nPlease let me know which option you'd like to use, and I'll guide you through the process!",
+        "created_at": "2025-02-03T06:01:07.451140",
+        "current_turn": true,
+        "response_type": "internal",
+        "role": "assistant",
+        "sender": "Outstanding Payments"
+      },
+      {
+        "content": "Your outstanding balance is $250.00, due by February 15, 2025. \n\nPayment options include:\n- **Credit Card:** You can use your saved Visa card ending in 1234.\n- **Bank Transfer**\n- **PayPal**\n\nLet me know your preferred payment method, and I’ll assist you!",
+        "created_at": "2025-02-03T06:01:07.451140",
+        "current_turn": true,
+        "response_type": "external",
+        "role": "assistant",
+        "sender": "Outstanding Payments >> Post process"
+      }
+    ],
+    "state": {
+      "agent_data": [
+        // Omitted for brevity
+      ],
+      "last_agent_name": "Outstanding Payments"
+    }
+}
+```

apps/docs/docs/using_the_sdk.md

@@ -0,0 +1,81 @@
+# Using the Python SDK
+
+This is a guide on using the RowBoat Python SDK as an alternative to the [RowBoat HTTP API](/using_the_api) to power conversations with the assistant created in Studio.
+
+## Prerequisites
+- [Deploy your assistant to production](/using_the_api/#deploy-your-assistant-to-production-on-studio) and [obtain your API key and Project ID](/using_the_api/#obtain-api-key-and-project-id)
+- ``` pip install rowboat ```
+
+## Usage
+
+### Basic Usage
+
+Initialize a client and use the chat method directly:
+
+```python
+from rowboat import Client
+from rowboat.schema import UserMessage, SystemMessage
+
+# Initialize the client
+client = Client(
+    host="<HOST>",
+    project_id="<PROJECT_ID>",
+    api_key="<API_KEY>"
+)
+
+# Create messages
+messages = [
+    SystemMessage(role='system', content="You are a helpful assistant"),
+    UserMessage(role='user', content="Hello, how are you?")
+]
+
+# Get response
+response_messages, state = client.chat(messages=messages)
+print(response_messages[-1].content)
+
+# For subsequent messages, include previous messages and state
+messages.extend(response_messages)
+messages.append(UserMessage(role='user', content="What's your name?"))
+response_messages, state = client.chat(messages=messages, state=state)
+```
+
+### Using Tools
+
+The SDK supports function calling through tools:
+
+```python
+def weather_lookup(city_name: str) -> str:
+    return f"The weather in {city_name} is 22°C."
+
+# Create a tools dictionary
+tools = {
+    'weather_lookup': weather_lookup
+}
+
+# Use tools with the chat method
+response_messages, state = client.chat(
+    messages=messages,
+    tools=tools
+)
+```
+
+### Stateful Chat (Convenience Wrapper)
+
+For simpler use cases, the SDK provides a `StatefulChat` class that maintains conversation state automatically:
+
+```python
+from rowboat import StatefulChat
+
+# Initialize stateful chat
+chat = StatefulChat(
+    client,
+    tools=tools,
+    system_prompt="You are a helpful assistant."
+)
+
+# Simply send messages and get responses
+response = chat.run("Hello, how are you?")
+print(response)
+# I'm good, thanks! How can I help you today?
+```
+

apps/docs/mkdocs.yml

@@ -9,4 +9,6 @@ nav:
     - Open Source License: license.md
   - Getting started:
     - Installation: installation.md
-    - Quickstart: quickstart.md
+    - Building in Studio: building_in_studio.md
+    - Using the API: using_the_api.md
+    - Using the SDK: using_the_sdk.md