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.
Files changed (55) hide show
  1. studiolink-0.3.0/PKG-INFO +306 -0
  2. studiolink-0.3.0/README.md +280 -0
  3. {studiolink-0.2.0 → studiolink-0.3.0}/pyproject.toml +26 -5
  4. {studiolink-0.2.0 → studiolink-0.3.0}/setup.cfg +4 -4
  5. {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink/__init__.py +1 -1
  6. {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink/cli.py +68 -16
  7. studiolink-0.3.0/src/studiolink/config.py +183 -0
  8. studiolink-0.3.0/src/studiolink/files.py +403 -0
  9. studiolink-0.3.0/src/studiolink/lmstudio_adapter.py +211 -0
  10. studiolink-0.3.0/src/studiolink/models.py +457 -0
  11. studiolink-0.3.0/src/studiolink/ollama_adapter.py +516 -0
  12. {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink/ports.py +20 -3
  13. studiolink-0.3.0/src/studiolink/service.py +604 -0
  14. studiolink-0.3.0/src/studiolink/state.py +184 -0
  15. studiolink-0.3.0/src/studiolink/syncer.py +657 -0
  16. studiolink-0.3.0/src/studiolink/transactions.py +193 -0
  17. studiolink-0.3.0/src/studiolink.egg-info/PKG-INFO +306 -0
  18. {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink.egg-info/SOURCES.txt +11 -0
  19. studiolink-0.3.0/src/studiolink.egg-info/requires.txt +6 -0
  20. {studiolink-0.2.0 → studiolink-0.3.0}/tests/test_cli.py +92 -11
  21. studiolink-0.3.0/tests/test_config.py +236 -0
  22. studiolink-0.3.0/tests/test_failure_paths.py +203 -0
  23. studiolink-0.3.0/tests/test_import_lifecycle.py +339 -0
  24. studiolink-0.3.0/tests/test_import_transactions.py +146 -0
  25. studiolink-0.3.0/tests/test_lifecycle_sequences.py +74 -0
  26. studiolink-0.3.0/tests/test_lmstudio_adapter.py +144 -0
  27. {studiolink-0.2.0 → studiolink-0.3.0}/tests/test_models.py +82 -9
  28. studiolink-0.3.0/tests/test_ollama_adapter.py +332 -0
  29. studiolink-0.3.0/tests/test_ollama_manifests_v2.py +373 -0
  30. studiolink-0.3.0/tests/test_real_lms.py +215 -0
  31. studiolink-0.3.0/tests/test_release_review.py +417 -0
  32. studiolink-0.3.0/tests/test_review_fixes.py +205 -0
  33. studiolink-0.3.0/tests/test_service.py +643 -0
  34. {studiolink-0.2.0 → studiolink-0.3.0}/tests/test_state.py +78 -8
  35. studiolink-0.3.0/tests/test_syncer.py +1013 -0
  36. studiolink-0.2.0/PKG-INFO +0 -304
  37. studiolink-0.2.0/README.md +0 -260
  38. studiolink-0.2.0/src/studiolink/config.py +0 -71
  39. studiolink-0.2.0/src/studiolink/lmstudio_adapter.py +0 -125
  40. studiolink-0.2.0/src/studiolink/models.py +0 -194
  41. studiolink-0.2.0/src/studiolink/ollama_adapter.py +0 -164
  42. studiolink-0.2.0/src/studiolink/service.py +0 -343
  43. studiolink-0.2.0/src/studiolink/state.py +0 -91
  44. studiolink-0.2.0/src/studiolink/syncer.py +0 -215
  45. studiolink-0.2.0/src/studiolink.egg-info/PKG-INFO +0 -304
  46. studiolink-0.2.0/src/studiolink.egg-info/requires.txt +0 -3
  47. studiolink-0.2.0/tests/test_config.py +0 -91
  48. studiolink-0.2.0/tests/test_ollama_adapter.py +0 -149
  49. studiolink-0.2.0/tests/test_service.py +0 -247
  50. studiolink-0.2.0/tests/test_syncer.py +0 -284
  51. {studiolink-0.2.0 → studiolink-0.3.0}/LICENSE +0 -0
  52. {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink/__main__.py +1 -1
  53. {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink.egg-info/dependency_links.txt +0 -0
  54. {studiolink-0.2.0 → studiolink-0.3.0}/src/studiolink.egg-info/entry_points.txt +0 -0
  55. {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>=68"]
2
+ requires = ["setuptools>=77"]
3
3
  build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "studiolink"
7
- version = "0.2.0"
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 = { file = "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 = ["pytest>=8.0"]
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
+
@@ -2,4 +2,4 @@
2
2
 
3
3
  __all__ = ["__version__"]
4
4
 
5
- __version__ = "0.2.0"
5
+ __version__ = "0.3.0"