| Name | lmstudio JSON |
| Version |
1.5.0
JSON |
| download |
| home_page | None |
| Summary | LM Studio Python SDK |
| upload_time | 2025-08-22 13:52:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# LM Studio Python SDK
## Using the SDK
### Installation
The SDK can be installed from PyPI as follows:
```console
$ pip install lmstudio
```
Installation from the repository URL or a local clone is also
supported for development and pre-release testing purposes.
## Examples
The base component of the LM Studio SDK is the (synchronous) `Client`.
This should be created once and used to manage the underlying
websocket connections to the LM Studio instance.
However, a top level convenience API is provided for convenience in
interactive use (this API implicitly creates a default `Client` instance
which will remain active until the Python interpreter is terminated).
Using this convenience API, requesting text completion from an already
loaded LLM is as straightforward as:
```python
import lmstudio as lms
model = lms.llm()
model.complete("Once upon a time,")
```
Requesting a chat response instead only requires the extra step of
setting up a `Chat` helper to manage the chat history and include
it in response prediction requests:
```python
import lmstudio as lms
EXAMPLE_MESSAGES = (
"My hovercraft is full of eels!",
"I will not buy this record, it is scratched."
)
model = lms.llm()
chat = lms.Chat("You are a helpful shopkeeper assisting a foreign traveller")
for message in EXAMPLE_MESSAGES:
chat.add_user_message(message)
print(f"Customer: {message}")
response = model.respond(chat)
chat.add_assistant_response(response)
print(f"Shopkeeper: {response}")
```
Additional SDK examples and usage recommendations may be found in the main
[LM Studio Python SDK documentation](https://lmstudio.ai/docs/python).
## SDK versioning
The LM Studio Python SDK uses a 3-part `X.Y.Z` numeric version identifier:
* `X`: incremented when the minimum version of significant dependencies is updated
(for example, dropping support for older versions of Python or LM Studio).
Previously deprecated features may be dropped when this part of the version number
increases.
* `Y`: incremented when new features are added, or some other notable change is
introduced (such as support for additional versions of Python). New deprecation
warnings may be introduced when this part of the version number increases.
* `Z`: incremented for bug fix releases which don't contain any other changes.
Adding exceptions and warnings for previously undetected situations is considered
a bug fix.
This versioning policy is intentionally similar to [semantic versioning](https://semver.org/),
but differs in the specifics of when the different parts of the version number will be updated.
Release candidates *may* be published prior to full releases, but this will typically only
occur when seeking broader feedback on particular features prior to finalizing the release.
Outside the preparation of a new release, the SDK repository will include a `.devN` suffix
on the nominal Python package version.
## Contributing to SDK development
### Fetching the source code
```console
$ git clone https://github.com/lmstudio-ai/lmstudio-python
$ cd lmstudio-python
```
To be able to run `tox -e sync-sdk-schema`, it is also
necessary to ensure the `lmstudio-js` submodule is updated:
```console
$ git submodule update --init --recursive
```
### Development Environment
In order to work on the Python SDK, you need to install
:pypi:`pdm`, :pypi:`tox`, and :pypi:`tox-pdm`
(everything else can be executed via `tox` environments).
Given these tools, the default development environment can be set up
and other commands executed as described below.
The simplest option for handling that is to install `uv`, and then use
its `uv tool` command to set up `pdm` and a second environment
with `tox` + `tox-pdm`. `pipx` is another reasonable option for this task.
In order to _use_ the Python SDK, you just need some form of
Python environment manager (since `lmstudio-python` publishes
the package `lmstudio` to PyPI).
### Recommended local checks
The set of checks recommended for local execution are accessible via
the `check` marker in `tox`:
```console
$ tox -m check
```
This runs the same checks as the `static` and `test` markers (described below).
### Code consistency checks
The project source code is autoformatted and linted using :pypi:`ruff`.
It also uses :pypi:`mypy` in strict mode to statically check that Python APIs
are being accessed as expected.
All of these commands can be invoked via tox:
```console
$ tox -e format
```
```console
$ tox -e lint
```
```console
$ tox -e typecheck
```
Linting and type checking can be executed together using the `static` marker:
```console
$ tox -m static
```
Avoid using `# noqa` comments to suppress these warnings - wherever
possible, warnings should be fixed instead. `# noqa` comments are
reserved for rare cases where the recommended style causes severe
readability problems, and there isn't a more explicit mechanism
(such as `typing.cast`) to indicate which check is being skipped.
`# fmt: off/on` and `# fmt: skip` comments may be used as needed
when the autoformatter makes readability worse instead of better
(for example, collapsing lists to a single line when they intentionally
cover multiple lines, or breaking alignment of end-of-line comments).
### Automated testing
The project's tests are written using the :pypi:`pytest` test framework.
:pypi:`tox` is used to automate the setup and execution of these tests
across multiple Python versions. One of these is nominated as the
default test target, and is accessible via the `test` marker:
```console
$ tox -m test
```
You can also use other defined versions by specifying the target
environment directly:
```console
$ tox -e py3.11
```
There are additional labels defined for running the oldest test environment,
the latest test environment, and all test environments:
```console
$ tox -m test_oldest
$ tox -m test_latest
$ tox -m test_all
```
To ensure all the required models are loaded before running the tests, run the
following command:
```
$ tox -e load-test-models
```
`tox` has been configured to forward any additional arguments it is given to
`pytest`. This enables the use of pytest's
[rich CLI](https://docs.pytest.org/en/stable/how-to/usage.html#specifying-which-tests-to-run).
In particular, you can select tests using all the options that pytest provides:
```console
$ # Using file name
$ tox -m test -- tests/test_basics.py
$ # Using markers
$ tox -m test -- -m "slow"
$ # Using keyword text search
$ tox -m test -- -k "catalog"
```
Additional notes on running and updating the tests can be found in the
`tests/README.md` file.
### Expanding the API
- the content of `src/lmstudio/_sdk_models` is automatically generated by the
`sync-sdk-schema.py` script in `sdk-schema` and should not be modified directly.
Run `tox -e sync-sdk-schema` to regenerate the Python submodule from the existing
export of the `lmstudio-js` schema (for example, after modifying the data model
template). Run `tox -e sync-sdk-schema -- --regen-schema` after updating the
`sdk-schema/lmstudio-js` submodule itself to a newer iteration of the
`lmstudio-js` JSON API.
- as support for new API namespaces is added to the SDK, each should get a dedicated
session type (similar to those for the already supported namespaces), even if it
is only used privately by the client implementation.
- as support for new API channel endppoints is added to the SDK, each should get a
dedicated base endpoint type (similar to those for the already supported channels).
This avoids duplicating the receive message processing between the sync and async APIs.
- the `json_api.SessionData` base class is useful for defining rich result objects which
offer additional methods that call back into the SDK (for example, this is how downloaded
model listings offer their interfaces to load a new instance of a model).
Raw data
{
"_id": null,
"home_page": null,
"name": "lmstudio",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Alyssa Coghlan <ncoghlan@gmail.com>, Christian Zhou-Zheng <christianzhouzheng@gmail.com>",
"keywords": null,
"author": null,
"author_email": "LM Studio <team@lmstudio.ai>",
"download_url": "https://files.pythonhosted.org/packages/db/6d/40876f14c759fa2072ccbc844cc3ef7c74c1824e17e7d19b2cf4ff2cea2c/lmstudio-1.5.0.tar.gz",
"platform": null,
"description": "# LM Studio Python SDK\n\n## Using the SDK\n\n### Installation\n\nThe SDK can be installed from PyPI as follows:\n\n```console\n$ pip install lmstudio\n```\n\nInstallation from the repository URL or a local clone is also\nsupported for development and pre-release testing purposes.\n\n## Examples\n\nThe base component of the LM Studio SDK is the (synchronous) `Client`.\nThis should be created once and used to manage the underlying\nwebsocket connections to the LM Studio instance.\n\nHowever, a top level convenience API is provided for convenience in\ninteractive use (this API implicitly creates a default `Client` instance\nwhich will remain active until the Python interpreter is terminated).\n\nUsing this convenience API, requesting text completion from an already\nloaded LLM is as straightforward as:\n\n```python\nimport lmstudio as lms\n\nmodel = lms.llm()\nmodel.complete(\"Once upon a time,\")\n```\n\nRequesting a chat response instead only requires the extra step of\nsetting up a `Chat` helper to manage the chat history and include\nit in response prediction requests:\n\n```python\nimport lmstudio as lms\n\nEXAMPLE_MESSAGES = (\n \"My hovercraft is full of eels!\",\n \"I will not buy this record, it is scratched.\"\n)\n\nmodel = lms.llm()\nchat = lms.Chat(\"You are a helpful shopkeeper assisting a foreign traveller\")\nfor message in EXAMPLE_MESSAGES:\n chat.add_user_message(message)\n print(f\"Customer: {message}\")\n response = model.respond(chat)\n chat.add_assistant_response(response)\n print(f\"Shopkeeper: {response}\")\n```\n\nAdditional SDK examples and usage recommendations may be found in the main\n[LM Studio Python SDK documentation](https://lmstudio.ai/docs/python).\n\n## SDK versioning\n\nThe LM Studio Python SDK uses a 3-part `X.Y.Z` numeric version identifier:\n\n* `X`: incremented when the minimum version of significant dependencies is updated\n (for example, dropping support for older versions of Python or LM Studio).\n Previously deprecated features may be dropped when this part of the version number\n increases.\n* `Y`: incremented when new features are added, or some other notable change is\n introduced (such as support for additional versions of Python). New deprecation\n warnings may be introduced when this part of the version number increases.\n* `Z`: incremented for bug fix releases which don't contain any other changes.\n Adding exceptions and warnings for previously undetected situations is considered\n a bug fix.\n\nThis versioning policy is intentionally similar to [semantic versioning](https://semver.org/),\nbut differs in the specifics of when the different parts of the version number will be updated.\n\nRelease candidates *may* be published prior to full releases, but this will typically only\noccur when seeking broader feedback on particular features prior to finalizing the release.\n\nOutside the preparation of a new release, the SDK repository will include a `.devN` suffix\non the nominal Python package version.\n\n## Contributing to SDK development\n\n### Fetching the source code\n\n```console\n$ git clone https://github.com/lmstudio-ai/lmstudio-python\n$ cd lmstudio-python\n```\n\nTo be able to run `tox -e sync-sdk-schema`, it is also\nnecessary to ensure the `lmstudio-js` submodule is updated:\n\n```console\n$ git submodule update --init --recursive\n```\n\n### Development Environment\n\nIn order to work on the Python SDK, you need to install\n:pypi:`pdm`, :pypi:`tox`, and :pypi:`tox-pdm`\n(everything else can be executed via `tox` environments).\n\nGiven these tools, the default development environment can be set up\nand other commands executed as described below.\n\nThe simplest option for handling that is to install `uv`, and then use\nits `uv tool` command to set up `pdm` and a second environment\nwith `tox` + `tox-pdm`. `pipx` is another reasonable option for this task.\n\nIn order to _use_ the Python SDK, you just need some form of\nPython environment manager (since `lmstudio-python` publishes\nthe package `lmstudio` to PyPI).\n\n### Recommended local checks\n\nThe set of checks recommended for local execution are accessible via\nthe `check` marker in `tox`:\n\n```console\n$ tox -m check\n```\n\nThis runs the same checks as the `static` and `test` markers (described below).\n\n### Code consistency checks\n\nThe project source code is autoformatted and linted using :pypi:`ruff`.\nIt also uses :pypi:`mypy` in strict mode to statically check that Python APIs\nare being accessed as expected.\n\nAll of these commands can be invoked via tox:\n\n```console\n$ tox -e format\n```\n\n```console\n$ tox -e lint\n```\n\n```console\n$ tox -e typecheck\n```\n\nLinting and type checking can be executed together using the `static` marker:\n\n```console\n$ tox -m static\n```\n\nAvoid using `# noqa` comments to suppress these warnings - wherever\npossible, warnings should be fixed instead. `# noqa` comments are\nreserved for rare cases where the recommended style causes severe\nreadability problems, and there isn't a more explicit mechanism\n(such as `typing.cast`) to indicate which check is being skipped.\n\n`# fmt: off/on` and `# fmt: skip` comments may be used as needed\nwhen the autoformatter makes readability worse instead of better\n(for example, collapsing lists to a single line when they intentionally\ncover multiple lines, or breaking alignment of end-of-line comments).\n\n### Automated testing\n\nThe project's tests are written using the :pypi:`pytest` test framework.\n:pypi:`tox` is used to automate the setup and execution of these tests\nacross multiple Python versions. One of these is nominated as the\ndefault test target, and is accessible via the `test` marker:\n\n```console\n$ tox -m test\n```\n\nYou can also use other defined versions by specifying the target\nenvironment directly:\n\n```console\n$ tox -e py3.11\n```\n\nThere are additional labels defined for running the oldest test environment,\nthe latest test environment, and all test environments:\n\n```console\n$ tox -m test_oldest\n$ tox -m test_latest\n$ tox -m test_all\n```\n\nTo ensure all the required models are loaded before running the tests, run the\nfollowing command:\n\n```\n$ tox -e load-test-models\n```\n\n`tox` has been configured to forward any additional arguments it is given to\n`pytest`. This enables the use of pytest's\n[rich CLI](https://docs.pytest.org/en/stable/how-to/usage.html#specifying-which-tests-to-run).\nIn particular, you can select tests using all the options that pytest provides:\n\n```console\n$ # Using file name\n$ tox -m test -- tests/test_basics.py\n$ # Using markers\n$ tox -m test -- -m \"slow\"\n$ # Using keyword text search\n$ tox -m test -- -k \"catalog\"\n```\n\nAdditional notes on running and updating the tests can be found in the\n`tests/README.md` file.\n\n\n### Expanding the API\n\n- the content of `src/lmstudio/_sdk_models` is automatically generated by the\n `sync-sdk-schema.py` script in `sdk-schema` and should not be modified directly.\n Run `tox -e sync-sdk-schema` to regenerate the Python submodule from the existing\n export of the `lmstudio-js` schema (for example, after modifying the data model\n template). Run `tox -e sync-sdk-schema -- --regen-schema` after updating the\n `sdk-schema/lmstudio-js` submodule itself to a newer iteration of the\n `lmstudio-js` JSON API.\n- as support for new API namespaces is added to the SDK, each should get a dedicated\n session type (similar to those for the already supported namespaces), even if it\n is only used privately by the client implementation.\n- as support for new API channel endppoints is added to the SDK, each should get a\n dedicated base endpoint type (similar to those for the already supported channels).\n This avoids duplicating the receive message processing between the sync and async APIs.\n- the `json_api.SessionData` base class is useful for defining rich result objects which\n offer additional methods that call back into the SDK (for example, this is how downloaded\n model listings offer their interfaces to load a new instance of a model).\n",
"bugtrack_url": null,
"license": null,
"summary": "LM Studio Python SDK",
"version": "1.5.0",
"project_urls": {
"Documentation": "https://lmstudio.ai/docs/sdk/",
"Homepage": "https://github.com/lmstudio-ai/lmstudio-sdk-python",
"Issues": "https://github.com/lmstudio-ai/lmstudio-sdk-python/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b851dcf7a86872a9de6529d67c68db0319b6f2afa093294d1fb8f1affcc86cc8",
"md5": "a179ef00a8641ed3aac68c7e290a7cf3",
"sha256": "0b1e5a1cf013744a6ce0a80960204af5bf468dbbb2a505acb4dfb67185fffbe9"
},
"downloads": -1,
"filename": "lmstudio-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a179ef00a8641ed3aac68c7e290a7cf3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 139490,
"upload_time": "2025-08-22T13:52:41",
"upload_time_iso_8601": "2025-08-22T13:52:41.456383Z",
"url": "https://files.pythonhosted.org/packages/b8/51/dcf7a86872a9de6529d67c68db0319b6f2afa093294d1fb8f1affcc86cc8/lmstudio-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "db6d40876f14c759fa2072ccbc844cc3ef7c74c1824e17e7d19b2cf4ff2cea2c",
"md5": "17fb1336de9264026f9e98be7d750b5b",
"sha256": "458c34fe1f94a7dcc521d4226b4cee82b8af7ea3da8c40b31bbdac558d9a74d4"
},
"downloads": -1,
"filename": "lmstudio-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "17fb1336de9264026f9e98be7d750b5b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 200230,
"upload_time": "2025-08-22T13:52:42",
"upload_time_iso_8601": "2025-08-22T13:52:42.487243Z",
"url": "https://files.pythonhosted.org/packages/db/6d/40876f14c759fa2072ccbc844cc3ef7c74c1824e17e7d19b2cf4ff2cea2c/lmstudio-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 13:52:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lmstudio-ai",
"github_project": "lmstudio-sdk-python",
"github_not_found": true,
"lcname": "lmstudio"
}
