Licantha SDK

License-gated, encrypted-model SDK for on-prem AI services.

📦 Available on PyPI: pip install licantha-sdk

The SDK validates a customer's license against a Keygen.sh server (or an offline Ed25519-signed .lic file for air-gapped deployments), activates this machine, runs a background heartbeat, and decrypts AES-256-GCM encrypted model files using keys delivered through license metadata.

✨ Features

• Online activation against a self-hosted Keygen server (SecureClient)
• Offline / air-gapped mode via signed .lic files
• AES-256-GCM model envelope with embedded model_id for multi-model licenses
• Background heartbeat daemon with clean SIGTERM-safe shutdown
• Pluggable KeyProvider abstraction (lease today, GPU-attestation tomorrow)
• Pydantic-validated config (SecureClientConfigPM) and .env loader (SecureClientCliConfig)
• Self-contained example mini-apps for every flow

---

🛠 Installation

1. 🚧 Prerequisites

• Install Python (>= v3.10) and pip (>= 23):
  • [RECOMMENDED] Miniconda (v3)
  • [arm64/aarch64] Miniforge (v3)
  • [Python virtual environment] venv

[OPTIONAL] For DEVELOPMENT environment:

• Install git
• Setup an SSH key

2. 📥 Download or clone the repository

[TIP] Skip this step, if you're going to install the package directly from PyPi or GitHub repository.

2.1. Prepare projects directory (if not exists):

# Create projects directory:
mkdir -pv ~/workspaces/projects

# Enter into projects directory:
cd ~/workspaces/projects

2.2. Follow one of the below options [A], [B] or [C]:

OPTION A. Clone the repository:

git clone https://github.com/humblebeeai/int-sdk-python-licensing.git && \
    cd int-sdk-python-licensing

OPTION B. Clone the repository (for DEVELOPMENT: git + ssh key):

git clone git@github.com:humblebeeai/int-sdk-python-licensing.git && \
    cd int-sdk-python-licensing

OPTION C. Download source code:

1. Download archived zip file from releases.
2. Extract it into the projects directory.

3. 📦 Install the package

[NOTE] Choose one of the following methods to install the package [A ~ E]:

OPTION A. [RECOMMENDED] Install from PyPI:

pip install -U licantha-sdk

OPTION B. Install from the downloaded source code:

# Install directly from the source code:
pip install .

# Or install with editable mode:
pip install -e .

OPTION C. Install for DEVELOPMENT environment:

pip install -e .[dev]

# Install pre-commit hooks:
pre-commit install

OPTION D. Install from pre-built release files:

1. Download .whl or .tar.gz file from PyPI downloads
2. Install with pip:

# Install from .whl file:
pip install ./licantha_sdk-[VERSION]-py3-none-any.whl

# Or install from .tar.gz file:
pip install ./licantha_sdk-[VERSION].tar.gz

OPTION E. Copy the module into the project directory (for testing):

# Install python dependencies:
pip install -r ./requirements.txt

# Copy the module source code into the project:
cp -r ./src/licantha_sdk [PROJECT_DIR]
# For example:
cp -r ./src/licantha_sdk /some/path/project/

🚸 Usage/Examples

Simple

examples/simple/main.py:

# Standard libraries
import sys
import logging
from pathlib import Path

# Third-party libraries
from dotenv import load_dotenv

# Internal modules
from licantha_sdk import LicenseError, SecureClient, SecureClientCliConfig


HERE = Path(__file__).parent
load_dotenv(HERE / ".env")
logger = logging.getLogger("quickstart")


def serve(weights: bytes) -> None:
    logger.info(f"model loaded — {len(weights)} bytes")


def main() -> int:
    logging.basicConfig(level=logging.INFO)

    _config = SecureClientCliConfig()  # picks up LICANTHA_SDK_* from .env / env
    with SecureClient(config=_config) as _client:
        try:
            _weights = _client.decrypt_model(str(HERE / "model.encrypted"))
        except LicenseError as _e:
            logger.critical(f"cannot start: {_e}")
            return 2
        serve(_weights)
    return 0


if __name__ == "__main__":
    sys.exit(main())

See examples/ for offline / custom-inference / multi-model / manual-lifecycle / error-shape variants.

---

⚙️ Configuration

Production callers construct SecureClientConfigPM explicitly — they do NOT pull env vars from inside a compiled binary:

from licantha_sdk import SecureClient, SecureClientConfigPM

config = SecureClientConfigPM(
    account_id="...",
    license_key="...",
    app_id="my-product",
    api_url="https://licensing.your-company.com",
    # public_key="..."  # 64-char hex Ed25519 — only needed for offline .lic mode
)
with SecureClient(config=config) as client:
    weights = client.decrypt_model("model.enc")

Dev / examples can load from .env via SecureClientCliConfig instead.

🌎 Environment Variables

.env.example:

# Required:
LICANTHA_SDK_ACCOUNT_ID=
LICANTHA_SDK_LICENSE_KEY=
LICANTHA_SDK_PUBLIC_KEY=

# Optional:
# LICANTHA_SDK_APP_ID=licantha-default
# LICANTHA_SDK_API_URL=https://licensing.your-company.com
# LICANTHA_SDK_OFFLINE_LICENSE_PATH=./license.lic
# LICANTHA_SDK_HEARTBEAT_INTERVAL=60
# LICANTHA_SDK_DEACTIVATE_ON_EXIT=true

---

🧪 Running Tests

To run tests, run the following command:

# Install python test dependencies:
pip install .[test]

# Run tests:
python -m pytest -sv -o log_cli=true
# Or use the test script:
./scripts/test.sh -l -v -c

🏗️ Build Package

To build the python package, run the following command:

# Install python build dependencies:
pip install -r ./requirements/requirements.build.txt

# Build python package:
python -m build
# Or use the build script:
./scripts/build.sh

📝 Generate Docs

To build the documentation, run the following command:

# Install python documentation dependencies:
pip install -r ./requirements/requirements.docs.txt

# Serve documentation locally (for development):
mkdocs serve -a 0.0.0.0:8000 --livereload
# Or use the docs script:
./scripts/docs.sh

# Or build documentation:
mkdocs build
# Or use the docs script:
./scripts/docs.sh -b

📚 Documentation

• Docs

---

📑 References

• https://packaging.python.org/en/latest/tutorials/packaging-projects
• https://python-packaging.readthedocs.io/en/latest