Azure / Azure/azure-sdk-for-python

[Cosmos] [Embedding V0] New azure-cosmos-embedding package — scaffold

Open
#46,765 0 comments 0 reactions 0 assignees View on GitHub
Cosmos
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.