Skip to content

Installing the Diogenes SDK

For internal teams and partners, the Diogenes SDK is published as a versioned Python wheel attached to a GitHub Release on the ubiquitousthey/diogenes repository. Each tagged release of the form v*.*.* carries one diogenes_sdk-<version>-py3-none-any.whl asset that you can install directly with pip.

Why GitHub Releases (not GitHub Packages)? GitHub Packages does not host Python distributions — it only supports container, npm, Maven, NuGet, and RubyGems registries. The original pkg.github.com upload endpoint returned 404 Not Found for the Python upload attempt (see issue #377 for the full investigation). GitHub Releases is the supported way to host arbitrary release artifacts in a GitHub repo and works fine for pip install <url>.

What gets published

The published distribution is named diogenes-sdk (note the hyphen — the wheel filename normalizes this to diogenes_sdk per PEP 427). It is SDK-only: partners get the SDK client surface but NOT the server, CLI, or admin code. The full diogenes monorepo package is only used internally by the Diogenes service itself.

The Python import path is unchanged — you still write:

from diogenes.sdk import DiogenesSDK, LocalKeystoreSigner

The wheel ships:

  • diogenes.sdk.* — the public SDK API.
  • diogenes.common.* — internal modules that diogenes.sdk depends on (canonical JSON, key types, signing payload construction, trust configuration, schemas).

It does not include:

  • diogenes.server.* — the FastAPI app. If you try from diogenes.server import ... you will get ModuleNotFoundError.
  • diogenes.cli.* — the operator CLI.
  • diogenes.admin.* — the admin/portal templates.

If you need any of those, work from a monorepo checkout (pip install -e .) rather than installing the published SDK.

A standalone diogenes-verify distribution (the verify-only SDK at ./diogenes-verify/ in the repo) is not yet published. Track its publication in the follow-up issue linked from issue #377 — until then, partners who only need verification should install diogenes-sdk and use diogenes.sdk.VerificationError / the verify helpers.

Authentication is required (private repo)

The ubiquitousthey/diogenes repository is private. Release assets attached to releases on a private repo can only be fetched with a valid GitHub credential — the unauthenticated https://github.com/.../releases/download/<tag>/<wheel> URL returns HTTP 404 for the public.

You will need a GitHub personal access token (PAT) with repo scope (classic PAT) or a fine-grained PAT scoped to this repository with Contents: Read permission.

Installing with gh release download + pip install

The cleanest pattern is to download the wheel via the GitHub CLI (which handles auth) and then pip-install the local file:

gh release download v0.1.0 \
  --repo ubiquitousthey/diogenes \
  --pattern '*.whl' \
  --dir /tmp
pip install /tmp/diogenes_sdk-0.1.0-py3-none-any.whl

gh reads its credential from gh auth login or the GH_TOKEN environment variable. The wheel's transitive runtime dependencies (cryptography, pydantic, httpx, rfc8785, argon2-cffi) resolve from PyPI as usual — no extra index flag needed.

Installing in CI

- env:
    GH_TOKEN: ${{ secrets.DIOGENES_SDK_PAT }}  # PAT with repo:read
  run: |
    gh release download v0.1.0 \
      --repo ubiquitousthey/diogenes \
      --pattern '*.whl' \
      --dir /tmp
    pip install /tmp/diogenes_sdk-0.1.0-py3-none-any.whl

For workflows inside the diogenes repo itself, the built-in secrets.GITHUB_TOKEN is sufficient — the publish workflow's smoke job uses that pattern (see .github/workflows/publish-sdk.yml).

Pinning the latest release

If you want the latest published wheel rather than a specific tag:

latest=$(gh release list --repo ubiquitousthey/diogenes --limit 1 \
  --json tagName --jq '.[0].tagName')
gh release download "$latest" --repo ubiquitousthey/diogenes \
  --pattern '*.whl' --dir /tmp
pip install /tmp/diogenes_sdk-*-py3-none-any.whl

Pinning in pyproject.toml

A PEP 508 direct-reference to a release-asset URL does not work on private repos — pip cannot pass authentication when fetching the URL. The supported pattern is to pin against a local file path after fetching with gh. For projects that want a single declarative spec, depend on diogenes-sdk by name and resolve the URL in a prepare-step (CI) or with a wrapper script (local dev).

If the repository is later made public, the PEP 508 direct reference becomes the recommended pin:

[project]
dependencies = [
  "diogenes-sdk @ https://github.com/ubiquitousthey/diogenes/releases/download/v0.1.0/diogenes_sdk-0.1.0-py3-none-any.whl",
]

You can pin against a hash for reproducibility once the URL is publicly fetchable:

"diogenes-sdk @ https://.../diogenes_sdk-0.1.0-py3-none-any.whl#sha256=<HASH>",

Using the SDK after install

Once installed, the SDK is importable from any Python program:

from diogenes.sdk import DiogenesSDK, LocalKeystoreSigner

sdk = DiogenesSDK(server_url="https://trustdiogenes.com")
signer = LocalKeystoreSigner(fingerprint=fp, password="hunter2")
receipt = sdk.sign(b"Hello, Diogenes!", signer)

See docs/developers/sdk-reference.md for the full SDK reference, examples, and quickstart.

Release cadence

A new release is published whenever a maintainer pushes a Git tag of the form v*.*.* (or manually triggers the publish workflow with an explicit tag_override). The version embedded in the wheel's metadata is derived from the Git tag via setuptools-scm, so pip show diogenes-sdk will always report a version that matches a real tag in the repository.

Troubleshooting

404 Not Found from pip when using a raw release-asset URL

The ubiquitousthey/diogenes repo is private — pip install https://github.com/.../releases/download/... cannot authenticate and returns 404. Use gh release download (see above) instead.

gh: error: HTTP 404 from gh release download

Either the tag does not exist, or your gh is not authenticated to an account with read access to the repo. Run gh auth status to check. Re-authenticate with a PAT that has repo scope.

Could not find a version that satisfies the requirement

This means pip could not resolve one of the SDK's transitive dependencies from PyPI. Make sure your environment has access to pypi.org.

pip install succeeds but import diogenes.sdk fails

The wheel ships only diogenes.sdk.* and diogenes.common.*. If you expected diogenes.server, diogenes.cli, or diogenes.admin, you are looking for the full monorepo package — clone the repo and pip install -e . instead.