Public python API inconsistency: some methods return models, others return raw dicts

[SilentDemonSD]

The Python Copilot SDK currently exposes a mixed public API surface: some higher-level methods return dataclass-based models (generated from NodeJS definitions), while others return raw JSON-RPC dicts typed only via TypedDict (e.g. get_status(), list_sessions()).

I understand that the underlying JsonRpcClient intentionally returns dicts at the transport layer, but at the SDK boundary this leads to an inconsistent abstraction and unclear guidance for users (object attributes vs dict access).

Some responses are represented as dataclasses generated from NodeJS definitions which are generated, with explicit serialization helpers:

copilot/generated/session_events.py

@dataclass
class ContextClass:
    ...
    @staticmethod
    def from_dict(...)

These expose a clear, object-oriented API to SDK users.

Moreover Sample: 

>>> sess = await client.create_session()
>>> sess
<copilot.session.CopilotSession object at 0x000002292C6F7E00>

Other public methods return raw JSON-RPC responses directly:

async def get_status(self) -> GetStatusResponse:
    return await self._client.request("status.get", {})

>>> await client.get_status()
{'version': '0.0.394', 'protocolVersion': 2}

This should return GetStatusResponse ?

Could you clarify whether the intended direction is to consistently expose object-based models at the public API level, with dicts treated as an internal detail? @friggeri

Happy to help refactor or align missing response types if this matches the design intent.

[github-actions]

Thank you for opening this issue, @SilentDemonSD!

I've labeled this as sdk/python and enhancement since you're raising a valid API consistency concern about the Python SDK's return types. The issue is well-documented with clear examples showing the inconsistency between dataclass-based models (like CopilotSession) and raw dict responses (like get_status()).

A maintainer will review this and clarify the intended API design direction. Your offer to help with refactoring is appreciated!

AI generated by Issue Triage Agent

[Scarage1]

Thanks for raising this — I agree the current mix of raw dict / TypedDict responses and model-based responses makes the public API feel inconsistent.

A clean way forward could be to standardize on a model-first public API, where:
-All public SDK methods return typed models / dataclasses
-Raw JSON dicts remain internal to the JSON-RPC / transport layer

Concretely:
-Introduce response models for methods that currently return plain dicts (e.g. get_status, list_sessions)
-Convert RPC responses to these models at the SDK boundary (e.g. Model.from_dict(...))
-Keep backward compatibility internally while improving IDE autocomplete, type safety, and API predictability for users

This would align well with the rest of the SDK, improve developer experience, and avoid leaking low-level response shapes into user code. Happy to help implement or iterate on this if the direction makes sense

[abhijitsingh10]

Introduce / use response models consistently

If this already exists:

class GetStatusResponse(TypedDict):
version: str
protocolVersion: int

That’s still not enough for a public SDK API. Prefer a dataclass:

@DataClass(frozen=True)
class GetStatus:
version: str
protocol_version: int

@staticmethod
def from_dict(data: dict) -> "GetStatus":
    return GetStatus(
        version=data["version"],
        protocol_version=data["protocolVersion"],
    )

Convert at the SDK boundary
async def get_status(self) -> GetStatus:
raw = await self._client.request("status.get", {})
return GetStatus.from_dict(raw)

Now users get:

status = await client.get_status()
status.version
status.protocol_version

No ambiguity. No dict poking.

// this may help to fix this issue...

[SilentDemonSD]

yep, thats the core plan, so that no ambiguity and simple as it is intended too with proper support for low level workups too (handling future attributes) and Enum for all constants for no workaround searches.