Skip to content

Chat

Chat proxy classes (client.chat.completions.create).

Completions

Proxy for client.chat.completions.

Source code in superme_sdk/_chat_proxy.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
class Completions:
    """Proxy for ``client.chat.completions``."""

    def __init__(self, client: "SuperMeClient") -> None:
        self._client = client

    def create(
        self,
        messages: list,
        model: str = "gpt-4",
        *,
        username: str = "ludo",
        conversation_id: Optional[str] = None,
        max_tokens: int = 1000,
        incognito: bool = False,
        response_format: Optional[dict] = None,
        **kwargs: Any,
    ) -> ChatCompletion:
        """Create a chat completion via the MCP ``ask`` tool.

        Example:
            ```python
            response = client.chat.completions.create(
                model="gpt-4",
                messages=[{"role": "user", "content": "What is PMF?"}],
                username="ludo",
            )
            print(response.choices[0].message.content)
            print(response.metadata["conversation_id"])
            ```

        Note:
            **OpenAI compat quirks** — this wraps the SuperMe MCP ``ask`` tool,
            not a real OpenAI endpoint:

            - ``model`` — ignored. The SuperMe AI determines the model.
            - ``messages`` — only the last ``role: user`` message is sent.
              Prior messages in the list are **not** forwarded; pass
              ``conversation_id`` to continue a thread.
            - ``max_tokens`` — ignored by the MCP backend.
            - ``response_format`` — not supported, ignored.

        Args:
            messages: List of ``{"role": ..., "content": ...}`` dicts.
                Only the last user message is sent to the API.
            model: Ignored — kept for OpenAI interface compatibility.
            username: Target SuperMe username.
            conversation_id: Continue an existing conversation.
            max_tokens: Ignored — kept for OpenAI interface compatibility.
            incognito: Ask anonymously.
            response_format: Not supported, ignored.

        Returns:
            :class:`ChatCompletion` with ``.choices[0].message.content``
            and ``.metadata["conversation_id"]``.
        """
        # Backward-compat: pre-hardening callers used extra_body={"username": ...}
        # to pass routing params through the OpenAI-compatible interface.
        # Extract any recognised fields from extra_body and let them override
        # the direct kwargs so old call sites keep working without changes.
        extra_body: dict = kwargs.pop("extra_body", {}) or {}
        if "username" in extra_body:
            username = extra_body["username"]
        if "incognito" in extra_body:
            incognito = extra_body["incognito"]
        if "conversation_id" in extra_body:
            conversation_id = extra_body["conversation_id"]

        # Extract the last user message as the question
        question = ""
        for msg in reversed(messages):
            if msg.get("role") == "user":
                question = msg.get("content", "")
                break

        if not question:
            raise ValueError("messages must contain at least one user message")

        args: dict[str, Any] = {
            "identifier": username,
            "question": question,
        }
        if conversation_id:
            args["conversation_id"] = conversation_id
        if incognito:
            args["incognito"] = True

        result = self._client._mcp_tool_call("ask", args)

        # Build an OpenAI-shaped ChatCompletion from the MCP result
        return ChatCompletion(
            {
                "id": f"chatcmpl-{uuid.uuid4().hex[:12]}",
                "object": "chat.completion",
                "created": int(time.time()),
                "model": model,
                "choices": [
                    {
                        "index": 0,
                        "message": {
                            "role": "assistant",
                            "content": result.get("response", ""),
                        },
                        "finish_reason": "stop",
                    }
                ],
                "usage": {},
                "metadata": {
                    "conversation_id": result.get("conversation_id"),
                    "target_user": result.get("target_user"),
                    "target_user_id": result.get("target_user_id"),
                },
            }
        )

create 

create(
    messages: list,
    model: str = "gpt-4",
    *,
    username: str = "ludo",
    conversation_id: Optional[str] = None,
    max_tokens: int = 1000,
    incognito: bool = False,
    response_format: Optional[dict] = None,
    **kwargs: Any,
) -> ChatCompletion

Create a chat completion via the MCP ask tool.

Example 
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What is PMF?"}],
    username="ludo",
)
print(response.choices[0].message.content)
print(response.metadata["conversation_id"])
Note

OpenAI compat quirks — this wraps the SuperMe MCP ask tool, not a real OpenAI endpoint:

  • model — ignored. The SuperMe AI determines the model.
  • messages — only the last role: user message is sent. Prior messages in the list are not forwarded; pass conversation_id to continue a thread.
  • max_tokens — ignored by the MCP backend.
  • response_format — not supported, ignored.

Parameters:

Name Type Description Default
messages list

List of {"role": ..., "content": ...} dicts. Only the last user message is sent to the API.

 required
model str

Ignored — kept for OpenAI interface compatibility.

 'gpt-4'
username str

Target SuperMe username.

 'ludo'
conversation_id Optional[str]

Continue an existing conversation.

 None
max_tokens int

Ignored — kept for OpenAI interface compatibility.

 1000
incognito bool

Ask anonymously.

 False
response_format Optional[dict]

Not supported, ignored.

 None

Returns:

Type Description
ChatCompletion

class:ChatCompletion with .choices[0].message.content
ChatCompletion

and .metadata["conversation_id"].
Source code in superme_sdk/_chat_proxy.py 
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def create(
    self,
    messages: list,
    model: str = "gpt-4",
    *,
    username: str = "ludo",
    conversation_id: Optional[str] = None,
    max_tokens: int = 1000,
    incognito: bool = False,
    response_format: Optional[dict] = None,
    **kwargs: Any,
) -> ChatCompletion:
    """Create a chat completion via the MCP ``ask`` tool.

    Example:
        ```python
        response = client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": "What is PMF?"}],
            username="ludo",
        )
        print(response.choices[0].message.content)
        print(response.metadata["conversation_id"])
        ```

    Note:
        **OpenAI compat quirks** — this wraps the SuperMe MCP ``ask`` tool,
        not a real OpenAI endpoint:

        - ``model`` — ignored. The SuperMe AI determines the model.
        - ``messages`` — only the last ``role: user`` message is sent.
          Prior messages in the list are **not** forwarded; pass
          ``conversation_id`` to continue a thread.
        - ``max_tokens`` — ignored by the MCP backend.
        - ``response_format`` — not supported, ignored.

    Args:
        messages: List of ``{"role": ..., "content": ...}`` dicts.
            Only the last user message is sent to the API.
        model: Ignored — kept for OpenAI interface compatibility.
        username: Target SuperMe username.
        conversation_id: Continue an existing conversation.
        max_tokens: Ignored — kept for OpenAI interface compatibility.
        incognito: Ask anonymously.
        response_format: Not supported, ignored.

    Returns:
        :class:`ChatCompletion` with ``.choices[0].message.content``
        and ``.metadata["conversation_id"]``.
    """
    # Backward-compat: pre-hardening callers used extra_body={"username": ...}
    # to pass routing params through the OpenAI-compatible interface.
    # Extract any recognised fields from extra_body and let them override
    # the direct kwargs so old call sites keep working without changes.
    extra_body: dict = kwargs.pop("extra_body", {}) or {}
    if "username" in extra_body:
        username = extra_body["username"]
    if "incognito" in extra_body:
        incognito = extra_body["incognito"]
    if "conversation_id" in extra_body:
        conversation_id = extra_body["conversation_id"]

    # Extract the last user message as the question
    question = ""
    for msg in reversed(messages):
        if msg.get("role") == "user":
            question = msg.get("content", "")
            break

    if not question:
        raise ValueError("messages must contain at least one user message")

    args: dict[str, Any] = {
        "identifier": username,
        "question": question,
    }
    if conversation_id:
        args["conversation_id"] = conversation_id
    if incognito:
        args["incognito"] = True

    result = self._client._mcp_tool_call("ask", args)

    # Build an OpenAI-shaped ChatCompletion from the MCP result
    return ChatCompletion(
        {
            "id": f"chatcmpl-{uuid.uuid4().hex[:12]}",
            "object": "chat.completion",
            "created": int(time.time()),
            "model": model,
            "choices": [
                {
                    "index": 0,
                    "message": {
                        "role": "assistant",
                        "content": result.get("response", ""),
                    },
                    "finish_reason": "stop",
                }
            ],
            "usage": {},
            "metadata": {
                "conversation_id": result.get("conversation_id"),
                "target_user": result.get("target_user"),
                "target_user_id": result.get("target_user_id"),
            },
        }
    )

Chat

Proxy for client.chat.

Source code in superme_sdk/_chat_proxy.py 
131
132
133
134
135
class Chat:
    """Proxy for ``client.chat``."""

    def __init__(self, client: "SuperMeClient") -> None:
        self.completions = Completions(client)