Real-world SDK Feedback: Misleading Docs, Missing Methods, and Response Structure Bugs

[tarun-infiniteloop]

Hi team,

I just finished doing a complete real-world SDK validation of smallestai==3.0.0 on macOS using a Python 3.9 virtual environment, and wanted to share some findings and suggestions to improve the developer experience.

✅ What worked well:

Agent creation

Outbound call (received a real call)

Knowledge base creation

PDF upload to KB

❌ Critical Issues Found:

Misleading Response Object in start_outbound_call()
Docs or dev intuition expect:

print(response.conversation_id)

But it actually lives under response.data.conversation_id. This raises an AttributeError unless you dig deeper manually.
Suggestion: Update docs to show correct access pattern.

No .chat() or simulate method
There’s no way to test basic conversation flows before involving phone calls or campaigns.
Suggestion: Add a simulate() or .chat() method for debugging agent replies via text.

AtomsClient(api_key="...") crashes
This raises a TypeError: got unexpected keyword argument 'api_key'. However, many devs (like me) assume this is valid from past SDK patterns (OpenAI, Hugging Face, etc.).
Suggestion: Either support this or show Configuration() in every example.

Missing Configuration import in docs
None of the code samples mention:

from smallestai.atoms import Configuration

This causes confusion for first-time users.
Suggestion: Add complete import statements to examples.

SSL warnings on macOS
Using Python 3.9 on macOS shows this:

urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 2.8.3'.

Suggestion: Add a macOS compatibility note or offer a fix (e.g., urllib3 pinning).

Thanks for building this — really impressive work overall. With just a few tweaks, this can go from “working” to “incredibly developer-friendly.”

Happy to test further or contribute docs if helpful.

[hamees-sayed]

Thank you so much @tarun-infiniteloop for the review, we'll take this into consideration and add this in the next iteration. We are very open to contribution in terms of suggestions, code and documentation and you are welcome to raise a PR :)