v1.0 Readiness Assessment — Pre-release Checklist

[johnxing-amigo]

Python SDK v1.0 Readiness Assessment

Current version: 0.137.1 | Target: 1.0.0

Must-Fix (Breaking Changes)

• Rename PermissionError to ForbiddenError — shadows builtins.PermissionError, will cause confusion
• Rename sync client aclose() to close() — the "a" prefix conventionally means "async"; confusing on AmigoClient and AmigoHttpClient
• Normalize resource property names to plural — currently client.conversation (singular) vs client.users (plural). Standardize to: client.conversations, client.services, client.organizations, client.users
• Align method naming — organization.get() vs user.get_users(). Pick one convention

Should-Fix (Design Improvements)

• Export AmigoConfig and all error classes from __init__.py — currently users must import from submodules
• Add mypy/pyright to CI — py.typed marker exists but no type checker runs
• Move GetMessageSourceResponse to models.py — hand-written Pydantic model in resource file is maintenance risk
• Remove dead InteractionInput TypedDict or prefix with _
• Wrap *ParametersQuery types — generated names like GetUsersParametersQuery leak code-gen naming scheme
• Streaming return types — annotate as AsyncIterator[T] / Iterator[T] instead of AsyncGenerator
• Remove scripts/ from wheel build — packages = ["src/amigo_sdk", "scripts"] ships code-gen scripts
• Add license and urls fields to pyproject.toml

Missing API Coverage (~75% of endpoints missing)

Entire resource categories not in SDK:

• Agents & Context Graphs — CRUD + versioning for agents and context graphs
• Tools — 14 endpoints: create, list, update, publish, invoke, deprecate, env vars, test, invocations
• Dynamic Behaviors — CRUD + versioning + invocations + search
• Metrics — CRUD + evaluate + evaluation results + search
• Simulations — 5 sub-resources (personas, scenarios, unit tests, unit test sets, runs), each with CRUD + versioning
• Admin — get_models, get_prompt_logs, sql_query

Missing endpoints within existing resources:

• Organization — create (PUT), modify (POST), delete (DELETE), get user dimensions
• Service — create (POST), update (POST), version sets (GET)
• User — search, modify variables, get memories, sign in with email
• Conversation — real-time WebSocket (converse_realtime)

Nice-to-Have

• Pagination helpers (auto-follow continuation_token)
• __repr__ on AmigoClient / AsyncAmigoClient
• Configurable timeout at client level (currently only via **httpx_kwargs)

Summary

The SDK has a solid core (dual sync/async, proper auth/retry/streaming, clean error hierarchy, generated models) but covers ~20-25% of the documented API surface. Minimum bar for 1.0: fix the 4 breaking naming issues, complete the public export surface, add type checking to CI, and add at least the resource categories referenced in the developer guide's Python SDK examples.

🤖 Generated with Claude Code