Deployed 1ade0a8 with MkDocs version: 1.6.1

api-sdk/using_the_api.mdx

@@ -0,0 +1,173 @@
+---
+title: "Using the API"
+description: "This is a guide on using the HTTP API to power conversations with the assistant created in Studio."
+icon: "code"
+---
+
+
+## Deploy your assistant to production on Studio
+<Frame>
+  <img src="/docs/img/prod-deploy.png" alt="Prod Deploy" />
+</Frame>
+
+## Obtain API key and Project ID
+
+Generate API keys via the developer configs in your project. Copy the Project ID from the same page.
+<Frame>
+  <img src="/docs/img/dev-config.png" alt="Developer Configs" />
+</Frame>
+
+## API Endpoint
+
+```
+POST <HOST>/api/v1/<PROJECT_ID>/chat
+```
+
+Where:
+
+- For self-hosted: `<HOST>` is `http://localhost:3000`
+
+## Authentication
+
+Include your API key in the Authorization header:
+
+```
+Authorization: Bearer <API_KEY>
+```
+
+## Examples
+
+### First Turn
+
+```bash
+curl --location '<HOST>/api/v1/<PROJECT_ID>/chat' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <API_KEY>' \
+--data '{
+    "messages": [
+        {
+            "role": "user",
+            "content": "Hello, can you help me?"
+        }
+    ],
+    "state": null
+}'
+```
+
+Response:
+```json
+{
+    "messages": [
+        {
+            "role": "assistant",
+            "content": "Hello! Yes, I'd be happy to help you. What can I assist you with today?",
+            "agenticResponseType": "external"
+        }
+    ],
+    "state": {
+        "last_agent_name": "MainAgent"
+    }
+}
+```
+
+### Subsequent Turn
+
+Notice how we include both the previous messages and the state from the last response:
+
+```bash
+curl --location '<HOST>/api/v1/<PROJECT_ID>/chat' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer <API_KEY>' \
+--data '{
+    "messages": [
+        {
+            "role": "user",
+            "content": "Hello, can you help me?"
+        },
+        {
+            "role": "assistant",
+            "content": "Hello! Yes, I'd be happy to help you. What can I assist you with today?",
+            "agenticResponseType": "external"
+        },
+        {
+            "role": "user",
+            "content": "What services do you offer?"
+        }
+    ],
+    "state": {
+        "last_agent_name": "MainAgent"
+    }
+}'
+```
+
+## API Specification
+
+### Request Schema
+
+```typescript
+{
+    // Required fields
+    messages: Message[];      // Array of message objects representing the conversation history
+    state: any;              // State object from previous response, or null for first message
+
+    // Optional fields
+    workflowId?: string;     // Specific workflow ID to use (defaults to production workflow)
+    testProfileId?: string;  // Test profile ID for simulation
+}
+```
+
+### Message Types
+
+Messages can be one of the following types:
+
+1. System Message
+```typescript
+{
+    role: "system";
+    content: string;
+}
+```
+
+2. User Message
+```typescript
+{
+    role: "user";
+    content: string;
+}
+```
+
+3. Assistant Message
+```typescript
+{
+    role: "assistant";
+    content: string;
+    agenticResponseType: "internal" | "external";
+    agenticSender?: string | null;
+}
+```
+
+### Response Schema
+
+```typescript
+{
+    messages: Message[];  // Array of new messages from this turn
+    state: any;          // State object to pass in the next request
+}
+```
+
+## Important Notes
+
+1. Always pass the complete conversation history in the `messages` array
+2. Always include the `state` from the previous response in your next request
+3. The last message in the response's `messages` array will be a user-facing assistant message (`agenticResponseType: "external"`)
+
+## Rate Limiting
+
+The API has rate limits per project. If exceeded, you'll receive a 429 status code.
+
+## Error Responses
+
+- 400: Invalid request body or missing/invalid Authorization header
+- 403: Invalid API key
+- 404: Project or workflow not found
+- 429: Rate limit exceeded

api-sdk/using_the_sdk.mdx

@@ -0,0 +1,91 @@
+---
+title: "Using the SDK"
+description: "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."
+icon: "toolbox"
+---
+
+## Prerequisites
+- ``` pip install rowboat ```
+- [Deploy your assistant to production](/using_the_api/#deploy-your-assistant-to-production-on-studio)
+- [Obtain your `<API_KEY>` and `<PROJECT_ID>`](/using_the_api/#obtain-api-key-and-project-id)
+
+### API Host
+- For the open source installation, the `<HOST>` is [http://localhost:3000](http://localhost:3000)
+- When using the hosted app, the `<HOST>` is [https://app.rowboatlabs.com](https://app.rowboatlabs.com)
+
+## Usage
+
+### Basic Usage
+
+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>",
+    projectId="<PROJECT_ID>",
+    apiKey="<API_KEY>"
+)
+
+# Start a new conversation
+result = client.run_turn(
+    messages=[
+        UserMessage(role='user', content="What is the capital of France?")
+    ]
+)
+print(result.turn.output[-1].content)
+# The capital of France is Paris.
+
+print("Conversation ID:", result.conversationId)
+
+# Continue the conversation by passing the conversationId
+result = client.run_turn(
+    messages=[
+        UserMessage(role='user', content="What other major cities are in that country?")
+    ],
+    conversationId=result.conversationId
+)
+print(result.turn.output[-1].content)
+# Other major cities in France include Lyon, Marseille, Toulouse, and Nice.
+
+result = client.run_turn(
+    messages=[
+        UserMessage(role='user', content="What's the population of the first city you mentioned?")
+    ],
+    conversationId=result.conversationId
+)
+print(result.turn.output[-1].content)
+# Lyon has a population of approximately 513,000 in the city proper.
+```
+
+### 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`, `AssistantMessage`, 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`.