studiolink 0.2.0__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- studiolink-0.3.0/PKG-INFO +306 -0
- studiolink-0.3.0/README.md +280 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/pyproject.toml +26 -5
- {studiolink-0.2.0 → studiolink-0.3.0}/setup.cfg +4 -4
- {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink/__init__.py +1 -1
- {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink/cli.py +68 -16
- studiolink-0.3.0/src/studiolink/config.py +183 -0
- studiolink-0.3.0/src/studiolink/files.py +403 -0
- studiolink-0.3.0/src/studiolink/lmstudio_adapter.py +211 -0
- studiolink-0.3.0/src/studiolink/models.py +457 -0
- studiolink-0.3.0/src/studiolink/ollama_adapter.py +516 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink/ports.py +20 -3
- studiolink-0.3.0/src/studiolink/service.py +604 -0
- studiolink-0.3.0/src/studiolink/state.py +184 -0
- studiolink-0.3.0/src/studiolink/syncer.py +657 -0
- studiolink-0.3.0/src/studiolink/transactions.py +193 -0
- studiolink-0.3.0/src/studiolink.egg-info/PKG-INFO +306 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink.egg-info/SOURCES.txt +11 -0
- studiolink-0.3.0/src/studiolink.egg-info/requires.txt +6 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/tests/test_cli.py +92 -11
- studiolink-0.3.0/tests/test_config.py +236 -0
- studiolink-0.3.0/tests/test_failure_paths.py +203 -0
- studiolink-0.3.0/tests/test_import_lifecycle.py +339 -0
- studiolink-0.3.0/tests/test_import_transactions.py +146 -0
- studiolink-0.3.0/tests/test_lifecycle_sequences.py +74 -0
- studiolink-0.3.0/tests/test_lmstudio_adapter.py +144 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/tests/test_models.py +82 -9
- studiolink-0.3.0/tests/test_ollama_adapter.py +332 -0
- studiolink-0.3.0/tests/test_ollama_manifests_v2.py +373 -0
- studiolink-0.3.0/tests/test_real_lms.py +215 -0
- studiolink-0.3.0/tests/test_release_review.py +417 -0
- studiolink-0.3.0/tests/test_review_fixes.py +205 -0
- studiolink-0.3.0/tests/test_service.py +643 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/tests/test_state.py +78 -8
- studiolink-0.3.0/tests/test_syncer.py +1013 -0
- studiolink-0.2.0/PKG-INFO +0 -304
- studiolink-0.2.0/README.md +0 -260
- studiolink-0.2.0/src/studiolink/config.py +0 -71
- studiolink-0.2.0/src/studiolink/lmstudio_adapter.py +0 -125
- studiolink-0.2.0/src/studiolink/models.py +0 -194
- studiolink-0.2.0/src/studiolink/ollama_adapter.py +0 -164
- studiolink-0.2.0/src/studiolink/service.py +0 -343
- studiolink-0.2.0/src/studiolink/state.py +0 -91
- studiolink-0.2.0/src/studiolink/syncer.py +0 -215
- studiolink-0.2.0/src/studiolink.egg-info/PKG-INFO +0 -304
- studiolink-0.2.0/src/studiolink.egg-info/requires.txt +0 -3
- studiolink-0.2.0/tests/test_config.py +0 -91
- studiolink-0.2.0/tests/test_ollama_adapter.py +0 -149
- studiolink-0.2.0/tests/test_service.py +0 -247
- studiolink-0.2.0/tests/test_syncer.py +0 -284
- {studiolink-0.2.0 → studiolink-0.3.0}/LICENSE +0 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink/__main__.py +1 -1
- {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink.egg-info/dependency_links.txt +0 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink.egg-info/entry_points.txt +0 -0
- {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink.egg-info/top_level.txt +0 -0
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: studiolink
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Sync Ollama-downloaded GGUF models into LM Studio.
|
|
5
|
+
Author: StudioLink contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ensevengg/StudioLink
|
|
8
|
+
Project-URL: Repository, https://github.com/ensevengg/StudioLink
|
|
9
|
+
Keywords: ollama,lm-studio,gguf,cli,sync
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Requires-Python: >=3.12
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Provides-Extra: dev
|
|
21
|
+
Requires-Dist: build>=1.2; extra == "dev"
|
|
22
|
+
Requires-Dist: pyright>=1.1.390; extra == "dev"
|
|
23
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
24
|
+
Requires-Dist: ruff>=0.9; extra == "dev"
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# StudioLink
|
|
28
|
+
|
|
29
|
+
**Sync Ollama-downloaded GGUF models into LM Studio.**
|
|
30
|
+
|
|
31
|
+
StudioLink is a Python CLI tool that bridges Ollama and LM Studio. It treats Ollama as the source of truth, discovers GGUF-backed models from Ollama manifests, and imports them into LM Studio via the `lms` CLI—using hard links when the filesystem allows them, and symbolic links otherwise, to save disk space.
|
|
32
|
+
|
|
33
|
+
## Features
|
|
34
|
+
|
|
35
|
+
- 🔍 **Scan** - Discover all GGUF models and supported vision projectors in your Ollama library
|
|
36
|
+
- 🔄 **Sync** - Import models into LM Studio with one command
|
|
37
|
+
- 📊 **Status** - Track which models are synced and their current state
|
|
38
|
+
- 🩺 **Doctor** - Verify prerequisites and diagnose issues
|
|
39
|
+
- 🧹 **Prune** - Remove obsolete managed imports and aliases to release pinned disk space
|
|
40
|
+
- 🔗 **Smart linking** - Uses hard links when possible and switches to symbolic links (or copies) automatically when they aren't, e.g. across volumes or btrfs subvolumes
|
|
41
|
+
- 💾 **State tracking** - Remembers what's been synced to avoid re-importing
|
|
42
|
+
|
|
43
|
+
## Prerequisites
|
|
44
|
+
|
|
45
|
+
Before using StudioLink, ensure you have:
|
|
46
|
+
|
|
47
|
+
1. **Ollama** installed with a local model library (StudioLink detects platform defaults, including Linux system-service and distro-package stores, and honors `OLLAMA_MODELS`)
|
|
48
|
+
2. **LM Studio** with the `lms` CLI installed
|
|
49
|
+
3. **Python 3.12+**
|
|
50
|
+
|
|
51
|
+
Default executable locations are detected per platform (e.g. `ollama.exe` under `AppData` on Windows; `ollama` from your `PATH` and `~/.lmstudio/bin/lms` on Linux/macOS). Override with environment variables if yours differ - see [Configuration](#configuration).
|
|
52
|
+
|
|
53
|
+
## Installation
|
|
54
|
+
|
|
55
|
+
```powershell
|
|
56
|
+
pip install studiolink
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
To upgrade to the latest version:
|
|
60
|
+
|
|
61
|
+
```powershell
|
|
62
|
+
sdl upgrade
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Quick Start
|
|
66
|
+
|
|
67
|
+
```powershell
|
|
68
|
+
# Scan for available models
|
|
69
|
+
sdl scan
|
|
70
|
+
|
|
71
|
+
# Import a specific model
|
|
72
|
+
sdl sync <modelname>
|
|
73
|
+
|
|
74
|
+
# Import all discovered models
|
|
75
|
+
sdl sync --all
|
|
76
|
+
|
|
77
|
+
# Check sync status
|
|
78
|
+
sdl status
|
|
79
|
+
|
|
80
|
+
# Verify everything is set up correctly
|
|
81
|
+
sdl doctor
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Commands
|
|
85
|
+
|
|
86
|
+
### `sdl scan`
|
|
87
|
+
Discover all GGUF-backed Ollama models available for import.
|
|
88
|
+
|
|
89
|
+
```powershell
|
|
90
|
+
# Basic scan
|
|
91
|
+
sdl scan
|
|
92
|
+
|
|
93
|
+
# Output as JSON
|
|
94
|
+
sdl scan --json
|
|
95
|
+
|
|
96
|
+
# Verbose output (debug logging)
|
|
97
|
+
sdl -v scan
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Output:**
|
|
101
|
+
```
|
|
102
|
+
Discovered 3 model(s):
|
|
103
|
+
- <modelname> [ready]
|
|
104
|
+
blob: C:\Users\...\ollama\models\blobs\sha256-...
|
|
105
|
+
- <modelname2> [stale]
|
|
106
|
+
blob: C:\Users\...\ollama\models\blobs\sha256-...
|
|
107
|
+
issues: model blob is missing from the Ollama blob store
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### `sdl sync`
|
|
111
|
+
Import one or more models into LM Studio.
|
|
112
|
+
|
|
113
|
+
```powershell
|
|
114
|
+
# Import specific model(s)
|
|
115
|
+
sdl sync <modelname>
|
|
116
|
+
sdl sync <model1> <model2> <model3>
|
|
117
|
+
|
|
118
|
+
# Import all discovered models
|
|
119
|
+
sdl sync --all
|
|
120
|
+
|
|
121
|
+
# Preview without making changes (dry run)
|
|
122
|
+
sdl sync <modelname> --dry-run
|
|
123
|
+
|
|
124
|
+
# Use a specific link mode
|
|
125
|
+
sdl sync <modelname> --hard-link
|
|
126
|
+
sdl sync <modelname> --copy
|
|
127
|
+
sdl sync <modelname> --symbolic-link
|
|
128
|
+
|
|
129
|
+
# Import the opaque Ollama blob path directly (advanced)
|
|
130
|
+
sdl sync <modelname> --direct
|
|
131
|
+
|
|
132
|
+
# Verbose output
|
|
133
|
+
sdl -v sync --all
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
**Options:**
|
|
137
|
+
- `--all` - Sync every discovered model
|
|
138
|
+
- `--dry-run` - Preview the import without making changes
|
|
139
|
+
- `--copy` - Copy the weights (uses disk space, but keeps working if Ollama deletes the model)
|
|
140
|
+
- `--hard-link` - Force hard links; fails if they are not possible
|
|
141
|
+
- `--symbolic-link` - Use symbolic links
|
|
142
|
+
|
|
143
|
+
Without a mode flag, sync probes the machine and uses hard links if they work, otherwise symbolic links, otherwise copies, and prints which mode it picked. Models that are already synced keep the mode they were imported with.
|
|
144
|
+
- `--direct` - Import a single-artifact Ollama blob directly without a human-readable alias; model-plus-projector bundles require aliases
|
|
145
|
+
|
|
146
|
+
### `sdl status`
|
|
147
|
+
Show discovered models and their sync state.
|
|
148
|
+
|
|
149
|
+
```powershell
|
|
150
|
+
sdl status
|
|
151
|
+
sdl status --json
|
|
152
|
+
sdl -v status
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
**Output:**
|
|
156
|
+
```
|
|
157
|
+
Discovered 3 model(s); 1 tracked as synced.
|
|
158
|
+
- <modelname>: synced
|
|
159
|
+
imported: 2026-04-12T10:30:00+00:00
|
|
160
|
+
- <modelname2>: stale
|
|
161
|
+
issues: model blob is missing from the Ollama blob store
|
|
162
|
+
- <modelname3>: pending
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### `sdl prune`
|
|
166
|
+
Remove tracked LM Studio imports, staging aliases, and sync state for models that Ollama no longer has or has replaced.
|
|
167
|
+
|
|
168
|
+
Hard-linked weights remain on disk until **all** links are removed, including the LM Studio destination. `sdl prune` removes both the tracked destination and its staging alias. It preserves files whose identity has changed and refuses cleanup after an incomplete source scan or when either model library is unavailable. It also recovers abandoned import transactions and temporary copy aliases. Files already present in LM Studio without a verifiable StudioLink record are left alone.
|
|
169
|
+
|
|
170
|
+
```powershell
|
|
171
|
+
# Preview what would be removed
|
|
172
|
+
sdl prune --dry-run
|
|
173
|
+
|
|
174
|
+
# Actually remove orphaned aliases and stale sync records
|
|
175
|
+
sdl prune
|
|
176
|
+
|
|
177
|
+
# Output as JSON
|
|
178
|
+
sdl prune --json
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### `sdl doctor`
|
|
182
|
+
Check local StudioLink prerequisites and diagnose issues.
|
|
183
|
+
|
|
184
|
+
```powershell
|
|
185
|
+
sdl doctor
|
|
186
|
+
sdl doctor --json
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
**Checks include:**
|
|
190
|
+
- Ollama executable exists
|
|
191
|
+
- LM Studio CLI (`lms`) exists
|
|
192
|
+
- Ollama manifests (`manifests-v2/` from Ollama 0.40+, or legacy `manifests/`) and blobs directories exist
|
|
193
|
+
- LM Studio models directory exists
|
|
194
|
+
- Default link mode: which mode sync will use without a flag, and why. A real link is created and removed again (even before StudioLink's directories exist), catching different volumes, btrfs subvolumes, and Linux `fs.protected_hardlinks`
|
|
195
|
+
- LM Studio model inventory (`lms ls --json`; required to verify projector bundles)
|
|
196
|
+
- Discovered Ollama models
|
|
197
|
+
- Blob presence validation
|
|
198
|
+
- GGUF header validation
|
|
199
|
+
|
|
200
|
+
### `sdl help`
|
|
201
|
+
Show all available commands and their descriptions.
|
|
202
|
+
|
|
203
|
+
```powershell
|
|
204
|
+
sdl help
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## Global Options
|
|
208
|
+
|
|
209
|
+
All commands support these global options:
|
|
210
|
+
|
|
211
|
+
- `-v, --verbose` - Enable verbose output (debug logging)
|
|
212
|
+
- `--version` - Show version information
|
|
213
|
+
- `--help` - Show help for the specific command
|
|
214
|
+
|
|
215
|
+
```powershell
|
|
216
|
+
# Examples
|
|
217
|
+
sdl -v scan # Scan with debug logging
|
|
218
|
+
sdl sync --help # Show help for sync command
|
|
219
|
+
sdl --version # Show version
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Model Readiness States
|
|
223
|
+
|
|
224
|
+
When scanning or checking status, models can have these states:
|
|
225
|
+
|
|
226
|
+
| State | Description | Action Required |
|
|
227
|
+
|-------|-------------|-----------------|
|
|
228
|
+
| **ready** | Every required model/projector blob exists and has a valid GGUF header | Ready to sync |
|
|
229
|
+
| **stale** | A required model/projector blob is missing | Run `ollama pull <model>` to restore |
|
|
230
|
+
| **invalid** | An artifact is malformed or the manifest uses an unsupported artifact combination | Inspect the reported issues |
|
|
231
|
+
| **synced** | Already imported into LM Studio | No action needed |
|
|
232
|
+
| **pending** | Ready but not yet synced | Run `sdl sync` |
|
|
233
|
+
|
|
234
|
+
## Configuration
|
|
235
|
+
|
|
236
|
+
Default paths are platform-aware; every one can be overridden with an environment variable:
|
|
237
|
+
|
|
238
|
+
| Setting | Windows default | Linux default | macOS default | Environment Variable |
|
|
239
|
+
|---------|-----------------|---------------|---------------|---------------------|
|
|
240
|
+
| 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` |
|
|
241
|
+
| 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` |
|
|
242
|
+
| Ollama models | `~\.ollama\models` | First existing of: the `ollama` systemd unit's `OLLAMA_MODELS`, `/usr/share/ollama/.ollama/models` (official installer), `/var/lib/ollama` (Arch/CachyOS package), `~/.ollama/models` | `~/.ollama/models` | `STUDIOLINK_OLLAMA_MODELS_DIR` (falls back to Ollama's own `OLLAMA_MODELS`) |
|
|
243
|
+
| LM Studio models | LM Studio's configured `downloadsFolder` | LM Studio's configured `downloadsFolder` | LM Studio's configured `downloadsFolder` | `STUDIOLINK_LMSTUDIO_MODELS_DIR` |
|
|
244
|
+
| State directory | `~\.studiolink` | `~/.studiolink` | `~/.studiolink` | `STUDIOLINK_STATE_DIR` |
|
|
245
|
+
|
|
246
|
+
The LM Studio models override must match the models directory selected in LM Studio; it does not change where `lms import` writes files. A mismatch is reported before importing.
|
|
247
|
+
|
|
248
|
+
## How It Works
|
|
249
|
+
|
|
250
|
+
1. **Scanning** - Reads named manifests from both `manifests-v2/` (Ollama 0.40+, links to content-addressed manifest blobs) and the legacy `manifests/` tree, preferring v2 when a name exists in both. For Ollama manifest lists it picks the llama.cpp GGUF child, falling back to the `ggml` child; internal `llamacpp:<digest>` downgrade tags are ignored
|
|
251
|
+
2. **Artifact Resolution** - Locates the primary model and optional projector GGUF in Ollama's content-addressed blob directory
|
|
252
|
+
3. **Validation** - Checks every required artifact's SHA-256 digest syntax, GGUF magic bytes, and the blob size declared in the manifest
|
|
253
|
+
4. **Import Aliases** - Creates digest-keyed, human-readable `.gguf` aliases; projectors use the LM Studio-recognized `mmproj-` prefix. Copy mode uses temporary aliases on Ollama's filesystem, removed after the import; other modes use `~/.studiolink/imports/`
|
|
254
|
+
5. **LM Studio Import** - Uses one `lms import` call per artifact to stage and verify the requested link/copy, then publishes each destination without overwriting an existing file. Each model/projector pair lands in the same digest-isolated repository so a re-pull cannot leave LM Studio choosing an older projector. Failed imports clean up partial files; subsequent sync or prune recovers abandoned transactions after a process crash
|
|
255
|
+
6. **State Tracking** - Saves resumable per-artifact destination paths and file identities to schema-v2 `~/.studiolink/state.json` (written atomically; schema-v1 records remain readable). Sync and prune operations share a process lock.
|
|
256
|
+
7. **Reconciliation** - Status and sync verify every imported file before skipping, repair missing destinations, and confirm projector bundles through `lms ls --json`. An import whose Ollama blob was deleted stays synced only while it is the unchanged file StudioLink recorded.
|
|
257
|
+
8. **Cleanup** - Successful replacement imports remove the previous managed destinations and aliases; a failed re-pull keeps the previous import tracked. `sdl prune` removes obsolete tracked imports and orphaned aliases after a complete Ollama scan; its dry run counts shared file data once.
|
|
258
|
+
|
|
259
|
+
## Troubleshooting
|
|
260
|
+
|
|
261
|
+
### "model blob is missing from the Ollama blob store"
|
|
262
|
+
The model manifest exists but the actual blob file has been deleted or purged by Ollama. Re-download it:
|
|
263
|
+
```powershell
|
|
264
|
+
ollama pull <model-name>
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### "Ollama MLX (safetensors) models are not supported"
|
|
268
|
+
The model only has an MLX build in Ollama (common on Apple Silicon), which has no GGUF file for LM Studio to import. Pull a GGUF variant of the model, or download it in LM Studio directly.
|
|
269
|
+
|
|
270
|
+
### Hard link fails
|
|
271
|
+
Hard links need the Ollama blob store, the StudioLink state directory, and the LM Studio models directory on the same filesystem - and on Linux, separate btrfs subvolumes (such as CachyOS's default `@` and `@home`) count as different filesystems. When Ollama runs as a system service, its blobs belong to the `ollama` user and `fs.protected_hardlinks` also blocks linking them.
|
|
272
|
+
|
|
273
|
+
Without a mode flag, sync detects this and uses symbolic links instead; `sdl doctor` shows the mode it will pick. If you passed `--hard-link`, drop it or choose another mode:
|
|
274
|
+
|
|
275
|
+
```sh
|
|
276
|
+
sdl sync <model-name> --symbolic-link # no extra disk space; breaks if Ollama deletes the model
|
|
277
|
+
sdl sync <model-name> --copy # full copy; independent of Ollama
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
Copy mode creates its temporary naming alias on Ollama's filesystem when it can, and otherwise uses a symbolic link in StudioLink's own directory. Symbolic-link mode requires permission to create symlinks on Windows (Developer Mode).
|
|
281
|
+
|
|
282
|
+
### Deleted a model in Ollama but disk space wasn't freed
|
|
283
|
+
Both LM Studio imports and StudioLink staging aliases can keep a deleted Ollama blob alive. Run `sdl prune --dry-run` to preview cleanup, then `sdl prune` to remove the obsolete managed files. Untracked LM Studio files may still hold links and need separate inspection.
|
|
284
|
+
|
|
285
|
+
### LM Studio import fails
|
|
286
|
+
Run `sdl doctor` to verify:
|
|
287
|
+
- LM Studio is installed
|
|
288
|
+
- `lms` CLI is in PATH
|
|
289
|
+
- Import directories are writable
|
|
290
|
+
|
|
291
|
+
## Design Notes
|
|
292
|
+
|
|
293
|
+
- **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
|
|
294
|
+
- **Hard links when possible** - Space-efficient, creates references rather than copies
|
|
295
|
+
- **No silent fallbacks** - An explicit mode flag never falls back; it fails with a hint. Without a flag, sync prints the mode it picked and why
|
|
296
|
+
- **State persistence** - Tracks and verifies actual imports to avoid redundant operations; state is written atomically and corrupt records are skipped. Verified existing files can restore lost state.
|
|
297
|
+
- **Copy deduplication** - Tags with identical weights share one destination copy through hard links when the destination filesystem supports them.
|
|
298
|
+
- **Dry runs** - Preview sync actions without replacing aliases or invoking an import.
|
|
299
|
+
- **Prune over leak** - Obsolete tracked destinations and orphaned aliases are cleaned up with `sdl prune` instead of pinning disk space forever; symbolic-link dependencies are retained
|
|
300
|
+
- **Supported bundles** - Any number of Ollama models can be synced; each manifest may contain one primary model GGUF and at most one projector GGUF
|
|
301
|
+
- **Explicit limitations** - Manifests with multiple primary models/projectors or Ollama adapter, draft, or tensor artifacts are reported as unsupported rather than partially imported
|
|
302
|
+
- **CLI-only** - No GUI, designed for automation and scripting
|
|
303
|
+
|
|
304
|
+
## License
|
|
305
|
+
|
|
306
|
+
MIT License - See [LICENSE](LICENSE) for details.
|
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
# StudioLink
|
|
2
|
+
|
|
3
|
+
**Sync Ollama-downloaded GGUF models into LM Studio.**
|
|
4
|
+
|
|
5
|
+
StudioLink is a Python CLI tool that bridges Ollama and LM Studio. It treats Ollama as the source of truth, discovers GGUF-backed models from Ollama manifests, and imports them into LM Studio via the `lms` CLI—using hard links when the filesystem allows them, and symbolic links otherwise, to save disk space.
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- 🔍 **Scan** - Discover all GGUF models and supported vision projectors in your Ollama library
|
|
10
|
+
- 🔄 **Sync** - Import models into LM Studio with one command
|
|
11
|
+
- 📊 **Status** - Track which models are synced and their current state
|
|
12
|
+
- 🩺 **Doctor** - Verify prerequisites and diagnose issues
|
|
13
|
+
- 🧹 **Prune** - Remove obsolete managed imports and aliases to release pinned disk space
|
|
14
|
+
- 🔗 **Smart linking** - Uses hard links when possible and switches to symbolic links (or copies) automatically when they aren't, e.g. across volumes or btrfs subvolumes
|
|
15
|
+
- 💾 **State tracking** - Remembers what's been synced to avoid re-importing
|
|
16
|
+
|
|
17
|
+
## Prerequisites
|
|
18
|
+
|
|
19
|
+
Before using StudioLink, ensure you have:
|
|
20
|
+
|
|
21
|
+
1. **Ollama** installed with a local model library (StudioLink detects platform defaults, including Linux system-service and distro-package stores, and honors `OLLAMA_MODELS`)
|
|
22
|
+
2. **LM Studio** with the `lms` CLI installed
|
|
23
|
+
3. **Python 3.12+**
|
|
24
|
+
|
|
25
|
+
Default executable locations are detected per platform (e.g. `ollama.exe` under `AppData` on Windows; `ollama` from your `PATH` and `~/.lmstudio/bin/lms` on Linux/macOS). Override with environment variables if yours differ - see [Configuration](#configuration).
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
```powershell
|
|
30
|
+
pip install studiolink
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
To upgrade to the latest version:
|
|
34
|
+
|
|
35
|
+
```powershell
|
|
36
|
+
sdl upgrade
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
```powershell
|
|
42
|
+
# Scan for available models
|
|
43
|
+
sdl scan
|
|
44
|
+
|
|
45
|
+
# Import a specific model
|
|
46
|
+
sdl sync <modelname>
|
|
47
|
+
|
|
48
|
+
# Import all discovered models
|
|
49
|
+
sdl sync --all
|
|
50
|
+
|
|
51
|
+
# Check sync status
|
|
52
|
+
sdl status
|
|
53
|
+
|
|
54
|
+
# Verify everything is set up correctly
|
|
55
|
+
sdl doctor
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Commands
|
|
59
|
+
|
|
60
|
+
### `sdl scan`
|
|
61
|
+
Discover all GGUF-backed Ollama models available for import.
|
|
62
|
+
|
|
63
|
+
```powershell
|
|
64
|
+
# Basic scan
|
|
65
|
+
sdl scan
|
|
66
|
+
|
|
67
|
+
# Output as JSON
|
|
68
|
+
sdl scan --json
|
|
69
|
+
|
|
70
|
+
# Verbose output (debug logging)
|
|
71
|
+
sdl -v scan
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
**Output:**
|
|
75
|
+
```
|
|
76
|
+
Discovered 3 model(s):
|
|
77
|
+
- <modelname> [ready]
|
|
78
|
+
blob: C:\Users\...\ollama\models\blobs\sha256-...
|
|
79
|
+
- <modelname2> [stale]
|
|
80
|
+
blob: C:\Users\...\ollama\models\blobs\sha256-...
|
|
81
|
+
issues: model blob is missing from the Ollama blob store
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### `sdl sync`
|
|
85
|
+
Import one or more models into LM Studio.
|
|
86
|
+
|
|
87
|
+
```powershell
|
|
88
|
+
# Import specific model(s)
|
|
89
|
+
sdl sync <modelname>
|
|
90
|
+
sdl sync <model1> <model2> <model3>
|
|
91
|
+
|
|
92
|
+
# Import all discovered models
|
|
93
|
+
sdl sync --all
|
|
94
|
+
|
|
95
|
+
# Preview without making changes (dry run)
|
|
96
|
+
sdl sync <modelname> --dry-run
|
|
97
|
+
|
|
98
|
+
# Use a specific link mode
|
|
99
|
+
sdl sync <modelname> --hard-link
|
|
100
|
+
sdl sync <modelname> --copy
|
|
101
|
+
sdl sync <modelname> --symbolic-link
|
|
102
|
+
|
|
103
|
+
# Import the opaque Ollama blob path directly (advanced)
|
|
104
|
+
sdl sync <modelname> --direct
|
|
105
|
+
|
|
106
|
+
# Verbose output
|
|
107
|
+
sdl -v sync --all
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Options:**
|
|
111
|
+
- `--all` - Sync every discovered model
|
|
112
|
+
- `--dry-run` - Preview the import without making changes
|
|
113
|
+
- `--copy` - Copy the weights (uses disk space, but keeps working if Ollama deletes the model)
|
|
114
|
+
- `--hard-link` - Force hard links; fails if they are not possible
|
|
115
|
+
- `--symbolic-link` - Use symbolic links
|
|
116
|
+
|
|
117
|
+
Without a mode flag, sync probes the machine and uses hard links if they work, otherwise symbolic links, otherwise copies, and prints which mode it picked. Models that are already synced keep the mode they were imported with.
|
|
118
|
+
- `--direct` - Import a single-artifact Ollama blob directly without a human-readable alias; model-plus-projector bundles require aliases
|
|
119
|
+
|
|
120
|
+
### `sdl status`
|
|
121
|
+
Show discovered models and their sync state.
|
|
122
|
+
|
|
123
|
+
```powershell
|
|
124
|
+
sdl status
|
|
125
|
+
sdl status --json
|
|
126
|
+
sdl -v status
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**Output:**
|
|
130
|
+
```
|
|
131
|
+
Discovered 3 model(s); 1 tracked as synced.
|
|
132
|
+
- <modelname>: synced
|
|
133
|
+
imported: 2026-04-12T10:30:00+00:00
|
|
134
|
+
- <modelname2>: stale
|
|
135
|
+
issues: model blob is missing from the Ollama blob store
|
|
136
|
+
- <modelname3>: pending
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### `sdl prune`
|
|
140
|
+
Remove tracked LM Studio imports, staging aliases, and sync state for models that Ollama no longer has or has replaced.
|
|
141
|
+
|
|
142
|
+
Hard-linked weights remain on disk until **all** links are removed, including the LM Studio destination. `sdl prune` removes both the tracked destination and its staging alias. It preserves files whose identity has changed and refuses cleanup after an incomplete source scan or when either model library is unavailable. It also recovers abandoned import transactions and temporary copy aliases. Files already present in LM Studio without a verifiable StudioLink record are left alone.
|
|
143
|
+
|
|
144
|
+
```powershell
|
|
145
|
+
# Preview what would be removed
|
|
146
|
+
sdl prune --dry-run
|
|
147
|
+
|
|
148
|
+
# Actually remove orphaned aliases and stale sync records
|
|
149
|
+
sdl prune
|
|
150
|
+
|
|
151
|
+
# Output as JSON
|
|
152
|
+
sdl prune --json
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### `sdl doctor`
|
|
156
|
+
Check local StudioLink prerequisites and diagnose issues.
|
|
157
|
+
|
|
158
|
+
```powershell
|
|
159
|
+
sdl doctor
|
|
160
|
+
sdl doctor --json
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**Checks include:**
|
|
164
|
+
- Ollama executable exists
|
|
165
|
+
- LM Studio CLI (`lms`) exists
|
|
166
|
+
- Ollama manifests (`manifests-v2/` from Ollama 0.40+, or legacy `manifests/`) and blobs directories exist
|
|
167
|
+
- LM Studio models directory exists
|
|
168
|
+
- Default link mode: which mode sync will use without a flag, and why. A real link is created and removed again (even before StudioLink's directories exist), catching different volumes, btrfs subvolumes, and Linux `fs.protected_hardlinks`
|
|
169
|
+
- LM Studio model inventory (`lms ls --json`; required to verify projector bundles)
|
|
170
|
+
- Discovered Ollama models
|
|
171
|
+
- Blob presence validation
|
|
172
|
+
- GGUF header validation
|
|
173
|
+
|
|
174
|
+
### `sdl help`
|
|
175
|
+
Show all available commands and their descriptions.
|
|
176
|
+
|
|
177
|
+
```powershell
|
|
178
|
+
sdl help
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Global Options
|
|
182
|
+
|
|
183
|
+
All commands support these global options:
|
|
184
|
+
|
|
185
|
+
- `-v, --verbose` - Enable verbose output (debug logging)
|
|
186
|
+
- `--version` - Show version information
|
|
187
|
+
- `--help` - Show help for the specific command
|
|
188
|
+
|
|
189
|
+
```powershell
|
|
190
|
+
# Examples
|
|
191
|
+
sdl -v scan # Scan with debug logging
|
|
192
|
+
sdl sync --help # Show help for sync command
|
|
193
|
+
sdl --version # Show version
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Model Readiness States
|
|
197
|
+
|
|
198
|
+
When scanning or checking status, models can have these states:
|
|
199
|
+
|
|
200
|
+
| State | Description | Action Required |
|
|
201
|
+
|-------|-------------|-----------------|
|
|
202
|
+
| **ready** | Every required model/projector blob exists and has a valid GGUF header | Ready to sync |
|
|
203
|
+
| **stale** | A required model/projector blob is missing | Run `ollama pull <model>` to restore |
|
|
204
|
+
| **invalid** | An artifact is malformed or the manifest uses an unsupported artifact combination | Inspect the reported issues |
|
|
205
|
+
| **synced** | Already imported into LM Studio | No action needed |
|
|
206
|
+
| **pending** | Ready but not yet synced | Run `sdl sync` |
|
|
207
|
+
|
|
208
|
+
## Configuration
|
|
209
|
+
|
|
210
|
+
Default paths are platform-aware; every one can be overridden with an environment variable:
|
|
211
|
+
|
|
212
|
+
| Setting | Windows default | Linux default | macOS default | Environment Variable |
|
|
213
|
+
|---------|-----------------|---------------|---------------|---------------------|
|
|
214
|
+
| 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` |
|
|
215
|
+
| 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` |
|
|
216
|
+
| Ollama models | `~\.ollama\models` | First existing of: the `ollama` systemd unit's `OLLAMA_MODELS`, `/usr/share/ollama/.ollama/models` (official installer), `/var/lib/ollama` (Arch/CachyOS package), `~/.ollama/models` | `~/.ollama/models` | `STUDIOLINK_OLLAMA_MODELS_DIR` (falls back to Ollama's own `OLLAMA_MODELS`) |
|
|
217
|
+
| LM Studio models | LM Studio's configured `downloadsFolder` | LM Studio's configured `downloadsFolder` | LM Studio's configured `downloadsFolder` | `STUDIOLINK_LMSTUDIO_MODELS_DIR` |
|
|
218
|
+
| State directory | `~\.studiolink` | `~/.studiolink` | `~/.studiolink` | `STUDIOLINK_STATE_DIR` |
|
|
219
|
+
|
|
220
|
+
The LM Studio models override must match the models directory selected in LM Studio; it does not change where `lms import` writes files. A mismatch is reported before importing.
|
|
221
|
+
|
|
222
|
+
## How It Works
|
|
223
|
+
|
|
224
|
+
1. **Scanning** - Reads named manifests from both `manifests-v2/` (Ollama 0.40+, links to content-addressed manifest blobs) and the legacy `manifests/` tree, preferring v2 when a name exists in both. For Ollama manifest lists it picks the llama.cpp GGUF child, falling back to the `ggml` child; internal `llamacpp:<digest>` downgrade tags are ignored
|
|
225
|
+
2. **Artifact Resolution** - Locates the primary model and optional projector GGUF in Ollama's content-addressed blob directory
|
|
226
|
+
3. **Validation** - Checks every required artifact's SHA-256 digest syntax, GGUF magic bytes, and the blob size declared in the manifest
|
|
227
|
+
4. **Import Aliases** - Creates digest-keyed, human-readable `.gguf` aliases; projectors use the LM Studio-recognized `mmproj-` prefix. Copy mode uses temporary aliases on Ollama's filesystem, removed after the import; other modes use `~/.studiolink/imports/`
|
|
228
|
+
5. **LM Studio Import** - Uses one `lms import` call per artifact to stage and verify the requested link/copy, then publishes each destination without overwriting an existing file. Each model/projector pair lands in the same digest-isolated repository so a re-pull cannot leave LM Studio choosing an older projector. Failed imports clean up partial files; subsequent sync or prune recovers abandoned transactions after a process crash
|
|
229
|
+
6. **State Tracking** - Saves resumable per-artifact destination paths and file identities to schema-v2 `~/.studiolink/state.json` (written atomically; schema-v1 records remain readable). Sync and prune operations share a process lock.
|
|
230
|
+
7. **Reconciliation** - Status and sync verify every imported file before skipping, repair missing destinations, and confirm projector bundles through `lms ls --json`. An import whose Ollama blob was deleted stays synced only while it is the unchanged file StudioLink recorded.
|
|
231
|
+
8. **Cleanup** - Successful replacement imports remove the previous managed destinations and aliases; a failed re-pull keeps the previous import tracked. `sdl prune` removes obsolete tracked imports and orphaned aliases after a complete Ollama scan; its dry run counts shared file data once.
|
|
232
|
+
|
|
233
|
+
## Troubleshooting
|
|
234
|
+
|
|
235
|
+
### "model blob is missing from the Ollama blob store"
|
|
236
|
+
The model manifest exists but the actual blob file has been deleted or purged by Ollama. Re-download it:
|
|
237
|
+
```powershell
|
|
238
|
+
ollama pull <model-name>
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### "Ollama MLX (safetensors) models are not supported"
|
|
242
|
+
The model only has an MLX build in Ollama (common on Apple Silicon), which has no GGUF file for LM Studio to import. Pull a GGUF variant of the model, or download it in LM Studio directly.
|
|
243
|
+
|
|
244
|
+
### Hard link fails
|
|
245
|
+
Hard links need the Ollama blob store, the StudioLink state directory, and the LM Studio models directory on the same filesystem - and on Linux, separate btrfs subvolumes (such as CachyOS's default `@` and `@home`) count as different filesystems. When Ollama runs as a system service, its blobs belong to the `ollama` user and `fs.protected_hardlinks` also blocks linking them.
|
|
246
|
+
|
|
247
|
+
Without a mode flag, sync detects this and uses symbolic links instead; `sdl doctor` shows the mode it will pick. If you passed `--hard-link`, drop it or choose another mode:
|
|
248
|
+
|
|
249
|
+
```sh
|
|
250
|
+
sdl sync <model-name> --symbolic-link # no extra disk space; breaks if Ollama deletes the model
|
|
251
|
+
sdl sync <model-name> --copy # full copy; independent of Ollama
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Copy mode creates its temporary naming alias on Ollama's filesystem when it can, and otherwise uses a symbolic link in StudioLink's own directory. Symbolic-link mode requires permission to create symlinks on Windows (Developer Mode).
|
|
255
|
+
|
|
256
|
+
### Deleted a model in Ollama but disk space wasn't freed
|
|
257
|
+
Both LM Studio imports and StudioLink staging aliases can keep a deleted Ollama blob alive. Run `sdl prune --dry-run` to preview cleanup, then `sdl prune` to remove the obsolete managed files. Untracked LM Studio files may still hold links and need separate inspection.
|
|
258
|
+
|
|
259
|
+
### LM Studio import fails
|
|
260
|
+
Run `sdl doctor` to verify:
|
|
261
|
+
- LM Studio is installed
|
|
262
|
+
- `lms` CLI is in PATH
|
|
263
|
+
- Import directories are writable
|
|
264
|
+
|
|
265
|
+
## Design Notes
|
|
266
|
+
|
|
267
|
+
- **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
|
|
268
|
+
- **Hard links when possible** - Space-efficient, creates references rather than copies
|
|
269
|
+
- **No silent fallbacks** - An explicit mode flag never falls back; it fails with a hint. Without a flag, sync prints the mode it picked and why
|
|
270
|
+
- **State persistence** - Tracks and verifies actual imports to avoid redundant operations; state is written atomically and corrupt records are skipped. Verified existing files can restore lost state.
|
|
271
|
+
- **Copy deduplication** - Tags with identical weights share one destination copy through hard links when the destination filesystem supports them.
|
|
272
|
+
- **Dry runs** - Preview sync actions without replacing aliases or invoking an import.
|
|
273
|
+
- **Prune over leak** - Obsolete tracked destinations and orphaned aliases are cleaned up with `sdl prune` instead of pinning disk space forever; symbolic-link dependencies are retained
|
|
274
|
+
- **Supported bundles** - Any number of Ollama models can be synced; each manifest may contain one primary model GGUF and at most one projector GGUF
|
|
275
|
+
- **Explicit limitations** - Manifests with multiple primary models/projectors or Ollama adapter, draft, or tensor artifacts are reported as unsupported rather than partially imported
|
|
276
|
+
- **CLI-only** - No GUI, designed for automation and scripting
|
|
277
|
+
|
|
278
|
+
## License
|
|
279
|
+
|
|
280
|
+
MIT License - See [LICENSE](LICENSE) for details.
|
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
[build-system]
|
|
2
|
-
requires = ["setuptools>=
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
3
|
build-backend = "setuptools.build_meta"
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "studiolink"
|
|
7
|
-
|
|
7
|
+
dynamic = ["version"]
|
|
8
8
|
description = "Sync Ollama-downloaded GGUF models into LM Studio."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.12"
|
|
11
|
-
license =
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
12
13
|
authors = [
|
|
13
14
|
{ name = "StudioLink contributors" }
|
|
14
15
|
]
|
|
@@ -17,15 +18,20 @@ classifiers = [
|
|
|
17
18
|
"Development Status :: 3 - Alpha",
|
|
18
19
|
"Environment :: Console",
|
|
19
20
|
"Intended Audience :: End Users/Desktop",
|
|
20
|
-
"License :: OSI Approved :: MIT License",
|
|
21
21
|
"Programming Language :: Python :: 3",
|
|
22
22
|
"Programming Language :: Python :: 3.12",
|
|
23
23
|
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Programming Language :: Python :: 3.14",
|
|
24
25
|
]
|
|
25
26
|
dependencies = []
|
|
26
27
|
|
|
27
28
|
[project.optional-dependencies]
|
|
28
|
-
dev = [
|
|
29
|
+
dev = [
|
|
30
|
+
"build>=1.2",
|
|
31
|
+
"pyright>=1.1.390",
|
|
32
|
+
"pytest>=8.0",
|
|
33
|
+
"ruff>=0.9",
|
|
34
|
+
]
|
|
29
35
|
|
|
30
36
|
[project.urls]
|
|
31
37
|
Homepage = "https://github.com/ensevengg/StudioLink"
|
|
@@ -37,8 +43,23 @@ sdl = "studiolink.cli:main"
|
|
|
37
43
|
[tool.setuptools]
|
|
38
44
|
package-dir = {"" = "src"}
|
|
39
45
|
|
|
46
|
+
[tool.setuptools.dynamic]
|
|
47
|
+
version = {attr = "studiolink.__version__"}
|
|
48
|
+
|
|
40
49
|
[tool.setuptools.packages.find]
|
|
41
50
|
where = ["src"]
|
|
42
51
|
|
|
43
52
|
[tool.pytest.ini_options]
|
|
44
53
|
testpaths = ["tests"]
|
|
54
|
+
|
|
55
|
+
[tool.ruff]
|
|
56
|
+
target-version = "py312"
|
|
57
|
+
line-length = 88
|
|
58
|
+
|
|
59
|
+
[tool.ruff.lint]
|
|
60
|
+
select = ["E4", "E7", "E9", "F", "I"]
|
|
61
|
+
|
|
62
|
+
[tool.pyright]
|
|
63
|
+
include = ["src"]
|
|
64
|
+
pythonVersion = "3.12"
|
|
65
|
+
typeCheckingMode = "basic"
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
[egg_info]
|
|
2
|
-
tag_build =
|
|
3
|
-
tag_date = 0
|
|
4
|
-
|
|
1
|
+
[egg_info]
|
|
2
|
+
tag_build =
|
|
3
|
+
tag_date = 0
|
|
4
|
+
|