Cross-SDK Consistency Review

I've reviewed this PR for consistency with the other SDK implementations (Node.js/TypeScript, Go, and .NET). The Python SDK is converting response types from TypedDict to dataclasses, which is great for consistency within Python. However, I've identified one cross-SDK inconsistency to consider:

❌ Inconsistency Found: StopError dataclass

Python SDK (this PR):

async def stop(self) -> list[StopError]:
    # Returns list of StopError dataclasses with 'message' field
    errors: list[StopError] = []
    errors.append(StopError(message=f"Failed to destroy session..."))
    return errors

Node.js/TypeScript SDK:

async stop(): Promise(Error[]) {
    // Returns native Error objects
    const errors: Error[] = [];
    errors.push(new Error(`Failed to destroy session...`));
    return errors;
}

Go SDK:

func (c *Client) Stop() []error {
    // Returns native error slice
    var errors []error
    errors = append(errors, fmt.Errorf("failed to destroy session..."))
    return errors
}

.NET SDK:

public async Task StopAsync() {
    // Throws AggregateException instead of returning errors
    var errors = new List(Exception)();
    errors.Add(new Exception($"Failed to destroy session..."));
    ThrowErrors(errors); // Throws instead of returning
}

Recommendation

Consider these options for consistency:

1. Option A (Preferred): Return native Python Exception objects in stop() to match Node.js and Go:

   async def stop(self) -> list[Exception]:
       errors: list[Exception] = []
       errors.append(Exception(f"Failed to destroy session {session.session_id}: {e}"))
       return errors

2. Option B: Keep StopError dataclass but update other SDKs to use similar wrapper types (more invasive)

3. Option C: Keep current implementation but document the cross-language difference

All Other Response Types: ✅ Consistent

The dataclass conversions for PingResponse, GetStatusResponse, GetAuthStatusResponse, ModelInfo, and SessionMetadata are consistent with other SDKs:

• Node.js/TypeScript uses interfaces
• Go uses structs
• .NET uses classes
• Python now uses dataclasses

All expose object-oriented APIs with attribute/property access, which aligns perfectly.

Note: This is a suggestion for maintaining cross-SDK consistency, not a blocking issue. The current implementation is functional and improves Python's internal consistency.

AI generated by SDK Consistency Review Agent

Cross-SDK Consistency Review ✅

I've reviewed this PR for consistency across all four SDK implementations (Python, TypeScript, Go, and .NET).

Summary

This PR successfully aligns the Python SDK with the other SDKs by converting return types from raw dicts (TypedDict) to dataclasses. This is excellent for API consistency!

Current State After This PR

Minor Inconsistency Noted (Not a blocker for this PR)

The TypeScript SDK's ping() method returns an inline anonymous object type:

Promise<{ message: string; timestamp: number; protocolVersion?: number }>

While all other SDKs (including Python after this PR) use a named type like PingResponse. This is a minor inconsistency that could be addressed in a future TypeScript PR to define a PingResponse interface.

Recommendation

✅ This PR maintains good cross-SDK consistency. The Python SDK now properly returns typed objects instead of raw dicts, matching the pattern used in Go and .NET.

No changes needed to this PR. Great work on improving the Python SDK's type consistency!

AI generated by SDK Consistency Review Agent