Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,30 @@ on:
pull_request:

jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install
run: pip install -e ".[dev]"
- name: Lint
run: ruff check src tests
- name: Format
run: ruff format --check src tests
- name: Type check
run: pyright
- name: Build distributions
run: python -m build

test:
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
python-version: ["3.12", "3.13"]
python-version: ["3.12", "3.13", "3.14"]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
Expand Down
49 changes: 27 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ StudioLink is a Python CLI tool that bridges Ollama and LM Studio. It treats Oll
- 🔄 **Sync** - Import models into LM Studio with one command
- 📊 **Status** - Track which models are synced and their current state
- 🩺 **Doctor** - Verify prerequisites and diagnose issues
- 🧹 **Prune** - Reclaim disk space pinned by orphaned import aliases
- 🧹 **Prune** - Safely remove orphaned aliases without breaking symbolic imports
- 🔗 **Smart linking** - Uses hard links by default; pass `--copy` when volumes differ
- 💾 **State tracking** - Remembers what's been synced to avoid re-importing

## Prerequisites

Before using StudioLink, ensure you have:

1. **Ollama** installed, with its model library at `~/.ollama/models/` (or wherever `OLLAMA_MODELS` points)
1. **Ollama** installed with a local model library (StudioLink detects current platform defaults and honors `OLLAMA_MODELS`)
2. **LM Studio** with the `lms` CLI installed
3. **Python 3.12+**

Expand Down Expand Up @@ -100,6 +100,9 @@ sdl sync <modelname> --hard-link
sdl sync <modelname> --copy
sdl sync <modelname> --symbolic-link

# Import the opaque Ollama blob path directly (advanced)
sdl sync <modelname> --direct

# Verbose output
sdl -v sync --all
```
Expand All @@ -110,6 +113,7 @@ sdl -v sync --all
- `--copy` - Use copy mode instead of hard links
- `--hard-link` - Force hard link mode (default)
- `--symbolic-link` - Use symbolic links
- `--direct` - Import the Ollama blob directly without a human-readable alias

### `sdl status`
Show discovered models and their sync state.
Expand All @@ -131,9 +135,9 @@ Discovered 3 model(s); 1 tracked as synced.
```

### `sdl prune`
Remove staging aliases and sync state for models that Ollama no longer has.
Remove aliases and sync state that are no longer needed, after first verifying that the Ollama library was scanned completely.

Because synced models are hard-linked, deleting a model in Ollama does **not** free its disk space until the matching import alias is removed - `sdl prune` does exactly that.
Space recovery depends on the import mode. A copied import can leave the staging alias as the last reference to Ollama's former blob, while an LM Studio hard link continues to retain the model data after the staging alias is removed. Aliases required by symbolic-link imports are preserved so LM Studio is not left with a broken link.

```powershell
# Preview what would be removed
Expand All @@ -159,7 +163,7 @@ sdl doctor --json
- LM Studio CLI (`lms`) exists
- Ollama manifests and blobs directories exist
- LM Studio models directory exists
- Hard-link volume compatibility (same drive)
- Hard-link filesystem/volume compatibility
- Discovered Ollama models
- Blob presence validation
- GGUF header validation
Expand Down Expand Up @@ -202,23 +206,24 @@ When scanning or checking status, models can have these states:

Default paths are platform-aware; every one can be overridden with an environment variable:

| Setting | Windows default | Linux/macOS default | Environment Variable |
|---------|-----------------|---------------------|---------------------|
| Ollama executable | `~\AppData\Local\Programs\Ollama\ollama.exe` | `ollama` from `PATH` (fallback `/usr/bin/ollama`) | `STUDIOLINK_OLLAMA_EXE` |
| LM Studio CLI | `~\.lmstudio\bin\lms.exe` | `lms` from `PATH` (fallback `~/.lmstudio/bin/lms`) | `STUDIOLINK_LMS_EXE` |
| Ollama models | `~\.ollama\models` | `~/.ollama/models` | `STUDIOLINK_OLLAMA_MODELS_DIR` (falls back to Ollama's own `OLLAMA_MODELS`) |
| LM Studio models | `~\.lmstudio\models` | `~/.lmstudio/models` | `STUDIOLINK_LMSTUDIO_MODELS_DIR` |
| State directory | `~\.studiolink` | `~/.studiolink` | `STUDIOLINK_STATE_DIR` |
| Setting | Windows default | Linux default | macOS default | Environment Variable |
|---------|-----------------|---------------|---------------|---------------------|
| Ollama executable | `ollama` from `PATH`, then the standard app path | `ollama` from `PATH` (fallback `/usr/bin/ollama`) | `ollama` from `PATH` (fallback `/usr/bin/ollama`) | `STUDIOLINK_OLLAMA_EXE` |
| LM Studio CLI | `lms` from `PATH`, then `~\.lmstudio\bin\lms.exe` | `lms` from `PATH` (fallback `~/.lmstudio/bin/lms`) | `lms` from `PATH` (fallback `~/.lmstudio/bin/lms`) | `STUDIOLINK_LMS_EXE` |
| Ollama models | `~\.ollama\models` | `/usr/share/ollama/.ollama/models` | `~/.ollama/models` | `STUDIOLINK_OLLAMA_MODELS_DIR` (falls back to Ollama's own `OLLAMA_MODELS`) |
| LM Studio models | LM Studio's configured `downloadsFolder` | LM Studio's configured `downloadsFolder` | LM Studio's configured `downloadsFolder` | `STUDIOLINK_LMSTUDIO_MODELS_DIR` |
| State directory | `~\.studiolink` | `~/.studiolink` | `~/.studiolink` | `STUDIOLINK_STATE_DIR` |

## How It Works

1. **Scanning** - Reads Ollama manifest files from `~/.ollama/models/manifests/` to discover models
2. **Blob Resolution** - Locates GGUF blobs in `~/.ollama/models/blobs/` by digest
1. **Scanning** - Reads manifest files from the configured Ollama models directory
2. **Blob Resolution** - Locates GGUF blobs in Ollama's content-addressed blob directory
3. **Validation** - Verifies blobs start with GGUF magic bytes
4. **Import Aliases** - Creates human-readable `.gguf` hard links in `~/.studiolink/imports/`, named after the model and digest so re-pulled models never reuse a stale alias
4. **Import Aliases** - Creates digest-keyed, human-readable `.gguf` aliases. Copy mode uses a temporary alias on Ollama's filesystem so the state and LM Studio directories may live on other volumes
5. **LM Studio Import** - Uses `lms import` CLI to import models
6. **State Tracking** - Saves sync records to `~/.studiolink/state.json` (written atomically)
7. **Pruning** - `sdl prune` removes aliases for models Ollama no longer has, reclaiming pinned blob space
6. **State Tracking** - Saves sync records and the expected LM Studio target to `~/.studiolink/state.json` (written atomically)
7. **Reconciliation** - Status and sync verify that the expected LM Studio target still exists instead of trusting state alone
8. **Pruning** - Pruning is blocked after unavailable or incomplete Ollama scans and preserves aliases required by symbolic imports

## Troubleshooting

Expand All @@ -229,16 +234,16 @@ ollama pull <model-name>
```

### Hard link fails (cross-volume)
Hard links require the Ollama blob store, the StudioLink state directory, and the LM Studio models directory to live on the same filesystem/volume. If they don't, the sync reports a hard-link error; retry with copy mode instead:
Hard-link imports require the Ollama blob store, StudioLink alias directory, and LM Studio models directory to live on the same filesystem/volume. If they do not, retry with copy mode; copy mode creates its temporary naming alias on Ollama's filesystem and can copy to LM Studio on another volume:

```powershell
sdl sync <model-name> --copy
```

Alternatively, point `STUDIOLINK_STATE_DIR` at a location on the same volume as your Ollama models.
The StudioLink state directory does not need to share Ollama's volume when using copy mode.

### Deleted a model in Ollama but disk space wasn't freed
Synced models keep their blobs alive through hard links in the StudioLink imports directory. Run `sdl prune` to remove aliases for models Ollama no longer has and reclaim the space.
Run `sdl prune` to remove aliases that are no longer needed. If LM Studio imported the model with `--hard-link`, its final hard link intentionally continues to retain the data; removing only the staging alias cannot free those bytes. Symbolic-link aliases are preserved while LM Studio depends on them.

### LM Studio import fails
Run `sdl doctor` to verify:
Expand All @@ -248,11 +253,11 @@ Run `sdl doctor` to verify:

## Design Notes

- **Ollama as source of truth** - StudioLink never modifies Ollama's model store
- **Ollama as source of truth** - StudioLink never changes Ollama manifests or content-addressed blobs; copy mode may briefly create a `.studiolink-imports` alias directory on the same filesystem
- **Hard links by default** - Space-efficient, creates references rather than copies
- **No silent fallbacks** - If a hard link is impossible (cross-volume), the sync fails loudly; use `--copy` explicitly
- **State persistence** - Tracks imports to avoid redundant operations; state is written atomically and corrupt records are skipped, never crash
- **Prune over leak** - Orphaned aliases are cleaned up on demand with `sdl prune` instead of pinning disk space forever
- **Safe pruning** - Orphaned aliases are cleaned up only after a complete source scan; symbolic-link dependencies are retained
- **CLI-only** - No GUI, designed for automation and scripting

## License
Expand Down
31 changes: 26 additions & 5 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
[build-system]
requires = ["setuptools>=68"]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

[project]
name = "studiolink"
version = "0.2.0"
dynamic = ["version"]
description = "Sync Ollama-downloaded GGUF models into LM Studio."
readme = "README.md"
requires-python = ">=3.12"
license = { file = "LICENSE" }
license = "MIT"
license-files = ["LICENSE"]
authors = [
{ name = "StudioLink contributors" }
]
Expand All @@ -17,15 +18,20 @@ classifiers = [
"Development Status :: 3 - Alpha",
"Environment :: Console",
"Intended Audience :: End Users/Desktop",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: 3.14",
]
dependencies = []

[project.optional-dependencies]
dev = ["pytest>=8.0"]
dev = [
"build>=1.2",
"pyright>=1.1.390",
"pytest>=8.0",
"ruff>=0.9",
]

[project.urls]
Homepage = "https://github.com/ensevengg/StudioLink"
Expand All @@ -37,8 +43,23 @@ sdl = "studiolink.cli:main"
[tool.setuptools]
package-dir = {"" = "src"}

[tool.setuptools.dynamic]
version = {attr = "studiolink.__version__"}

[tool.setuptools.packages.find]
where = ["src"]

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.ruff]
target-version = "py312"
line-length = 88

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F", "I"]

[tool.pyright]
include = ["src"]
pythonVersion = "3.12"
typeCheckingMode = "basic"
2 changes: 1 addition & 1 deletion src/studiolink/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@

__all__ = ["__version__"]

__version__ = "0.2.0"
__version__ = "0.2.1"
2 changes: 1 addition & 1 deletion src/studiolink/__main__.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import sys
from studiolink.cli import main

from studiolink.cli import main

if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))
12 changes: 7 additions & 5 deletions src/studiolink/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ def build_parser() -> argparse.ArgumentParser:
action="version",
version=f"StudioLink {__version__}",
)
subparsers = parser.add_subparsers(dest="command", required=True, metavar="<command>")
subparsers = parser.add_subparsers(
dest="command", required=True, metavar="<command>"
)

scan_parser = subparsers.add_parser(
"scan",
Expand Down Expand Up @@ -334,17 +336,17 @@ def run_help(args: argparse.Namespace, service: StudioLinkService) -> int:
Usage: sdl scan [--json] [-v]

sync Import one or more models into LM Studio.
Usage: sdl sync <model> [<model>...] [--copy|--hard-link|--symbolic-link] [--dry-run] [-v]
sdl sync --all [--copy|--hard-link|--symbolic-link] [--dry-run] [-v]
Usage: sdl sync <model> [<model>...] [--copy|--hard-link|--symbolic-link] [--direct] [--dry-run] [--json] [-v]
sdl sync --all [--copy|--hard-link|--symbolic-link] [--direct] [--dry-run] [--json] [-v]

status Show discovered models and sync state.
Usage: sdl status [--json] [-v]

doctor Check local StudioLink prerequisites.
Usage: sdl doctor [--json] [-v]

prune Remove staging aliases and sync state for models that
Ollama no longer has (reclaims pinned blob space).
prune Safely remove unneeded staging aliases and stale state
after a complete Ollama library scan.
Usage: sdl prune [--dry-run] [--json] [-v]

upgrade Check for and install a newer StudioLink version.
Expand Down
33 changes: 29 additions & 4 deletions src/studiolink/config.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
from __future__ import annotations

import json
import os
import shutil
import sys
Expand All @@ -14,18 +15,42 @@ def _expand_path(env_name: str, default: Path) -> Path:
return Path(raw).expanduser() if raw else default.expanduser()


def _default_ollama_models_dir(home: Path) -> Path:
if sys.platform.startswith("linux"):
return Path("/usr/share/ollama/.ollama/models")
return home / ".ollama" / "models"


def _default_ollama_exe(home: Path) -> Path:
if sys.platform == "win32":
return home / "AppData" / "Local" / "Programs" / "Ollama" / "ollama.exe"
return Path(
shutil.which("ollama")
or home / "AppData" / "Local" / "Programs" / "Ollama" / "ollama.exe"
)
return Path(shutil.which("ollama") or "/usr/bin/ollama")


def _default_lms_exe(home: Path) -> Path:
if sys.platform == "win32":
return home / ".lmstudio" / "bin" / "lms.exe"
return Path(shutil.which("lms") or home / ".lmstudio" / "bin" / "lms.exe")
return Path(shutil.which("lms") or home / ".lmstudio" / "bin" / "lms")


def _default_lmstudio_models_dir(home: Path) -> Path:
fallback = home / ".lmstudio" / "models"
settings_path = home / ".lmstudio" / "settings.json"
try:
payload = json.loads(settings_path.read_text(encoding="utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError):
return fallback
if not isinstance(payload, dict):
return fallback
downloads_folder = payload.get("downloadsFolder")
if not isinstance(downloads_folder, str) or not downloads_folder.strip():
return fallback
return Path(downloads_folder).expanduser()


@dataclass(slots=True, frozen=True)
class StudioLinkConfig:
ollama_exe: Path
Expand All @@ -46,7 +71,7 @@ def from_env(cls) -> "StudioLinkConfig":
# StudioLink-specific override is set.
ollama_models_dir = _expand_path(
"STUDIOLINK_OLLAMA_MODELS_DIR",
_expand_path("OLLAMA_MODELS", home / ".ollama" / "models"),
_expand_path("OLLAMA_MODELS", _default_ollama_models_dir(home)),
)
state_dir = _expand_path("STUDIOLINK_STATE_DIR", home / ".studiolink")
return cls(
Expand All @@ -63,7 +88,7 @@ def from_env(cls) -> "StudioLinkConfig":
ollama_blobs_dir=ollama_models_dir / "blobs",
lmstudio_models_dir=_expand_path(
"STUDIOLINK_LMSTUDIO_MODELS_DIR",
home / ".lmstudio" / "models",
_default_lmstudio_models_dir(home),
),
state_dir=state_dir,
state_file=state_dir / "state.json",
Expand Down
12 changes: 8 additions & 4 deletions src/studiolink/lmstudio_adapter.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
from __future__ import annotations

import subprocess
from typing import Any

from studiolink.config import StudioLinkConfig
from studiolink.models import ImportResult, LinkMode
Expand Down Expand Up @@ -38,9 +37,7 @@ def get_version(self) -> str | None:
exc.returncode,
exc.stderr,
) from exc
output = "\n".join(
part for part in (result.stdout, result.stderr) if part
)
output = "\n".join(part for part in (result.stdout, result.stderr) if part)
return output.strip() or None

def get_import_capabilities(self) -> set[LinkMode]:
Expand Down Expand Up @@ -123,3 +120,10 @@ def _run(
-1,
str(exc),
) from exc
except OSError as exc:
raise LMStudioError(
f"Could not execute LM Studio CLI: {exc}",
command,
-1,
str(exc),
) from exc
Loading
Loading