models-provider 0.1.0__tar.gz

models_provider-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.log

models_provider-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giovanni Gravili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

models_provider-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: models-provider
+Version: 0.1.0
+Summary: An independent models.dev catalogue and interchangeable model provider layer.
+Project-URL: Repository, https://github.com/ghovax/models-provider
+Project-URL: Issues, https://github.com/ghovax/models-provider/issues
+Author: Giovanni Gravili
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,langchain,llm,models,providers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: litellm>=1.60.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: websockets<16,>=15.0
+Description-Content-Type: text/markdown
+
+# Models Provider
+
+Models Provider gives applications one interface for selecting models, resolving provider access, creating chat models, and collecting usage. Model metadata is loaded privately from the public [models.dev catalogue](https://models.dev).
+
+## Installation
+
+```console
+pip install models-provider
+```
+
+## Public flow
+
+Pass provider values directly to `Models`, then select a provider-qualified model:
+
+```python
+from models_provider import Models
+
+models = Models({
+    "openai": "OPENAI_API_KEY",
+})
+
+model = models.chat(
+    "openai/gpt-4.1-mini",
+    temperature=0.2,
+    top_p=0.9,
+)
+
+answer = model.invoke("Explain spaced repetition in two sentences.")
+```
+
+`Models()` fetches the fixed models.dev catalogue once during initialization and caches it internally. Applications do not load or construct a catalogue.
+
+The model identifier describes the model publisher, not the authentication mechanism. The access implementation is selected internally from the provider and the supplied values. For example, `openai/gpt-5` remains the model identifier when the available access is an API key or an OpenAI account session.
+
+## Provider values
+
+The constructor accepts one ordinary dictionary. Values can be literal credentials, environment-variable names, or provider-specific mappings:
+
+```python
+Models({"openai": "sk-proj-...7Qx2"})
+```
+
+```python
+Models({"openai": "OPENAI_API_KEY"})
+```
+
+An uppercase environment-variable name is resolved from the process environment. Persistence is owned by the embedding application; Models Provider does not expose a credential-store abstraction or load credential files.
+
+## OAuth
+
+OAuth values use the same dictionary. The host controls how the authorization URL is displayed:
+
+```python
+models = Models()
+
+authorization = await models.sign_in("openai")
+# The host uses authorization.url to open the authorization page for the user.
+await authorization.complete()
+
+model = models.chat("openai/gpt-5", authorization=authorization)
+```
+
+The login flow and token refresh are provider-owned. Each authorization is independent, so the same `Models` instance can serve different users. The host decides whether and how to persist a user's authorization values.
+
+## Model contract
+
+```python
+models.chat(
+    "provider/model",
+    temperature=0.2,
+    top_p=0.9,
+    reasoning_effort="high",
+    max_output_tokens=512,
+) -> BaseChatModel
+```
+
+Request settings are ordinary keyword arguments. The selected access implementation validates and translates them to its transport. There is no public options object and no provider-specific access class required from the caller.
+
+## Usage values
+
+Normalized usage is grouped by measurement type:
+
+```python
+usage.tokens.input_tokens
+usage.tokens.reasoning_tokens
+usage.cache.cache_read_tokens
+usage.audio.output_audio_tokens
+usage.cost.cost_usd
+```
+
+`UsageLedger` owns accumulation when an application records multiple responses.
+
+## Ownership
+
+Models Provider owns:
+
+- the private models.dev catalogue and its built-in cache;
+- provider and model selection;
+- provider-specific authentication and transport;
+- request-option normalization;
+- usage normalization.
+
+The embedding application owns:
+
+- the provider-values dictionary;
+- credential persistence, if needed;
+- application workflows, sessions, tools, permissions, and files.

models_provider-0.1.0/README.md

@@ -0,0 +1,107 @@
+# Models Provider
+
+Models Provider gives applications one interface for selecting models, resolving provider access, creating chat models, and collecting usage. Model metadata is loaded privately from the public [models.dev catalogue](https://models.dev).
+
+## Installation
+
+```console
+pip install models-provider
+```
+
+## Public flow
+
+Pass provider values directly to `Models`, then select a provider-qualified model:
+
+```python
+from models_provider import Models
+
+models = Models({
+    "openai": "OPENAI_API_KEY",
+})
+
+model = models.chat(
+    "openai/gpt-4.1-mini",
+    temperature=0.2,
+    top_p=0.9,
+)
+
+answer = model.invoke("Explain spaced repetition in two sentences.")
+```
+
+`Models()` fetches the fixed models.dev catalogue once during initialization and caches it internally. Applications do not load or construct a catalogue.
+
+The model identifier describes the model publisher, not the authentication mechanism. The access implementation is selected internally from the provider and the supplied values. For example, `openai/gpt-5` remains the model identifier when the available access is an API key or an OpenAI account session.
+
+## Provider values
+
+The constructor accepts one ordinary dictionary. Values can be literal credentials, environment-variable names, or provider-specific mappings:
+
+```python
+Models({"openai": "sk-proj-...7Qx2"})
+```
+
+```python
+Models({"openai": "OPENAI_API_KEY"})
+```
+
+An uppercase environment-variable name is resolved from the process environment. Persistence is owned by the embedding application; Models Provider does not expose a credential-store abstraction or load credential files.
+
+## OAuth
+
+OAuth values use the same dictionary. The host controls how the authorization URL is displayed:
+
+```python
+models = Models()
+
+authorization = await models.sign_in("openai")
+# The host uses authorization.url to open the authorization page for the user.
+await authorization.complete()
+
+model = models.chat("openai/gpt-5", authorization=authorization)
+```
+
+The login flow and token refresh are provider-owned. Each authorization is independent, so the same `Models` instance can serve different users. The host decides whether and how to persist a user's authorization values.
+
+## Model contract
+
+```python
+models.chat(
+    "provider/model",
+    temperature=0.2,
+    top_p=0.9,
+    reasoning_effort="high",
+    max_output_tokens=512,
+) -> BaseChatModel
+```
+
+Request settings are ordinary keyword arguments. The selected access implementation validates and translates them to its transport. There is no public options object and no provider-specific access class required from the caller.
+
+## Usage values
+
+Normalized usage is grouped by measurement type:
+
+```python
+usage.tokens.input_tokens
+usage.tokens.reasoning_tokens
+usage.cache.cache_read_tokens
+usage.audio.output_audio_tokens
+usage.cost.cost_usd
+```
+
+`UsageLedger` owns accumulation when an application records multiple responses.
+
+## Ownership
+
+Models Provider owns:
+
+- the private models.dev catalogue and its built-in cache;
+- provider and model selection;
+- provider-specific authentication and transport;
+- request-option normalization;
+- usage normalization.
+
+The embedding application owns:
+
+- the provider-values dictionary;
+- credential persistence, if needed;
+- application workflows, sessions, tools, permissions, and files.

models_provider-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "models-provider"
+version = "0.1.0"
+description = "An independent models.dev catalogue and interchangeable model provider layer."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Giovanni Gravili" }]
+keywords = ["ai", "llm", "models", "providers", "langchain"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.0",
+    "langchain-core>=1.0",
+    "litellm>=1.60.0",
+    "pydantic>=2.0.0",
+    "websockets>=15.0,<16",
+]
+
+[project.urls]
+Repository = "https://github.com/ghovax/models-provider"
+Issues = "https://github.com/ghovax/models-provider/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/models_provider"]
+
+[tool.hatch.build]
+include = ["src/models_provider/**/*.py", "src/models_provider/py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "B", "ASYNC", "RUF006", "RUF012", "RUF018", "RUF019"]

models_provider-0.1.0/src/models_provider/__init__.py

@@ -0,0 +1,55 @@
+"""Public model-selection and authorization interface."""
+
+from .auth import (
+    DeviceLoginFlow,
+    HostedAuthorization,
+    LoginFlow,
+    OAuthAdapter,
+    OAuthAuthorization,
+    OAuthAuthorizationRequest,
+    OAuthConfiguration,
+    OAuthLoginFlow,
+    OAuthProvider,
+    OAuthTokens,
+)
+from .catalogue import ModelProvider, ModelRecord, ProviderRecord
+from .client import Models
+from .errors import AuthenticationError, ContextWindowError
+from .usage import (
+    AudioUsage,
+    CacheUsage,
+    CostUsage,
+    ModelUsage,
+    TokenUsage,
+    UsageLedger,
+    UsageSnapshot,
+    UsageWindow,
+)
+
+
+__all__ = [
+    "AuthenticationError",
+    "AudioUsage",
+    "CacheUsage",
+    "ContextWindowError",
+    "CostUsage",
+    "DeviceLoginFlow",
+    "HostedAuthorization",
+    "LoginFlow",
+    "ModelProvider",
+    "ModelRecord",
+    "ModelUsage",
+    "Models",
+    "OAuthAdapter",
+    "OAuthAuthorization",
+    "OAuthAuthorizationRequest",
+    "OAuthConfiguration",
+    "OAuthLoginFlow",
+    "OAuthProvider",
+    "OAuthTokens",
+    "ProviderRecord",
+    "TokenUsage",
+    "UsageLedger",
+    "UsageSnapshot",
+    "UsageWindow",
+]