### Quick Start with SuperMeClient

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Basic initialization of the SuperMeClient and making a simple question. Demonstrates using an API key and base URL for client setup, and the simplified 'ask' method.

```python
from superme_sdk import SuperMeClient

# Initialize client with API key
client = SuperMeClient(
    api_key="your-api-key",
    base_url="https://api.superme.ai"  # or "http://localhost:8089" for local
)

# Simple question
answer = client.ask("What are the key principles of growth marketing?", username="ludo")
print(answer)

# Anonymous question (incognito mode)
anonymous_answer = client.ask("What are the key principles of growth marketing?", username="ludo", incognito=True)
print(anonymous_answer)
```

--------------------------------

### Install SuperMe SDK with Development Dependencies

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

This bash command outlines the steps to clone the SuperMe SDK repository and install it with development dependencies. This setup is typically used for contributing to the SDK or running tests.

```bash
git clone https://github.com/superme-ai/superme-sdk.git
cd superme-sdk
pip install -e ".[dev]"
```

--------------------------------

### Install SuperMe SDK

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Instructions for installing the SuperMe SDK using pip or from source. This involves either a direct pip install or cloning the repository and performing a local installation.

```bash
pip install superme-sdk
```

```bash
git clone https://github.com/superme-ai/superme-sdk.git
cd superme-sdk
pip install -e .
```

--------------------------------

### Install SuperMe SDK

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Install the SuperMe SDK using pip. This is the first step to integrate the SDK into your Python project.

```bash
pip install superme-sdk
```

--------------------------------

### Custom Base URL for Self-Hosted SuperMe

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Example of initializing the SuperMeClient with a custom 'base_url' for connecting to a locally hosted or self-hosted SuperMe AI instance.

```python
client = SuperMeClient(
    api_key="your-api-key",
    base_url="http://localhost:8089"  # Local development server
)
```

--------------------------------

### Run Tests for SuperMe SDK

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

This command executes the test suite for the SuperMe SDK using the `pytest` framework. Ensure you have cloned the repository and installed the development dependencies before running this command.

```bash
pytest
```

--------------------------------

### Use SuperMe Client Chat Completions

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

This example illustrates how to use the chat completions interface provided by the SuperMe client. It shows a call to `client.chat.completions.create` with a model, messages, and an additional 'username' parameter in the `extra_body`.

```python
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"username": "ludo"}
)
```

--------------------------------

### Make Raw API Requests to SuperMe API

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

This example demonstrates how to perform a raw HTTP request to the SuperMe API, specifically for listing available tools. It uses the `client.raw_request` method with a JSON payload specifying the 'tools/list' method.

```python
response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/list"
    }
)
print(response.json())
```

--------------------------------

### MCP Protocol - Get User Profiles

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Retrieves user profile information.

```APIDOC
## POST /mcp - Get User Profile

### Description
This endpoint retrieves a user's profile information. You can specify a username to get a specific user's profile, or omit the username to get your own profile.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The method to call, should be 'tools/call'.
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, should be 'get_profile'.
  - **arguments** (object) - Optional - Arguments for the 'get_profile' tool.
    - **username** (string) - Optional - The username of the profile to retrieve. If omitted, the authenticated user's profile is returned.

### Request Example (Specific User)
```json
{
    "method": "tools/call",
    "params": {
        "name": "get_profile",
        "arguments": {
            "username": "ludo"
        }
    }
}
```

### Request Example (Own Profile)
```json
{
    "method": "tools/call",
    "params": {
        "name": "get_profile",
        "arguments": {}
    }
}
```

### Response
#### Success Response (200)
- **content** (array) - Contains the response from the tool call.
  - **text** (string) - The actual response content, which is a JSON object representing the user profile.
    - The profile object may contain fields like `username`, `bio`, `expertise`.

#### Response Example
```json
{
  "content": [
    {
      "text": "{\"username\": \"ludo\", \"bio\": \"AI enthusiast and developer.\", \"expertise\": [\"Machine Learning\", \"Python\"]}"
    }
  ]
}
```
```

--------------------------------

### Structured Responses with Pydantic Models (Python)

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

This example demonstrates how to leverage Pydantic models for structured AI responses. It defines Pydantic models for data schemas (`GrowthStrategy`, `UserProfile`) and a helper function `ask_with_schema` to integrate these models with the SuperMe client for generating JSON-formatted outputs.

```python
from typing import Union
from pydantic import BaseModel
from superme_sdk import SuperMeClient

# Define your data models
class GrowthStrategy(BaseModel):
    strategy_name: str
    description: str
    target_audience: str
    expected_outcome: str
    implementation_difficulty: int  # 1-5 scale

class UserProfile(BaseModel):
    name: str
    age: int
    expertise: list[str]
    location: str

# Helper function for structured responses
def ask_with_schema(
    client: SuperMeClient,
    messages: list[dict],
    response_format: Union[BaseModel, dict],
    name: str = "response",
    username: str = "ludo",
    **kwargs
):
    if isinstance(response_format, BaseModel):
        response_format_dict = response_format.model_json_schema()
    else:
        response_format_dict = response_format

    return client.chat.completions.create(
        model="gpt-4",
        messages=messages,
        extra_body={
            "username": username,
            "response_format": {
                "type": "json_schema",
                "json_schema": {
                    "name": name,
                    "schema": response_format_dict,
                    "strict": True,
                },
            },
        },
        **kwargs
    )

# Use it with Pydantic models
client = SuperMeClient(api_key="your-api-key")

strategy_response = ask_with_schema(
    client=client,
    messages=[{
        "role": "user",
        "content": "Provide a growth marketing strategy for a B2B SaaS startup"
    }],
    response_format=GrowthStrategy,
    name="growth_strategy",
    username="ludo",
    max_tokens=300
)

print(strategy_response.choices[0].message.content)
# Output: {"strategy_name": "Content-Led Growth", "description": "...", ...}

# Use with custom dict schema
custom_schema = {
    "type": "object",
    "properties": {
        "tactics": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "priority": {"type": "integer", "minimum": 1, "maximum": 5}
                },
                "required": ["name", "priority"]
            }
        }
    },
    "required": ["tactics"]
}

tactics_response = ask_with_schema(
    client=client,
    messages=[{
        "role": "user",
        "content": "List 3 growth marketing tactics with priority levels"
    }],
    response_format=custom_schema,
    name="marketing_tactics",
    username="ludo",
    max_tokens=400
)
print(tactics_response.choices[0].message.content)
```

--------------------------------

### Multi-Turn Conversations in Python

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Implementing multi-turn conversations using the 'ask_with_history' method. This example shows sending initial messages, receiving a response and conversation ID, and continuing the conversation with updated message history.

```python
# First message
messages = [
    {"role": "user", "content": "What is product-market fit?"}
]

response1, conv_id = client.ask_with_history(
    messages=messages,
    username="ludo"
)
print(response1)

# Continue conversation
messages.append({"role": "assistant", "content": response1})
messages.append({"role": "user", "content": "How do you measure it?"})

response2, conv_id = client.ask_with_history(
    messages=messages,
    username="ludo",
    conversation_id=conv_id
)
print(response2)

# Anonymous conversation
anonymous_messages = [
    {"role": "user", "content": "What is product-market fit?"}
]

anonymous_response, anonymous_conv_id = client.ask_with_history(
    messages=anonymous_messages,
    username="ludo",
    incognito=True
)
print(anonymous_response)
```

--------------------------------

### MCP Protocol - Ask Tool (Python)

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

This code example shows how to use the MCP 'ask' tool to query the AI. It constructs a JSON payload with the method 'tools/call' and specifies the 'ask' tool with the question and username. The response content is then parsed to extract the question, answer, and conversation ID.

```python
import json
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Ask a question using MCP ask tool
ask_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "ask",
            "arguments": {
                "username": "ludo",
                "question": "What is product-market fit?"
            }
        }
    }
)

result = json.loads(ask_response.json()["content"][0]["text"])
print(f"Question: {result['question']}")
print(f"Response: {result['response']}")
print(f"Conversation ID: {result['conversation_id']}")
```

--------------------------------

### MCP Protocol - Get Conversation Details

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Retrieves detailed information about a specific conversation using its ID.

```APIDOC
## POST /mcp - Get Conversation Details

### Description
This endpoint retrieves the details of a specific conversation, including its messages, using the conversation's unique identifier.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The method to call, should be 'tools/call'.
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, should be 'get_conversation'.
  - **arguments** (object) - Required - Arguments for the 'get_conversation' tool.
    - **conversation_id** (string) - Required - The unique ID of the conversation to retrieve.

### Request Example
```json
{
    "method": "tools/call",
    "params": {
        "name": "get_conversation",
        "arguments": {
            "conversation_id": "conv_abc123"
        }
    }
}
```

### Response
#### Success Response (200)
- **content** (array) - Contains the response from the tool call.
  - **text** (string) - The actual response content, which is a JSON object representing the conversation details.
    - The conversation object contains fields like `id`, `created_at`, `messages`.
    - Each message object contains fields like `role` and `content`.

#### Response Example
```json
{
  "content": [
    {
      "text": "{\"id\": \"conv_abc123\", \"created_at\": \"2023-10-26T09:30:00Z\", \"messages\": [ {\"role\": \"user\", \"content\": \"Hello there!\"}, {\"role\": \"assistant\", \"content\": \"Hi! How can I help you today?\"} ] }"
    }
  ]
}
```
```

--------------------------------

### Get Conversation Details using MCP

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Retrieves details for a specific conversation using the MCP protocol. Requires the 'get_conversation' tool and a conversation ID. It returns a detailed conversation object, including messages.

```python
import json
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Get specific conversation details
conversation_id = "conv_abc123"

conv_details_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "get_conversation",
            "arguments": {
                "conversation_id": conversation_id
            }
        }
    }
)

conversation = json.loads(conv_details_response.json()["content"][0]["text"])
print(f"Conversation ID: {conversation['id']}")
print(f"Created: {conversation['created_at']}")
print(f"Messages:")
for msg in conversation.get('messages', []):
    print(f"  {msg['role']}: {msg['content'][:100]}...")
```

--------------------------------

### Get User Profiles using MCP

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Fetches user profiles using the MCP protocol with the 'get_profile' tool. It can retrieve a specific user's profile by username or the authenticated user's own profile if no username is provided. Returns a JSON object representing the user profile.

```python
import json
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Get a specific user's profile
profile_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "get_profile",
            "arguments": {
                "username": "ludo"
            }
        }
    }
)

profile = json.loads(profile_response.json()["content"][0]["text"])
print(json.dumps(profile, indent=2))
# Output: {"username": "ludo", "bio": "...", "expertise": [...], ...}

# Get authenticated user's own profile (no username needed)
my_profile_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "get_profile",
            "arguments": {}
        }
    }
)

my_profile = json.loads(my_profile_response.json()["content"][0]["text"])
print(f"My username: {my_profile['username']}")
print(f"My bio: {my_profile['bio']}")
```

--------------------------------

### Initialize SuperMe Client

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Initialize the SuperMeClient with your API key and base URL. Supports both cloud and local development environments.

```python
from superme_sdk import SuperMeClient

# Initialize client with API key
client = SuperMeClient(
    api_key="your-api-key",
    base_url="https://api.superme.ai"
)

# For local development
local_client = SuperMeClient(
    api_key="your-api-key",
    base_url="http://localhost:8089"
)
```

--------------------------------

### Initialize SuperMeClient

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

This snippet shows the basic constructor for the `SuperMeClient` class, which is the main entry point for interacting with the SuperMe API. It requires an `api_key` and optionally accepts a `base_url` for specifying the API endpoint.

```python
SuperMeClient(
    api_key: str,
    base_url: str = "https://api.superme.ai"
)
```

--------------------------------

### SuperMeClient Constructor

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Initializes the SuperMeClient with an API key and an optional base URL.

```APIDOC
## SuperMeClient Constructor

Initializes the SuperMeClient with an API key and an optional base URL.

### Method

```python
SuperMeClient(api_key: str, base_url: str = "https://api.superme.ai")
```

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```python
# No direct request body for constructor
```

### Response

#### Success Response (200)

None (constructor does not return a response object)

#### Response Example

None
```

--------------------------------

### MCP Protocol - Initialize Connection and List Tools (Python)

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

This snippet demonstrates how to initialize a connection using the MCP protocol and subsequently list the available tools. It uses `client.raw_request` to send JSON-RPC-like requests to the '/mcp' endpoint, retrieving server information and tool names.

```python
import json
from superme_sdk import SuperMeClient

client = SuperMeClient(
    api_key="your-api-key",
    base_url="https://api.superme.ai"
)

# Initialize MCP connection
init_response = client.raw_request(
    "/mcp",
    json={"method": "initialize", "params": {}}
)
server_info = init_response.json()
print(f"Server: {server_info['serverInfo']['name']}")
print(f"Version: {server_info['serverInfo']['version']}")
print(f"Capabilities: {server_info['capabilities']}")

# List available tools
tools_response = client.raw_request(
    "/mcp",
    json={"method": "tools/list", "params": {}}
)
tools = tools_response.json()["tools"]
print(f"Available tools: {[tool['name'] for tool in tools]}")
# Output: ['ask', 'list_conversations', 'get_conversation', 'get_profile']
```

--------------------------------

### MCP Protocol Usage in Python

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Demonstrates using the Model Context Protocol (MCP) via the SDK's 'raw_request' method. Includes initializing MCP, listing available tools, and calling the 'ask' tool with specific arguments.

```python
import json
from superme_sdk import SuperMeClient

client = SuperMeClient(
    api_key="your-api-key",
    base_url="https://api.superme.ai"
)

# 1. Initialize MCP connection
init_response = client.raw_request(
    "/mcp", 
    json={"method": "initialize", "params": {}}
)
print(f"Server info: {init_response.json()['serverInfo']}")

# 2. List available tools
tools_response = client.raw_request(
    "/mcp", 
    json={"method": "tools/list", "params": {}}
)
tools = tools_response.json()["tools"]
print(f"Available tools: {[tool['name'] for tool in tools]}")

# 3. Ask a question using MCP ask tool
ask_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "ask",
            "arguments": {
                "username": "ludo",
                "question": "Where do you live?"
            }
        }
    }
)

```

--------------------------------

### Basic Chat Completion with OpenAI Client

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Using the standard OpenAI client directly with the SuperMe AI endpoint. This allows leveraging familiar OpenAI methods like 'chat.completions.create' with SuperMe's capabilities.

```python
from openai import OpenAI

# One can use the OpenAI client directly with SuperMe endpoint
client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.superme.ai/sdk" # use /sdk here in case you are directly using the OpenAI client
)

# Standard OpenAI completion
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "What is product-market fit?"}
    ],
    extra_body={"username": "ludo"},  # SuperMe username
    max_tokens=150
)

print(response.choices[0].message.content)
```

--------------------------------

### Simplified Ask Method in Python

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Demonstrates the simplified 'ask' method for single questions, including options for specifying 'max_tokens' and enabling 'incognito' mode for anonymous queries.

```python
# Simpler interface for single questions
answer = client.ask(
    question="What are growth strategies?",
    username="ludo",
    max_tokens=500
)
print(answer)

# Anonymous question (incognito mode)
anonymous_answer = client.ask(
    question="What are growth strategies?",
    username="ludo",
    max_tokens=500,
    incognito=True
)
print(anonymous_answer)
```

--------------------------------

### ask

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

A simplified method to ask a question to the SuperMe AI.

```APIDOC
## ask

Simplified method to ask a question.

### Method

```python
ask(question, username="ludo", conversation_id=None, max_tokens=1000, incognito=False, **kwargs) -> str
```

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```python
# Example usage within the SDK, not a direct API request example
response_text = client.ask("What is the capital of France?")
```

### Response

#### Success Response (200)

- **response_text** (str) - AI response as string

#### Response Example

```json
{
  "response_text": "The capital of France is Paris."
}
```
```

--------------------------------

### chat.completions.create

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Access to OpenAI-compatible chat completions interface.

```APIDOC
## chat.completions.create

Access to OpenAI-compatible chat completions interface.

### Method

```python
client.chat.completions.create(
    model: str,
    messages: list,
    extra_body: dict = None,
    **kwargs
)
```

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

- **model** (str) - The name of the model to use (e.g., `"gpt-4"`).
- **messages** (list) - A list of message objects, each with a `role` and `content`.
- **extra_body** (dict) - Additional parameters to pass to the underlying OpenAI client, such as `username`.
- **kwargs** - Additional arguments to pass to OpenAI client.

### Request Example

```python
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"username": "ludo"}
)
print(response)
```

### Response

#### Success Response (200)

- **response** (object) - The response object from the OpenAI API.

#### Response Example

```json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}
```
```

--------------------------------

### Format Code with Black and Ruff

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

These bash commands demonstrate how to format the Python code within the SuperMe SDK using `black` for code style and `ruff` for linting. These tools help maintain code quality and consistency across the project.

```bash
black superme_sdk/
ruff check superme_sdk/
```

--------------------------------

### Simple Question-Answer with SuperMe SDK

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Ask a simple question to a user profile using the `ask` method. Specify the question, target username, and max tokens for the response.

```python
from superme_sdk import SuperMeClient

client = SuperMeClient(
    api_key="your-api-key",
    base_url="https://api.superme.ai"
)

# Ask a simple question to a user profile
answer = client.ask(
    question="What are the key principles of growth marketing?",
    username="ludo",
    max_tokens=500
)
print(answer)

# Output: Detailed response about growth marketing principles from ludo's profile
```

--------------------------------

### OpenAI-Compatible Chat Completions with SuperMe SDK

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Utilize the OpenAI-compatible interface for chat completions. The SDK mimics the OpenAI API structure, allowing familiar usage patterns.

```python
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Use the familiar OpenAI chat completions format
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "What is product-market fit?"}
    ],
    extra_body={"username": "ludo"},
    max_tokens=150
)

print(response.choices[0].message.content)

# Alternatively, use OpenAI client directly with SuperMe endpoint
from openai import OpenAI

openai_client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.superme.ai/sdk"  # Note: /sdk suffix required
)

response = openai_client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What is product-market fit?"}],
    extra_body={"username": "ludo"},
    max_tokens=150
)
print(response.choices[0].message.content)
```

--------------------------------

### Structured Conversations with Context using SuperMe SDK

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Build structured conversations by maintaining a list of messages (user and assistant roles) and sending them to the `chat.completions.create` endpoint. This allows for building complex, context-aware interactions.

```python
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Build a conversation with multiple turns
conversation = []

# First question
conversation.append({"role": "user", "content": "Who founded Y Combinator?"})
response1 = client.chat.completions.create(
    model="gpt-4",
    messages=conversation,
    extra_body={"username": "ludo"},
    max_tokens=100
)
answer1 = response1.choices[0].message.content
conversation.append({"role": "assistant", "content": answer1})
print(f"Q1: {conversation[0]['content']}")
print(f"A1: {answer1}\n")
```

--------------------------------

### Raw API Requests for Advanced Use Cases

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Demonstrates making custom raw API requests to the MCP endpoint using `client.raw_request`. This includes specifying the endpoint, method, JSON payload, and timeout. It also shows how to include custom headers in the request.

```python
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Make custom raw API requests
response = client.raw_request(
    endpoint="/mcp",
    method="POST",
    json={"method": "tools/list", "params": {}},
    timeout=30
)

print(f"Status: {response.status_code}")
print(f"Headers: {dict(response.headers)}")

if response.status_code == 200:
    data = response.json()
    print(f"Response: {data}")
else:
    print(f"Error: {response.text}")

# Custom headers example
custom_response = client.raw_request(
    endpoint="/mcp",
    method="POST",
    json={"method": "initialize", "params": {}},
    headers={"X-Custom-Header": "value"}
)
```

--------------------------------

### Querying Multiple User Profiles

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Allows asking the same question to multiple user profiles.

```APIDOC
## POST /ask - Query Multiple User Profiles

### Description
This method allows you to ask a question to multiple user profiles and receive their answers. It leverages the `ask` function of the client.

### Method
POST (Implicitly via client.ask)

### Endpoint
(Internal SDK function, likely interacting with a /ask or similar endpoint)

### Parameters
- **question** (string) - Required - The question to ask.
- **username** (string) - Required - The username of the profile to ask.
- **max_tokens** (integer) - Optional - The maximum number of tokens for the answer.

### Request Example (Code)
```python
answer = client.ask(
    question="What are your areas of expertise?",
    username="ludo",
    max_tokens=150
)
```

### Response
#### Success Response (200)
- **string** - The answer provided by the user profile.

#### Response Example
```
AI enthusiast and developer.
I specialize in Machine Learning and Python programming.
--------------------------------------------------
```
```

--------------------------------

### Query Multiple User Profiles

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Queries multiple user profiles with the same question using the SDK's `ask` method. It iterates through a list of usernames, sending the same query to each and printing the formatted response.

```python
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Query different user profiles with the same question
question = "What are your areas of expertise?"
usernames = ["ludo", "casey", "paul"]

for username in usernames:
    answer = client.ask(
        question=question,
        username=username,
        max_tokens=150
    )
    print(f"
{username.upper()}:")
    print(answer)
    print("-" * 50)
```

--------------------------------

### Follow-up question using context (Python)

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

This snippet shows how to append a user's follow-up question to a conversation and then use the SuperMe client to generate a response based on the conversation history. It handles the conversation state and prints the question and answer.

```python
conversation.append({"role": "user", "content": "What companies did he help start?"})
response2 = client.chat.completions.create(
    model="gpt-4",
    messages=conversation,
    extra_body={"username": "ludo"},
    max_tokens=150
)
answer2 = response2.choices[0].message.content
conversation.append({"role": "assistant", "content": answer2})
print(f"Q2: {conversation[2]['content']}")
print(f"A2: {answer2}")
```

--------------------------------

### raw_request

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Makes a raw HTTP request to the SuperMe API.

```APIDOC
## raw_request

Make a raw HTTP request to SuperMe API.

### Method

```python
raw_request(endpoint, method="POST", **kwargs) -> requests.Response
```

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

- **endpoint** (str) - API endpoint (e.g., `"/mcp/completion"`).
- **method** (str) - HTTP method (default: `"POST"`).
- **kwargs** - Additional arguments to pass to requests.

### Request Example

```python
# Example of a raw request to list tools
response = client.raw_request("/mcp", json={"method": "tools/list"})
print(response.json())
```

### Response

#### Success Response (200)

- **requests.Response** - The `requests.Response` object from the HTTP request.

#### Response Example

```json
# Example response, actual content depends on the endpoint called
{
  "status": "success",
  "data": [
    {
      "name": "ask",
      "description": "Ask a question to the AI."
    }
  ]
}
```
```

--------------------------------

### Raw API Requests

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Provides the ability to make custom raw API requests for advanced use cases.

```APIDOC
## POST /mcp - Raw API Request

### Description
This endpoint allows for making custom raw API requests to the `/mcp` endpoint. You can specify the method, JSON payload, and timeout.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The HTTP method for the request (e.g., 'POST', 'GET').
- **json** (object) - Required - The JSON payload for the request.
- **timeout** (integer) - Optional - The timeout in seconds for the request.
- **headers** (object) - Optional - Custom headers to include in the request.

### Request Example (List Tools)
```json
{
    "method": "POST",
    "json": {"method": "tools/list", "params": {}},
    "timeout": 30
}
```

### Request Example (Custom Headers)
```json
{
    "method": "POST",
    "json": {"method": "initialize", "params": {}},
    "headers": {"X-Custom-Header": "value"}
}
```

### Response
#### Success Response (200)
- **status_code** (integer) - The HTTP status code of the response.
- **headers** (object) - The headers of the response.
- **data** (object) - The JSON data returned in the response body.

#### Error Response
- **status_code** (integer) - The HTTP status code of the error.
- **text** (string) - The error message or response body.
```

--------------------------------

### Anonymous (Incognito) Q&A with SuperMe SDK

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Ask a question anonymously using `incognito=True`. The user profile will not know who asked, preserving privacy for sensitive queries.

```python
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Ask a question anonymously - the user profile won't know who asked
anonymous_answer = client.ask(
    question="What are your thoughts on competitor strategies?",
    username="ludo",
    incognito=True,
    max_tokens=500
)
print(anonymous_answer)

# The response is generated but the question isn't attributed to your account
```

--------------------------------

### Anonymous Question using MCP

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Allows users to ask questions anonymously via the MCP protocol.

```APIDOC
## POST /mcp - Anonymous Question

### Description
This endpoint allows you to send an anonymous question through the MCP protocol. It uses the 'ask' tool with specified arguments.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The method to call, should be 'tools/call'.
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, should be 'ask'.
  - **arguments** (object) - Required - Arguments for the 'ask' tool.
    - **username** (string) - Required - The username to ask the question to.
    - **question** (string) - Required - The question to ask.
    - **incognito** (boolean) - Required - Whether to ask the question anonymously.

### Request Example
```json
{
    "method": "tools/call",
    "params": {
        "name": "ask",
        "arguments": {
            "username": "ludo",
            "question": "What are your competitive advantages?",
            "incognito": true
        }
    }
}
```

### Response
#### Success Response (200)
- **content** (array) - Contains the response from the tool call.
  - **text** (string) - The actual response content, often a JSON string.

#### Response Example
```json
{
  "content": [
    {
      "text": "{\"response\": \"Your competitive advantages include advanced AI capabilities, a vast knowledge base, and personalized user experiences.\"}"
    }
  ]
}
```
```

--------------------------------

### Perform Anonymous Question using MCP Ask Tool

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

This snippet demonstrates how to make an anonymous request to the MCP ask tool to pose a question. It utilizes the `client.raw_request` method with specific parameters for the 'ask' tool. The response is then parsed to extract the question, answer, and conversation ID.

```python
anonymous_ask_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "ask",
            "arguments": {
                "username": "ludo",
                "question": "Where do you live?",
                "incognito": True
            }
        }
    }
)

# Parse the response
ask_result = json.loads(anonymous_ask_response.json()["content"][0]["text"])
print(f"Question: {ask_result['question']}")
print(f"Response: {ask_result['response']}")
print(f"Conversation ID: {ask_result['conversation_id']}")
```

--------------------------------

### Handle MCP Protocol Errors in Python

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

This code demonstrates how to handle errors that may occur during MCP protocol requests using the SuperMe SDK. It checks for non-200 status codes and extracts error messages from the JSON response, also including a general exception handler for request failures.

```python
try:
    response = client.raw_request(
        "/mcp",
        json={"method": "tools/call", "params": {"name": "invalid_tool"}}
    )
    if response.status_code != 200:
        print(f"MCP error: {response.json().get('error', 'Unknown error')}")
except Exception as e:
    print(f"MCP request failed: {e}")
```

--------------------------------

### Handle API Errors with Python Requests

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

This snippet demonstrates how to gracefully handle various HTTP-related errors when making requests to the SuperMe API using Python's `requests` library. It includes specific error types like `HTTPError`, `ConnectionError`, and `Timeout`, along with a general `Exception` catch-all.

```python
try:
    answer = client.ask(
        question="What is growth marketing?",
        username="ludo",
        max_tokens=500
    )
    print(answer)
except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
    print(f"Status code: {e.response.status_code}")
    print(f"Response: {e.response.text}")
except requests.exceptions.ConnectionError:
    print("Failed to connect to SuperMe API. Check your network connection.")
except requests.exceptions.Timeout:
    print("Request timed out. Try again later.")
except Exception as e:
    print(f"Unexpected error: {e}")
```

--------------------------------

### List Conversations using MCP List Conversations Tool

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

This code snippet shows how to list existing conversations using the MCP 'list_conversations' tool. It makes a raw API request to the '/mcp' endpoint and parses the JSON response to display the number of conversations found.

```python
conv_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "list_conversations",
            "arguments": {"limit": 5}
        }
    }
)
conversations = json.loads(conv_response.json()["content"][0]["text"])
print(f"Found {len(conversations)} conversations")
```

--------------------------------

### Anonymous Question using MCP

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Sends an anonymous question using the MCP protocol. Requires the 'ask' tool to be available. It takes a username, question, and an incognito flag as input, returning a JSON response.

```python
anon_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "ask",
            "arguments": {
                "username": "ludo",
                "question": "What are your competitive advantages?",
                "incognito": True
            }
        }
    }
)

anon_result = json.loads(anon_response.json()["content"][0]["text"])
print(f"Anonymous response: {anon_result['response']}")
```

--------------------------------

### ask_with_history

Source: https://github.com/superme-ai/superme-sdk/blob/main/README.md

Asks a question while maintaining conversation history.

```APIDOC
## ask_with_history

Ask a question with conversation history.

### Method

```python
ask_with_history(messages, username="ludo", conversation_id=None, max_tokens=1000, incognito=False, **kwargs) -> tuple[str, str]
```

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

- **messages** (list) - List of messages in OpenAI format.
- **username** (str) - SuperMe username to query (default: `"ludo"`).
- **conversation_id** (str) - Continue existing conversation (optional).
- **max_tokens** (int) - Maximum tokens in response (default: `1000`).
- **incognito** (bool) - When True, the user asking the question will be anonymous (default: `False`).
- **kwargs** - Additional arguments to pass to OpenAI client.

### Request Example

```python
# Example usage within the SDK, not a direct API request example
conversation_history = [
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi there! How can I help you?"}
]
response_text, conversation_id = client.ask_with_history(conversation_history, username="user123")
```

### Response

#### Success Response (200)

- **response_text** (str) - AI response as string.
- **conversation_id** (str) - The ID of the conversation.

#### Response Example

```json
{
  "response_text": "I am doing well, thank you!",
  "conversation_id": "conv_abc123"
}
```
```

--------------------------------

### List Conversations using MCP

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Lists recent conversations using the MCP protocol. Requires the 'list_conversations' tool. It accepts a limit for the number of conversations to retrieve and returns a JSON array of conversation objects.

```python
import json
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# List recent conversations
conv_response = client.raw_request(
    "/mcp",
    json={
        "method": "tools/call",
        "params": {
            "name": "list_conversations",
            "arguments": {
                "limit": 10
            }
        }
    }
)

conversations = json.loads(conv_response.json()["content"][0]["text"])
print(f"Found {len(conversations)} conversations")

for conv in conversations[:3]:
    print(f"ID: {conv['id']}")
    print(f"Created: {conv.get('created_at', 'N/A')}")
    print(f"Messages: {conv.get('message_count', 0)}
")
```

--------------------------------

### Multi-Turn Conversations with History using SuperMe SDK

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Manage multi-turn conversations by maintaining message history and passing a conversation ID. Supports both standard and anonymous modes.

```python
from superme_sdk import SuperMeClient

client = SuperMeClient(api_key="your-api-key")

# Start a conversation
messages = [
    {"role": "user", "content": "What is product-market fit?"}
]

response1, conv_id = client.ask_with_history(
    messages=messages,
    username="ludo",
    max_tokens=200
)
print(f"Response 1: {response1}")
print(f"Conversation ID: {conv_id}")

# Continue the conversation with context
messages.append({"role": "assistant", "content": response1})
messages.append({"role": "user", "content": "How do you measure it?"})

response2, conv_id = client.ask_with_history(
    messages=messages,
    username="ludo",
    conversation_id=conv_id,
    max_tokens=200
)
print(f"Response 2: {response2}")

# Anonymous multi-turn conversation
 anon_messages = [
    {"role": "user", "content": "What is growth hacking?"}
]

anon_response1, anon_conv_id = client.ask_with_history(
    messages=anon_messages,
    username="ludo",
    incognito=True
)
print(f"Anonymous response: {anon_response1}")
```

--------------------------------

### MCP Protocol - List Conversations

Source: https://context7.com/superme-ai/superme-sdk/llms.txt

Retrieves a list of recent conversations from the MCP protocol.

```APIDOC
## POST /mcp - List Conversations

### Description
This endpoint retrieves a list of recent conversations managed by the MCP protocol. You can specify a limit for the number of conversations to retrieve.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - The method to call, should be 'tools/call'.
- **params** (object) - Required - Parameters for the tool call.
  - **name** (string) - Required - The name of the tool, should be 'list_conversations'.
  - **arguments** (object) - Required - Arguments for the 'list_conversations' tool.
    - **limit** (integer) - Optional - The maximum number of conversations to return.

### Request Example
```json
{
    "method": "tools/call",
    "params": {
        "name": "list_conversations",
        "arguments": {
            "limit": 10
        }
    }
}
```

### Response
#### Success Response (200)
- **content** (array) - Contains the response from the tool call.
  - **text** (string) - The actual response content, which is a JSON array of conversation objects.
    - Each conversation object may contain fields like `id`, `created_at`, `message_count`.

#### Response Example
```json
{
  "content": [
    {
      "text": "[{"id": "conv_xyz789", "created_at": "2023-10-27T10:00:00Z", "message_count": 5}, ... ]"
    }
  ]
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.