SDK Documentation: 6 issues found (inconsistencies, missing docs, bug, typo) #157
Description
Summary
After auditing the SDK documentation at https://docs.opengradient.ai/developers/sdk/, I found 6 issues across the SDK, x402 gateway, and API reference pages — including naming inconsistencies, missing documentation, a code bug, and a typo.
1. Settlement mode naming mismatch
Pages affected:
- https://docs.opengradient.ai/developers/sdk/llm.html
- https://docs.opengradient.ai/developers/x402/
- https://docs.opengradient.ai/developers/x402/examples.html
The SDK uses SETTLE, SETTLE_METADATA, SETTLE_BATCH but the x402 docs use SETTLE_INDIVIDUAL, SETTLE_INDIVIDUAL_WITH_METADATA, SETTLE_BATCH. The x402 examples page mixes both in the same section.
Suggested fix: Pick one naming convention and use it everywhere. If the SDK intentionally uses short names, add a mapping table showing SETTLE = SETTLE_INDIVIDUAL, SETTLE_METADATA = SETTLE_INDIVIDUAL_WITH_METADATA, etc.
2. Default settlement mode contradiction
Pages affected:
SDK function signatures default to SETTLE_BATCH. The x402 gateway page states SETTLE_INDIVIDUAL is the default.
Suggested fix: Clarify that the defaults differ between the SDK and x402 gateway, or align them to one default. Add a note on each page stating what the other defaults to and why.
3. Model list out of sync
Pages affected:
- https://docs.opengradient.ai/developers/sdk/llm.html (9 models)
- https://docs.opengradient.ai/api_reference/python_sdk/ (16 models)
Seven models in the TEE_LLM enum are missing from the supported models list: CLAUDE_3_7_SONNET, GEMINI_2_0_FLASH, GEMINI_2_5_FLASH_LITE, GROK_2_1212, GROK_2_VISION_LATEST, GROK_4_1_FAST, O4_MINI.
Suggested fix: Either add the missing models to the LLM page's supported list, or mark them as deprecated/experimental in the API reference. Also add a mapping table between string identifiers (openai/gpt-4.1) and enum constants (og.TEE_LLM.GPT_4_1_2025_04_14) so users know which is which.
4. Missing return type documentation
Pages affected:
- https://docs.opengradient.ai/developers/sdk/llm.html
- https://docs.opengradient.ai/api_reference/python_sdk/
TextGenerationOutput and TextGenerationStream are used as return types but their fields/properties are never documented.
Suggested fix: Add a section to the API reference documenting both classes — their fields (e.g. text, payment_hash, usage), types, and a code example showing how to iterate over TextGenerationStream.
5. Bug: mutable default argument
Page affected:
client.llm.chat() signature shows tools: Optional[List[Dict]] = []. A mutable default is a known Python anti-pattern that can cause shared state across calls.
Suggested fix: Change to tools: Optional[List[Dict]] = None in both the implementation and docs.
6. Typo: "initalize"
Page affected:
Text reads: "create_model automatically calls create_version to initalize v0.01"
Suggested fix: Change "initalize" to "initialize".