logits-sdk 0.1.0__tar.gz

logits_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install pytest pytest-timeout respx
+
+      - name: Run tests
+        run: pytest
+
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build and check distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*

logits_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,87 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "Repository to publish to"
+        required: true
+        default: "testpypi"
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.repository == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.repository == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

logits_sdk-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.prism.log
+_dev
+
+__pycache__
+.mypy_cache
+
+dist
+
+.venv
+.idea
+
+.env
+.envrc
+codegen.log
+Brewfile.lock.json

logits_sdk-0.1.0/LICENSE

@@ -0,0 +1,177 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation
+or translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or
+merely link (or bind by name) to the interfaces of, the Work and Derivative
+Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the
+purposes of this definition, "submitted" means any form of electronic,
+verbal, or written communication sent to the Licensor or its representatives,
+including but not limited to communication on electronic mailing lists, source
+code control systems, and issue tracking systems that are managed by, or on
+behalf of, the Licensor for the purpose of discussing and improving the Work,
+but excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on
+behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed
+by their Contribution(s) alone or by combination of their Contribution(s) with
+the Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the
+Work constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as
+of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from
+the Source form of the Work, excluding those notices that do not pertain to
+any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file, excluding those
+notices that do not pertain to any part of the Derivative Works, in at least
+one of the following places: within a NOTICE text file distributed as part of
+the Derivative Works; within the Source form or documentation, if provided
+along with the Derivative Works; or, within a display generated by the
+Derivative Works, if and wherever such third-party notices normally appear.
+The contents of the NOTICE file are for informational purposes only and do
+not modify the License. You may add Your own attribution notices within
+Derivative Works that You distribute, alongside or as an addendum to the
+NOTICE text from the Work, provided that such additional attribution notices
+cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated in
+this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein
+shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of the Work
+and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to
+in writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability
+to use the Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all other
+commercial damages or losses), even if such Contributor has been advised of
+the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Gradient
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

logits_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: logits-sdk
+Version: 0.1.0
+Summary: The Logits Python SDK facade over the official Tinker SDK (import as `logits`)
+Project-URL: Homepage, https://github.com/GradientHQ/logits
+Project-URL: Repository, https://github.com/GradientHQ/logits
+Project-URL: Issues, https://github.com/GradientHQ/logits/issues
+Project-URL: Documentation, https://github.com/GradientHQ/logits#readme
+Author-email: Gradient <support@gradient.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: logits,logits-sdk,sampling,tinker,training
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: tinker<0.22,>=0.21
+Description-Content-Type: text/markdown
+
+# Logits Python SDK
+
+`logits-sdk` is the official Python SDK for the Logits platform. Install it
+under the distribution name `logits-sdk`; application code imports it as
+`logits`.
+
+## Installation
+
+```bash
+pip install logits-sdk
+```
+
+## Authentication
+
+Set a Logits API key before creating clients:
+
+```bash
+export LOGITS_API_KEY="your-api-key"
+```
+
+For non-default deployments, set a base URL:
+
+```bash
+export LOGITS_BASE_URL="https://api.example.com"
+```
+
+## Usage
+
+```python
+import logits
+
+service_client = logits.ServiceClient()
+sampling_client = service_client.create_sampling_client(base_model="Qwen/Qwen3-8B")
+future = sampling_client.sample(
+    prompt=logits.ModelInput.from_ints([1, 2, 3]),
+    num_samples=1,
+    sampling_params=logits.SamplingParams(max_tokens=32),
+)
+result = future.result()
+```
+
+Async usage:
+
+```python
+import logits
+
+service_client = logits.ServiceClient()
+sampling_client = await service_client.create_sampling_client_async(
+    base_model="Qwen/Qwen3-8B"
+)
+result = await sampling_client.sample_async(
+    prompt=logits.ModelInput.from_ints([1, 2, 3]),
+    num_samples=1,
+    sampling_params=logits.SamplingParams(max_tokens=32),
+)
+```
+
+Close the underlying holder when a long-running process no longer needs the client:
+
+```python
+service_client.holder.close()
+```
+
+## Development
+
+Install the package and test dependencies:
+
+```bash
+python -m pip install -e .
+python -m pip install pytest pytest-timeout respx
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+Build and validate release artifacts:
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+## Release Checklist
+
+- Bump both `pyproject.toml` and `src/logits/_version.py`.
+- Run `pytest`, `python -m build`, and `python -m twine check dist/*`.
+- Confirm GitHub Actions CI is green on the release commit.
+- Create a GitHub release from the version tag to trigger the publish workflow.

logits_sdk-0.1.0/README.md

@@ -0,0 +1,92 @@
+# Logits Python SDK
+
+`logits-sdk` is the official Python SDK for the Logits platform. Install it
+under the distribution name `logits-sdk`; application code imports it as
+`logits`.
+
+## Installation
+
+```bash
+pip install logits-sdk
+```
+
+## Authentication
+
+Set a Logits API key before creating clients:
+
+```bash
+export LOGITS_API_KEY="your-api-key"
+```
+
+For non-default deployments, set a base URL:
+
+```bash
+export LOGITS_BASE_URL="https://api.example.com"
+```
+
+## Usage
+
+```python
+import logits
+
+service_client = logits.ServiceClient()
+sampling_client = service_client.create_sampling_client(base_model="Qwen/Qwen3-8B")
+future = sampling_client.sample(
+    prompt=logits.ModelInput.from_ints([1, 2, 3]),
+    num_samples=1,
+    sampling_params=logits.SamplingParams(max_tokens=32),
+)
+result = future.result()
+```
+
+Async usage:
+
+```python
+import logits
+
+service_client = logits.ServiceClient()
+sampling_client = await service_client.create_sampling_client_async(
+    base_model="Qwen/Qwen3-8B"
+)
+result = await sampling_client.sample_async(
+    prompt=logits.ModelInput.from_ints([1, 2, 3]),
+    num_samples=1,
+    sampling_params=logits.SamplingParams(max_tokens=32),
+)
+```
+
+Close the underlying holder when a long-running process no longer needs the client:
+
+```python
+service_client.holder.close()
+```
+
+## Development
+
+Install the package and test dependencies:
+
+```bash
+python -m pip install -e .
+python -m pip install pytest pytest-timeout respx
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+Build and validate release artifacts:
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+## Release Checklist
+
+- Bump both `pyproject.toml` and `src/logits/_version.py`.
+- Run `pytest`, `python -m build`, and `python -m twine check dist/*`.
+- Confirm GitHub Actions CI is green on the release commit.
+- Create a GitHub release from the version tag to trigger the publish workflow.

logits_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "logits-sdk"
+version = "0.1.0"
+description = "The Logits Python SDK facade over the official Tinker SDK (import as `logits`)"
+readme = "README.md"
+authors = [{ name = "Gradient", email = "support@gradient.ai" }]
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = [
+    "tinker>=0.21,<0.22",
+]
+keywords = ["logits", "logits-sdk", "tinker", "training", "sampling"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/GradientHQ/logits"
+Repository = "https://github.com/GradientHQ/logits"
+Issues = "https://github.com/GradientHQ/logits/issues"
+Documentation = "https://github.com/GradientHQ/logits#readme"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-timeout",
+    "respx",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/logits"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+timeout = 15
+timeout_method = "thread"

logits_sdk-0.1.0/src/logits/__init__.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import typing as _t
+
+import tinker as _tinker
+from tinker import *  # noqa: F403
+
+from . import types
+from ._config import (
+    LOGITS_API_KEY_ENV,
+    LOGITS_BASE_URL_ENV,
+    TINKER_API_KEY_ENV,
+    TINKER_BASE_URL_ENV,
+    resolve_api_key,
+    resolve_base_url,
+)
+from ._service_client import ServiceClient, create_service_client
+from ._training_client import TrainingClient
+from ._version import __title__, __version__
+
+LogitsError = TinkerError
+
+__backend_sdk__ = "tinker"
+__backend_sdk_version__ = _tinker.__version__
+
+__all__ = [
+    *[name for name in _tinker.__all__ if name not in ("ServiceClient", "TrainingClient")],
+    "ServiceClient",
+    "TrainingClient",
+    "create_service_client",
+    "LOGITS_API_KEY_ENV",
+    "LOGITS_BASE_URL_ENV",
+    "TINKER_API_KEY_ENV",
+    "TINKER_BASE_URL_ENV",
+    "resolve_api_key",
+    "resolve_base_url",
+    "LogitsError",
+    "__title__",
+    "__version__",
+    "__backend_sdk__",
+    "__backend_sdk_version__",
+]
+
+if not _t.TYPE_CHECKING:
+    from tinker import resources as resources
+
+__locals = locals()
+for __name in __all__:
+    if not __name.startswith("__"):
+        try:
+            __locals[__name].__module__ = "logits"
+        except (TypeError, AttributeError):
+            pass

logits_sdk-0.1.0/src/logits/_config.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+import os
+from typing import Any
+
+import tinker.lib._auth_token_provider as _auth_provider
+import tinker.lib.internal_client_holder as _internal_client_holder
+import tinker._client as _tinker_client
+from tinker import types as _tinker_types
+
+LOGITS_API_KEY_ENV = "LOGITS_API_KEY"
+LOGITS_BASE_URL_ENV = "LOGITS_BASE_URL"
+TINKER_API_KEY_ENV = "TINKER_API_KEY"
+TINKER_BASE_URL_ENV = "TINKER_BASE_URL"
+API_KEY_HEADER = "X-API-Key"
+
+_logger = logging.getLogger("logits")
+
+DEFAULT_CLIENT_CONFIG: dict[str, Any] = {
+    "pjwt_auth_enabled": False,
+    "credential_default_source": "api_key",
+    "sample_dispatch_bytes_semaphore_size": 1 << 30,
+    "inflight_response_bytes_semaphore_size": 1 << 30,
+    "parallel_fwdbwd_chunks": 1,
+    "proto_write_fwdbwd": False,
+    "billing_exception_max_pause_duration_sec": 0,
+    "grpc_target": "",
+    "enable_grpc_retrieve_future": False,
+    "sample_no_retries": False,
+}
+
+
+class LogitsApiKeyAuthProvider(_auth_provider.AuthTokenProvider):
+    """Tinker-compatible auth provider that accepts Logits API keys."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        resolved = api_key or _get_first_env(LOGITS_API_KEY_ENV, TINKER_API_KEY_ENV)
+        if not resolved:
+            raise _auth_provider.TinkerError(
+                "The api_key client option must be set either by passing api_key to the client"
+                f" or by setting the {LOGITS_API_KEY_ENV} environment variable"
+            )
+        self._token = resolved
+
+    async def get_token(self) -> str | None:
+        return self._token
+
+
+def install_logits_auth_compat() -> None:
+    _auth_provider.ApiKeyAuthProvider = LogitsApiKeyAuthProvider
+    _internal_client_holder.ApiKeyAuthProvider = LogitsApiKeyAuthProvider
+    _tinker_client.ApiKeyAuthProvider = LogitsApiKeyAuthProvider
+
+
+_FETCH_CLIENT_CONFIG_PATCHED = False
+
+
+def install_client_config_fallback() -> None:
+    """Make `_fetch_client_config` fall back to defaults on transport failure.
+
+    Some Logits deployments do not implement `/api/v1/client/config` yet. When
+    the upstream tinker holder boots, it blocks on that endpoint before any
+    other call. Wrap the holder method so a 404 / connect error returns the
+    built-in defaults instead of aborting bootstrap. Once the backend ships
+    the endpoint, real responses take over automatically.
+    """
+    global _FETCH_CLIENT_CONFIG_PATCHED
+    if _FETCH_CLIENT_CONFIG_PATCHED:
+        return
+
+    original = _internal_client_holder.InternalClientHolder._fetch_client_config
+
+    async def _fetch_client_config_with_fallback(
+        self: _internal_client_holder.InternalClientHolder,
+        auth: _auth_provider.AuthTokenProvider,
+    ) -> _tinker_types.ClientConfigResponse:
+        try:
+            return await original(self, auth)
+        except Exception as exc:  # noqa: BLE001 — narrow below
+            if not _is_missing_endpoint_error(exc):
+                raise
+            _logger.info(
+                "logits: /api/v1/client/config unavailable (%s); using built-in defaults",
+                _summarize_exc(exc),
+            )
+            return _tinker_types.ClientConfigResponse.model_validate(DEFAULT_CLIENT_CONFIG)
+
+    _internal_client_holder.InternalClientHolder._fetch_client_config = (  # type: ignore[method-assign]
+        _fetch_client_config_with_fallback
+    )
+    _FETCH_CLIENT_CONFIG_PATCHED = True
+
+
+def _is_missing_endpoint_error(exc: BaseException) -> bool:
+    # httpx.HTTPStatusError exposes `.response`; tinker wraps 4xx into TinkerError.
+    response = getattr(exc, "response", None)
+    if response is not None and getattr(response, "status_code", None) == 404:
+        return True
+    # Tinker raises NotFoundError (subclass of TinkerError) for 404 responses.
+    if type(exc).__name__ == "NotFoundError":
+        return True
+    # Connection-level failures (DNS, refused, TLS) — treat as endpoint missing.
+    if isinstance(exc, (ConnectionError, OSError)):
+        return True
+    return False
+
+
+def _summarize_exc(exc: BaseException) -> str:
+    return f"{type(exc).__name__}: {exc}"[:200]
+
+
+def _get_first_env(*names: str) -> str | None:
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+def resolve_api_key(
+    api_key: str | None = None,
+    *,
+    default_headers: Mapping[str, str] | None = None,
+) -> str | None:
+    if api_key is not None:
+        return api_key
+    if default_headers is not None and default_headers.get(API_KEY_HEADER):
+        return default_headers[API_KEY_HEADER]
+    return _get_first_env(LOGITS_API_KEY_ENV, TINKER_API_KEY_ENV)
+
+
+def resolve_base_url(base_url: str | None = None) -> str | None:
+    if base_url is not None:
+        return base_url
+    return _get_first_env(LOGITS_BASE_URL_ENV, TINKER_BASE_URL_ENV)
+
+
+def resolve_service_client_kwargs(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    default_headers: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    install_logits_auth_compat()
+    install_client_config_fallback()
+    headers = dict(default_headers or {})
+    resolved_api_key = resolve_api_key(api_key, default_headers=headers)
+    resolved_base_url = resolve_base_url(base_url)
+
+    kwargs: dict[str, Any] = {}
+    if resolved_base_url is not None:
+        kwargs["base_url"] = resolved_base_url
+
+    if resolved_api_key is None:
+        if headers:
+            kwargs["default_headers"] = headers
+        return kwargs
+
+    kwargs["api_key"] = resolved_api_key
+
+    if headers:
+        kwargs["default_headers"] = headers
+    return kwargs

logits_sdk-0.1.0/src/logits/_path_compat.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+LOGITS_URI_PREFIX = "logits://"
+TINKER_URI_PREFIX = "tinker://"
+
+_VALID_MODEL_PATH_PREFIXES = (LOGITS_URI_PREFIX, TINKER_URI_PREFIX)
+
+
+def is_valid_model_path(path: str | None) -> bool:
+    """Whether the URI looks like a supported weights path.
+
+    Tinker SDK historically required ``tinker://``. Newer backends may return
+    ``logits://`` instead, so we accept both prefixes at the SDK boundary.
+    """
+
+    if path is None:
+        return False
+    return path.startswith(_VALID_MODEL_PATH_PREFIXES)
+
+
+def normalize_tinker_path(path: str) -> str:
+    """Convert logits://<...> to tinker://<...> for local parsing only."""
+
+    if path.startswith(LOGITS_URI_PREFIX):
+        return TINKER_URI_PREFIX + path[len(LOGITS_URI_PREFIX) :]
+    return path
+

logits_sdk-0.1.0/src/logits/_rest_client.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from concurrent.futures import Future as ConcurrentFuture
+from typing import Literal
+
+from tinker import types
+from tinker.lib.public_interfaces.rest_client import RestClient as TinkerRestClient
+
+from ._path_compat import normalize_tinker_path
+
+
+class RestClient(TinkerRestClient):
+    """Logits-compatible RestClient.
+
+    Upstream Tinker RestClient's `*_by_tinker_path` helpers parse the URI using
+    `ParsedCheckpointTinkerPath.from_tinker_path`, which historically only
+    accepted `tinker://`. Backends may now return `logits://` instead, so we
+    normalize only for local parsing while still treating the rest of the API
+    parameters as opaque.
+    """
+
+    def get_training_run_by_tinker_path(
+        self, tinker_path: str, access_scope: Literal["owned", "accessible"] = "owned"
+    ) -> ConcurrentFuture[types.TrainingRun]:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        return self.get_training_run(parsed.training_run_id, access_scope=access_scope)
+
+    async def get_training_run_by_tinker_path_async(
+        self, tinker_path: str, access_scope: Literal["owned", "accessible"] = "owned"
+    ) -> types.TrainingRun:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        return await self.get_training_run_async(parsed.training_run_id, access_scope=access_scope)
+
+    def delete_checkpoint_from_tinker_path(self, tinker_path: str) -> ConcurrentFuture[None]:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        return self._delete_checkpoint_submit(parsed.training_run_id, parsed.checkpoint_id).future()
+
+    async def delete_checkpoint_from_tinker_path_async(self, tinker_path: str) -> None:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        await self._delete_checkpoint_submit(parsed.training_run_id, parsed.checkpoint_id)
+
+    def get_checkpoint_archive_url_from_tinker_path(
+        self, tinker_path: str
+    ) -> ConcurrentFuture[types.CheckpointArchiveUrlResponse]:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        return self._get_checkpoint_archive_url_submit(parsed.training_run_id, parsed.checkpoint_id).future()
+
+    async def get_checkpoint_archive_url_from_tinker_path_async(
+        self, tinker_path: str
+    ) -> types.CheckpointArchiveUrlResponse:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        return await self._get_checkpoint_archive_url_submit(parsed.training_run_id, parsed.checkpoint_id)
+
+    def publish_checkpoint_from_tinker_path(self, tinker_path: str) -> ConcurrentFuture[None]:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        return self._publish_checkpoint_submit(parsed.training_run_id, parsed.checkpoint_id).future()
+
+    async def publish_checkpoint_from_tinker_path_async(self, tinker_path: str) -> None:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        await self._publish_checkpoint_submit(parsed.training_run_id, parsed.checkpoint_id)
+
+    def unpublish_checkpoint_from_tinker_path(self, tinker_path: str) -> ConcurrentFuture[None]:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        return self._unpublish_checkpoint_submit(parsed.training_run_id, parsed.checkpoint_id).future()
+
+    async def unpublish_checkpoint_from_tinker_path_async(self, tinker_path: str) -> None:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        await self._unpublish_checkpoint_submit(parsed.training_run_id, parsed.checkpoint_id)
+
+    def set_checkpoint_ttl_from_tinker_path(
+        self, tinker_path: str, ttl_seconds: int | None
+    ) -> ConcurrentFuture[None]:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        return self._set_checkpoint_ttl_submit(
+            parsed.training_run_id, parsed.checkpoint_id, ttl_seconds
+        ).future()
+
+    async def set_checkpoint_ttl_from_tinker_path_async(
+        self, tinker_path: str, ttl_seconds: int | None
+    ) -> None:
+        parsed = types.ParsedCheckpointTinkerPath.from_tinker_path(normalize_tinker_path(tinker_path))
+        await self._set_checkpoint_ttl_submit(parsed.training_run_id, parsed.checkpoint_id, ttl_seconds)
+

logits_sdk-0.1.0/src/logits/_service_client.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from typing import Any
+
+import tinker
+from tinker import SamplingClient, types
+from tinker.lib.client_connection_pool_type import ClientConnectionPoolType
+from tinker.lib.retry_handler import RetryConfig
+
+from ._config import resolve_service_client_kwargs
+from ._path_compat import is_valid_model_path
+from ._training_client import TrainingClient as LogitsTrainingClient
+from ._rest_client import RestClient as LogitsRestClient
+
+
+class ServiceClient(tinker.ServiceClient):
+    """Logits-first facade over ``tinker.ServiceClient``."""
+
+    def __init__(
+        self,
+        user_metadata: dict[str, str] | None = None,
+        project_id: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        base_url = kwargs.pop("base_url", None)
+        api_key = kwargs.pop("api_key", None)
+        default_headers = kwargs.pop("default_headers", None)
+        translated_kwargs = resolve_service_client_kwargs(
+            api_key=api_key,
+            base_url=base_url,
+            default_headers=default_headers,
+        )
+        super().__init__(
+            user_metadata=user_metadata,
+            project_id=project_id,
+            **translated_kwargs,
+            **kwargs,
+        )
+
+    @staticmethod
+    def _wrap_training_client(training_client: tinker.TrainingClient) -> LogitsTrainingClient:
+        # tinker.TrainingClient stores the model seq id in a private field.
+        # We only need it to construct an equivalent wrapper instance.
+        return LogitsTrainingClient(
+            training_client.holder,
+            getattr(training_client, "_training_client_id"),
+            training_client.model_id,
+        )
+
+    def create_sampling_client(
+        self,
+        model_path: str | None = None,
+        base_model: str | None = None,
+        retry_config: RetryConfig | None = None,
+    ) -> SamplingClient:
+        if model_path is None and base_model is None:
+            raise ValueError("Either model_path or base_model must be provided")
+        if model_path is not None and not is_valid_model_path(model_path):
+            raise ValueError("model_path must start with 'tinker://' or 'logits://'")
+
+        async def _create_sampling_client_async() -> SamplingClient:
+            assert self.holder._sampling_client_counter is not None
+            sampling_session_seq_id = self.holder._sampling_client_counter
+            self.holder._sampling_client_counter += 1
+
+            with self.holder.aclient(ClientConnectionPoolType.SESSION) as client:
+                request = types.CreateSamplingSessionRequest(
+                    session_id=self.holder._session_id,
+                    sampling_session_seq_id=sampling_session_seq_id,
+                    model_path=model_path,
+                    base_model=base_model,
+                )
+                result = await client.service.create_sampling_session(request=request)
+
+            return SamplingClient(
+                self.holder,
+                sampling_session_id=result.sampling_session_id,
+                retry_config=retry_config,
+            )
+
+        return self.holder.run_coroutine_threadsafe(_create_sampling_client_async()).result()
+
+    async def create_sampling_client_async(
+        self,
+        model_path: str | None = None,
+        base_model: str | None = None,
+        retry_config: RetryConfig | None = None,
+    ) -> SamplingClient:
+        if model_path is None and base_model is None:
+            raise ValueError("Either model_path or base_model must be provided")
+        if model_path is not None and not is_valid_model_path(model_path):
+            raise ValueError("model_path must start with 'tinker://' or 'logits://'")
+
+        async def _create_sampling_client_async_inner() -> SamplingClient:
+            assert self.holder._sampling_client_counter is not None
+            sampling_session_seq_id = self.holder._sampling_client_counter
+            self.holder._sampling_client_counter += 1
+
+            with self.holder.aclient(ClientConnectionPoolType.SESSION) as client:
+                request = types.CreateSamplingSessionRequest(
+                    session_id=self.holder._session_id,
+                    sampling_session_seq_id=sampling_session_seq_id,
+                    model_path=model_path,
+                    base_model=base_model,
+                )
+                result = await client.service.create_sampling_session(request=request)
+
+            return SamplingClient(
+                self.holder,
+                sampling_session_id=result.sampling_session_id,
+                retry_config=retry_config,
+            )
+
+        return await self.holder.run_coroutine_threadsafe(_create_sampling_client_async_inner())
+
+    def create_lora_training_client(
+        self,
+        base_model: str,
+        rank: int = 32,
+        seed: int | None = None,
+        train_mlp: bool = True,
+        train_attn: bool = True,
+        train_unembed: bool = True,
+        user_metadata: dict[str, str] | None = None,
+    ) -> LogitsTrainingClient:
+        training_client = super().create_lora_training_client(
+            base_model=base_model,
+            rank=rank,
+            seed=seed,
+            train_mlp=train_mlp,
+            train_attn=train_attn,
+            train_unembed=train_unembed,
+            user_metadata=user_metadata,
+        )
+        return self._wrap_training_client(training_client)
+
+    async def create_lora_training_client_async(
+        self,
+        base_model: str,
+        rank: int = 32,
+        seed: int | None = None,
+        train_mlp: bool = True,
+        train_attn: bool = True,
+        train_unembed: bool = True,
+        user_metadata: dict[str, str] | None = None,
+    ) -> LogitsTrainingClient:
+        training_client = await super().create_lora_training_client_async(
+            base_model=base_model,
+            rank=rank,
+            seed=seed,
+            train_mlp=train_mlp,
+            train_attn=train_attn,
+            train_unembed=train_unembed,
+            user_metadata=user_metadata,
+        )
+        return self._wrap_training_client(training_client)
+
+    def create_training_client_from_state(
+        self,
+        path: str,
+        user_metadata: dict[str, str] | None = None,
+        weights_access_token: str | None = None,
+    ) -> LogitsTrainingClient:
+        training_client = super().create_training_client_from_state(
+            path,
+            user_metadata=user_metadata,
+            weights_access_token=weights_access_token,
+        )
+        return self._wrap_training_client(training_client)
+
+    async def create_training_client_from_state_async(
+        self,
+        path: str,
+        user_metadata: dict[str, str] | None = None,
+        weights_access_token: str | None = None,
+    ) -> LogitsTrainingClient:
+        training_client = await super().create_training_client_from_state_async(
+            path,
+            user_metadata=user_metadata,
+            weights_access_token=weights_access_token,
+        )
+        return self._wrap_training_client(training_client)
+
+    def create_training_client_from_state_with_optimizer(
+        self,
+        path: str,
+        user_metadata: dict[str, str] | None = None,
+        weights_access_token: str | None = None,
+    ) -> LogitsTrainingClient:
+        training_client = super().create_training_client_from_state_with_optimizer(
+            path,
+            user_metadata=user_metadata,
+            weights_access_token=weights_access_token,
+        )
+        return self._wrap_training_client(training_client)
+
+    async def create_training_client_from_state_with_optimizer_async(
+        self,
+        path: str,
+        user_metadata: dict[str, str] | None = None,
+        weights_access_token: str | None = None,
+    ) -> LogitsTrainingClient:
+        training_client = await super().create_training_client_from_state_with_optimizer_async(
+            path,
+            user_metadata=user_metadata,
+            weights_access_token=weights_access_token,
+        )
+        return self._wrap_training_client(training_client)
+
+    def create_rest_client(self) -> LogitsRestClient:
+        return LogitsRestClient(self.holder)
+
+
+def create_service_client(**kwargs: Any) -> ServiceClient:
+    return ServiceClient(**kwargs)

logits_sdk-0.1.0/src/logits/_training_client.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import tinker
+from tinker import SamplingClient, types
+from tinker.lib.client_connection_pool_type import ClientConnectionPoolType
+from tinker.lib.retry_handler import RetryConfig
+
+from ._path_compat import is_valid_model_path
+
+
+class TrainingClient(tinker.TrainingClient):
+    """Logits-compatible TrainingClient.
+
+    The upstream Tinker SDK validates that `model_path` starts with `tinker://`
+    when creating a SamplingClient. Some backends now return `logits://`
+    checkpoints, so we accept both prefixes and pass the URI through unchanged.
+    """
+
+    def create_sampling_client(
+        self, model_path: str, retry_config: RetryConfig | None = None
+    ) -> SamplingClient:
+        if not is_valid_model_path(model_path):
+            raise ValueError("model_path must start with 'tinker://' or 'logits://'")
+
+        async def _create_sampling_client_async() -> SamplingClient:
+            # Create sampling session without the tinker:// prefix check.
+            assert self.holder._sampling_client_counter is not None
+            sampling_session_seq_id = self.holder._sampling_client_counter
+            self.holder._sampling_client_counter += 1
+
+            with self.holder.aclient(ClientConnectionPoolType.SESSION) as client:
+                request = types.CreateSamplingSessionRequest(
+                    session_id=self.holder._session_id,
+                    sampling_session_seq_id=sampling_session_seq_id,
+                    model_path=model_path,
+                    base_model=None,
+                )
+                result = await client.service.create_sampling_session(request=request)
+
+            return SamplingClient(
+                self.holder,
+                sampling_session_id=result.sampling_session_id,
+                retry_config=retry_config,
+            )
+
+        return self.holder.run_coroutine_threadsafe(_create_sampling_client_async()).result()
+
+    async def create_sampling_client_async(
+        self, model_path: str, retry_config: RetryConfig | None = None
+    ) -> SamplingClient:
+        if not is_valid_model_path(model_path):
+            raise ValueError("model_path must start with 'tinker://' or 'logits://'")
+
+        async def _create_sampling_client_async_inner() -> SamplingClient:
+            assert self.holder._sampling_client_counter is not None
+            sampling_session_seq_id = self.holder._sampling_client_counter
+            self.holder._sampling_client_counter += 1
+
+            with self.holder.aclient(ClientConnectionPoolType.SESSION) as client:
+                request = types.CreateSamplingSessionRequest(
+                    session_id=self.holder._session_id,
+                    sampling_session_seq_id=sampling_session_seq_id,
+                    model_path=model_path,
+                    base_model=None,
+                )
+                result = await client.service.create_sampling_session(request=request)
+
+            return SamplingClient(
+                self.holder,
+                sampling_session_id=result.sampling_session_id,
+                retry_config=retry_config,
+            )
+
+        return await self.holder.run_coroutine_threadsafe(_create_sampling_client_async_inner())
+

logits_sdk-0.1.0/src/logits/_version.py

@@ -0,0 +1,2 @@
+__title__ = "logits-sdk"
+__version__ = "0.1.0"

logits_sdk-0.1.0/src/logits/py.typed

@@ -0,0 +1 @@
+

logits_sdk-0.1.0/src/logits/types/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import importlib
+import pkgutil
+import sys
+
+import tinker.types as _tinker_types
+from tinker.types import *  # noqa: F403
+
+for module_info in pkgutil.walk_packages(_tinker_types.__path__, prefix="tinker.types."):
+    tinker_module_name = module_info.name
+    logits_module_name = tinker_module_name.replace("tinker.", "logits.", 1)
+    sys.modules[logits_module_name] = importlib.import_module(tinker_module_name)
+
+__all__ = [
+    name
+    for name in globals()
+    if not name.startswith("_")
+    and name not in {"importlib", "pkgutil", "sys", "module_info", "tinker_module_name", "logits_module_name"}
+]
+
+__locals = locals()
+for __name in __all__:
+    try:
+        __locals[__name].__module__ = "logits.types"
+    except (TypeError, AttributeError):
+        pass

logits_sdk-0.1.0/tests/test_service_client.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+import os
+
+import httpx
+import pytest
+from respx import MockRouter
+
+import logits
+
+BASE_URL = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
+
+
+def mock_service_client_bootstrap(respx_mock: MockRouter) -> httpx.Response:
+    respx_mock.post("/api/v1/client/config").mock(
+        return_value=httpx.Response(200, json={})
+    )
+    create_session_route = respx_mock.post("/api/v1/create_session").mock(
+        return_value=httpx.Response(200, json={"session_id": "test-session-id"})
+    )
+    return create_session_route
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_service_client_uses_non_tml_logits_key_as_header(respx_mock: MockRouter) -> None:
+    create_session_route = mock_service_client_bootstrap(respx_mock)
+
+    service_client = logits.ServiceClient(base_url=BASE_URL, api_key="logits-test-key")
+    service_client.holder.close()
+
+    assert create_session_route.called
+    assert create_session_route.calls[0].request.headers["X-API-Key"] == "logits-test-key"
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_service_client_prefers_logits_env_vars(
+    respx_mock: MockRouter, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    create_session_route = mock_service_client_bootstrap(respx_mock)
+    monkeypatch.setenv("LOGITS_API_KEY", "logits-env-key")
+    monkeypatch.setenv("LOGITS_BASE_URL", BASE_URL)
+    monkeypatch.setenv("TINKER_API_KEY", "tml-tinker-fallback")
+    monkeypatch.setenv("TINKER_BASE_URL", "https://example.invalid")
+
+    service_client = logits.ServiceClient()
+    service_client.holder.close()
+
+    assert create_session_route.called
+    request = create_session_route.calls[0].request
+    assert str(request.url).startswith(f"{BASE_URL}/api/v1/create_session")
+    assert request.headers["X-API-Key"] == "logits-env-key"
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_create_service_client_returns_logits_service_client(respx_mock: MockRouter) -> None:
+    mock_service_client_bootstrap(respx_mock)
+
+    service_client = logits.create_service_client(base_url=BASE_URL, api_key="tml-direct-key")
+    service_client.holder.close()
+
+    assert isinstance(service_client, logits.ServiceClient)
+
+
+@pytest.mark.respx(base_url=BASE_URL)
+def test_service_client_falls_back_when_client_config_missing(respx_mock: MockRouter) -> None:
+    """Backends without /api/v1/client/config must still bootstrap."""
+    config_route = respx_mock.post("/api/v1/client/config").mock(
+        return_value=httpx.Response(404, text="404 page not found")
+    )
+    create_session_route = respx_mock.post("/api/v1/create_session").mock(
+        return_value=httpx.Response(200, json={"session_id": "fallback-session"})
+    )
+
+    service_client = logits.ServiceClient(base_url=BASE_URL, api_key="logits-test-key")
+    try:
+        assert config_route.called
+        assert create_session_route.called
+        assert service_client.holder._session_id == "fallback-session"
+    finally:
+        service_client.holder.close()

logits_sdk-0.1.0/tests/test_types.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from logits.types import LossFnType, TensorData
+from logits.types.tensor_data import TensorData as TensorDataModule
+from tinker.types.tensor_data import TensorData as TinkerTensorData
+
+
+def test_types_package_reexports_tinker_types() -> None:
+    assert TensorData is TinkerTensorData
+    assert TensorDataModule is TinkerTensorData
+    assert LossFnType.__module__ == "logits.types"