packaging: resolve the PyPI distribution name collision

[OBaruch]

Problem / motivation

The project currently declares this distribution name in pyproject.toml:

[project]
name = "llm-bridge"
version = "0.1.0"

The README and provider error messages consequently recommend commands such as:

pip install llm-bridge
pip install "llm-bridge[openai]"
pip install "llm-bridge[aws]"
pip install "llm-bridge[google]"
pip install "llm-bridge[all]"

However, the normalized distribution name llm-bridge is already registered on PyPI by an unrelated project:

• PyPI page: https://pypi.org/project/LLM-Bridge/
• PyPI JSON API: https://pypi.org/pypi/llm-bridge/json
• Project currently returned by PyPI: LLM-Bridge version 2.0.8
• Upstream linked by that project: https://github.com/windsnow1025/LLM-Bridge

As a result, pip install llm-bridge resolves to that existing distribution rather than the code in this repository. This creates an incorrect installation path, prevents this project from being published under its current distribution name, and introduces avoidable package-identity and supply-chain confusion for users.

I am not reporting an exploited vulnerability or suggesting any wrongdoing by the existing package owner; this is a naming and packaging collision.

The collision cannot be avoided through capitalization or separator changes. The Python packaging name-normalization specification lowercases names and replaces runs of ., -, and _ with -, so all of these resolve to the same normalized name:

llm-bridge  -> llm-bridge
LLM-Bridge  -> llm-bridge
llm_bridge  -> llm-bridge
llm.bridge  -> llm-bridge

References:

• PyPA names and normalization specification: https://packaging.python.org/en/latest/specifications/name-normalization/
• PEP 503 normalized names: https://peps.python.org/pep-0503/#normalized-names
• Distribution package vs. import package: https://packaging.python.org/en/latest/discussions/distribution-package-vs-import-package/

Proposed solution

Would the maintainers be open to selecting a distinct, namespaced distribution name, while preserving the existing Python import package?

For example, installation could become:

pip install santander-llm-bridge

while the public Python API would remain unchanged:

from llm_bridge import create_llm

The distribution name used by pip and PyPI does not need to match the import package name. Keeping llm_bridge as the import package would avoid an unnecessary API break.

Possible candidates, subject to maintainer preference and rechecking availability immediately before publication:

Candidate	Normalized name	Status checked on 2026-06-21	Notes
santander-llm-bridge	santander-llm-bridge	Not found via the public PyPI JSON API	Explicit brand association; my preliminary preference
santanderai-llm-bridge	santanderai-llm-bridge	Not found via the public PyPI JSON API	Closely matches the GitHub organization
llm-bridge-santander	llm-bridge-santander	Not found via the public PyPI JSON API	Preserves the original phrase first
Maintainer-selected alternative	Depends on choice	To be checked	Leaves naming fully open to project maintainers

I would prefer to align on the public distribution name before preparing a patch because this affects project identity and future release configuration.

After agreement, I can prepare a focused PR that:

• updates [project].name in pyproject.toml;
• updates active installation instructions in the README, examples, provider docstrings, and optional-dependency error messages;
• documents the distinction between the distribution name and import llm_bridge;
• updates CHANGELOG.md;
• adds a small packaging metadata regression test without introducing runtime dependencies;
• builds and inspects both wheel and sdist;
• installs the wheel in a clean environment and verifies from llm_bridge import create_llm plus the offline mock provider;
• verifies the optional extras remain associated with the renamed distribution;
• reviews the release workflow for any name-specific assumptions.

The current .github/workflows/release.yml builds wheel/sdist and attaches them to GitHub Releases. Its PyPI Trusted Publishing job is present but commented out, so the repository does not currently publish to PyPI. Choosing the distribution name before enabling that job would avoid binding Trusted Publishing to the wrong project identity.

Alternatives considered

1. Keep llm-bridge and only document source installation. This avoids a metadata change but leaves the current pip install instructions incorrect and does not provide a viable PyPI publication path.
2. Change only capitalization, underscores, or dots. This does not work because PyPI normalizes all those variants to llm-bridge.
3. Rename both the distribution and the import package. This would create an unnecessary breaking API change; the import package can remain llm_bridge independently.
4. Request transfer of the existing PyPI name. The existing name is actively used by an unrelated project, so a distinct project-specific distribution name appears clearer and less disruptive.

Additional context

Local inspection was performed against commit 5d14ee9 (v0.1.0). The repository currently has no packaging/metadata regression test; its tests cover the public interface, registry, dependency-free providers, and stubbed cloud adapters.

All occurrences of the active installation name would need contextual review rather than a blind replacement because repository URLs, import paths, CODEOWNERS team names, and historical references may legitimately retain llm_bridge or llm-bridge.

Verification date: 2026-06-21.

I am happy to implement the agreed solution once the maintainers select a distribution name.