Implement Production-Ready Azure Cosmos DB Services

This skill teaches an agent to build a production-grade Azure Cosmos DB NoSQL service in Python, layered as a FastAPI router, a service layer (business logic, document-to-model conversion, graceful degradation), and a Cosmos DB client module (singleton container, dual authentication, async wrapper via run_in_threadpool). It defines a five-tier Pydantic model pattern - Base, Create, Update, response model, InDB - for clean separation between API and storage shapes, and prescribes writing tests before implementation. It also names the non-functional properties this architecture is meant to deliver: retry logic with exponential backoff for transient failures, connection pooling through the singleton client, partition-key-scoped queries that avoid cross-partition scans, and dependency injection through get_container() so services can be unit-tested without a real Cosmos account.

Use it when adding or refactoring a Cosmos DB-backed service behind a FastAPI app that needs RBAC authentication in Azure, an emulator fallback for local development, parameterized queries, and partition-key-aware access control. It is not a general Cosmos DB tutorial - it is opinionated toward a specific layered architecture (client module, service layer, router) with TDD and a five-tier model pattern, so it fits best when a codebase already follows, or is willing to adopt, that structure.

Inputs: COSMOS_ENDPOINT, COSMOS_DATABASE_NAME, and COSMOS_CONTAINER_ID as environment variables, plus COSMOS_KEY for the local emulator only. Authentication is DefaultAzureCredential against a real Cosmos account, or the well-known emulator key with connection_verify=False against https://localhost:8081. Outputs: a singleton get_container() accessor used by service methods, Pydantic response models built by _doc_to_model() / _model_to_doc() conversion helpers, and, for services, None or [] returned gracefully when Cosmos is unavailable rather than an exception.

Azure Cosmos DB (via azure-cosmos), Azure Identity (DefaultAzureCredential) for RBAC auth, FastAPI (auth dependencies, HTTPException error responses, run_in_threadpool for async wrapping of the sync SDK), Pydantic for the model hierarchy, and pytest / pytest-mock / pytest-asyncio for the prescribed TDD workflow, including a mocker.patch pattern for mocking get_container(). The skill also ships reference files for client setup, the service layer, testing, partitioning, and error handling, plus ready-to-use template files for the client module, a service class skeleton, and pytest fixtures.

pip install azure-cosmos azure-identity

Python and FastAPI developers building or maintaining a Cosmos DB-backed service who want a consistent, security-conscious architecture - RBAC auth, parameterized queries, partition-key isolation, graceful degradation, and test-first development - rather than ad hoc Cosmos client calls scattered through route handlers.