Azure / Azure/azure-sdk-for-python
[Cosmos] [Embedding V0] New azure-cosmos-embedding package — scaffold
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 3.4k
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 202
Description
# [Cosmos] [Embedding V0] New `azure-cosmos-embedding` package — scaffold
Parent: [#46729](https://github.com/Azure/azure-sdk-for-python/issues/46729)
## Background
The concrete embedding provider implementation (Azure OpenAI) ships as a **separate optional package**, analogous to the .NET `Microsoft.Azure.Cosmos.Embedding` package. This keeps `azure-cosmos` free of `openai` / `azure-ai-inference` dependencies for the majority of customers who do not use vector search.
- Core package: `azure-cosmos` — defines `EmbeddingGenerator` / `AsyncEmbeddingGenerator` Protocol only.
- Provider package: `azure-cosmos-embedding` — ships `AzureOpenAIEmbeddingGenerator` (and any future providers).
## Scope
Scaffold the new package directory (no business logic yet — that is in the next sub-issue):
```
sdk/cosmos/azure-cosmos-embedding/
setup.py
setup.cfg (or pyproject.toml)
README.md
CHANGELOG.md
azure/
cosmos/
embedding/
__init__.py # exports AzureOpenAIEmbeddingGenerator
_version.py
py.typed # PEP 561 marker
```
### setup.py requirements
```python
PACKAGE_NAME = "azure-cosmos-embedding"
install_requires = [
"azure-cosmos>=4.9.0", # for EmbeddingGenerator Protocol
"openai>=1.35.0", # Azure OpenAI client (azure.ai.openai uses this)
"azure-identity>=1.16.0" # for DefaultAzureCredential (Entra auth)
]
python_requires = ">=3.9"
```
### ci.yml additions
Add `azure-cosmos-embedding` to the `sdk/cosmos/ci.yml` packages list so it is picked up by the Azure SDK CI framework.
### Namespace package alignment
The `azure/cosmos/embedding/` namespace must have an empty `azure/__init__.py` and `azure/cosmos/__init__.py` (PEP 420 namespace packages) so it coexists cleanly with `azure-cosmos` when both are installed.
## Acceptance criteria
- `pip install -e sdk/cosmos/azure-cosmos-embedding/` succeeds with the two dependencies installed.
- `from azure.cosmos.embedding import AzureOpenAIEmbeddingGenerator` raises `ImportError` (stub not yet implemented — expected at this stage).
- `python -m pytest sdk/cosmos/azure-cosmos-embedding/tests/ --collect-only` exits 0 (empty but valid test suite).
- Package listed in `sdk/cosmos/ci.yml`.
## Files likely touched
- `sdk/cosmos/azure-cosmos-embedding/` (new folder tree)
- `sdk/cosmos/ci.yml` (add package to list)
## Dependencies
- #46730 — needs `EmbeddingGenerator` protocol to be defined in `azure-cosmos`.
Contributor guide
Research direction
Start with sdk/cosmos/ci.yml and the listed sdk/cosmos/azure-cosmos-embedding/ package tree, then run the stated editable-install and pytest collection commands. Done means the scaffold and namespace files exist, the package is listed in CI, installation succeeds with the specified dependencies, the import raises the expected ImportError, and test collection exits 0.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, python
- Domain
- cloud, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 73/100