Skip to content

Models

Response model classes (mirror OpenAI SDK objects).

Message

A single chat message.

Source code in superme_sdk/models.py 
 9
10
11
12
13
14
class Message:
    """A single chat message."""

    def __init__(self, data: dict) -> None:
        self.role: str = data.get("role", "assistant")
        self.content: str = data.get("content", "") or ""

Choice

One completion choice.

Source code in superme_sdk/models.py 
17
18
19
20
21
22
23
class Choice:
    """One completion choice."""

    def __init__(self, data: dict) -> None:
        self.index: int = data.get("index", 0)
        self.message = Message(data.get("message") or {})
        self.finish_reason: Optional[str] = data.get("finish_reason")

Usage

Token usage statistics.

Source code in superme_sdk/models.py 
26
27
28
29
30
31
32
class Usage:
    """Token usage statistics."""

    def __init__(self, data: dict) -> None:
        self.prompt_tokens: int = data.get("prompt_tokens", 0)
        self.completion_tokens: int = data.get("completion_tokens", 0)
        self.total_tokens: int = data.get("total_tokens", 0)

ChatCompletion

OpenAI-compatible chat completion response.

SuperMe-specific fields (metadata) are preserved as attributes.

Source code in superme_sdk/models.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
class ChatCompletion:
    """OpenAI-compatible chat completion response.

    SuperMe-specific fields (``metadata``) are preserved as attributes.
    """

    def __init__(self, data: dict) -> None:
        self.id: str = data.get("id", "")
        self.object: str = data.get("object", "chat.completion")
        self.created: int = data.get("created", 0)
        self.model: str = data.get("model", "")
        self.choices: list[Choice] = [Choice(c) for c in data.get("choices", [])]
        self.usage = Usage(data.get("usage") or {})
        self.metadata: Optional[dict] = data.get("metadata")

StreamEvent dataclass

A single event yielded by streaming methods.

Example::

for event in client.ask_my_agent_stream("Summarise my last 3 posts"):
    if event.done:
        print("conversation_id:", event.conversation_id)
    else:
        print(event.text, end="", flush=True)

Attributes:

Name Type Description
text str

Text chunk (empty string on the done event).
done bool

True on the final event — no more events will follow.
conversation_id Optional[str]

Populated on the done event so callers can capture the ID without making a second API call.
Source code in superme_sdk/models.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@dataclass
class StreamEvent:
    """A single event yielded by streaming methods.

    Example::

        for event in client.ask_my_agent_stream("Summarise my last 3 posts"):
            if event.done:
                print("conversation_id:", event.conversation_id)
            else:
                print(event.text, end="", flush=True)

    Attributes:
        text: Text chunk (empty string on the done event).
        done: True on the final event — no more events will follow.
        conversation_id: Populated on the done event so callers can capture the ID
            without making a second API call.
    """

    text: str = field(default="")
    done: bool = field(default=False)
    conversation_id: Optional[str] = field(default=None)