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
26 changes: 14 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ StudioLink is a Python CLI tool that bridges Ollama and LM Studio. It treats Oll

## Features

- 🔍 **Scan** - Discover all GGUF models available in your Ollama library
- 🔍 **Scan** - Discover all GGUF models and supported vision projectors in your Ollama library
- 🔄 **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
Expand Down Expand Up @@ -113,7 +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
- `--direct` - Import a single-artifact Ollama blob directly without a human-readable alias; model-plus-projector bundles require aliases

### `sdl status`
Show discovered models and their sync state.
Expand Down Expand Up @@ -196,9 +196,9 @@ When scanning or checking status, models can have these states:

| State | Description | Action Required |
|-------|-------------|-----------------|
| **ready** | Model blob exists and has valid GGUF header | Ready to sync |
| **stale** | Manifest exists but blob is missing | Run `ollama pull <model>` to restore |
| **invalid** | Blob exists but missing GGUF magic bytes | Model may be corrupted |
| **ready** | Every required model/projector blob exists and has a valid GGUF header | Ready to sync |
| **stale** | A required model/projector blob is missing | Run `ollama pull <model>` to restore |
| **invalid** | An artifact is malformed or the manifest uses an unsupported artifact combination | Inspect the reported issues |
| **synced** | Already imported into LM Studio | No action needed |
| **pending** | Ready but not yet synced | Run `sdl sync` |

Expand All @@ -217,13 +217,13 @@ Default paths are platform-aware; every one can be overridden with an environmen
## How It Works

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 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 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
2. **Artifact Resolution** - Locates the primary model and optional projector GGUF in Ollama's content-addressed blob directory
3. **Validation** - Verifies every required artifact has a valid digest, exists, and starts with GGUF magic bytes
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 so the state and LM Studio directories may live on other volumes
5. **LM Studio Import** - Uses one `lms import` call per artifact, placing each model/projector pair in the same digest-isolated repository so a re-pull cannot leave LM Studio choosing an older projector
6. **State Tracking** - Saves resumable per-artifact sync records to schema-v2 `~/.studiolink/state.json`; schema-v1 records remain readable
7. **Reconciliation** - Status and sync verify every expected target and confirm projector bundles through `lms ls --json`
8. **Pruning** - Pruning is blocked after unavailable or incomplete Ollama scans and preserves all aliases required by symbolic or partial imports

## Troubleshooting

Expand Down Expand Up @@ -258,6 +258,8 @@ Run `sdl doctor` to verify:
- **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
- **Safe pruning** - Orphaned aliases are cleaned up only after a complete source scan; symbolic-link dependencies are retained
- **Supported bundles** - Any number of Ollama models can be synced; each manifest may contain one primary model GGUF and at most one projector GGUF
- **Explicit limitations** - Manifests with multiple primary models/projectors or Ollama adapter, draft, or tensor artifacts are reported as unsupported rather than partially imported
- **CLI-only** - No GUI, designed for automation and scripting

## License
Expand Down
146 changes: 146 additions & 0 deletions docs/research/multi-artifact-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
# Multi-artifact Ollama model validation

**Date:** 2026-08-31
**Status:** Phase 0 complete; proceed with a constrained model + projector implementation

## Decision

StudioLink can safely support an Ollama manifest containing exactly:

- one `application/vnd.ollama.image.model` GGUF; and
- zero or one `application/vnd.ollama.image.projector` GGUF.

Both files must be imported into the same LM Studio `user/repo` directory. The projector alias must start with `mmproj-` and end in `.gguf`. A digest-keyed suffix is accepted by LM Studio, so aliases do not need to retain the original upstream filename.

The first implementation must reject, rather than partially sync:

- manifests with more than one model layer;
- manifests with more than one projector layer;
- manifests containing an Ollama adapter layer;
- manifests containing an Ollama draft layer; and
- manifests whose only model representation is an Ollama tensor layer.

An Ollama draft layer is not part of the importable model bundle. LM Studio treats speculative draft models as separately selected model resources, not as files automatically associated by `lms import`. Phase 1 should report a draft layer as an unsupported semantic extension and block sync instead of claiming exact Ollama-to-LM-Studio parity.

## Primary-source findings

### Ollama manifest semantics

Ollama assigns distinct media types to model, projector, adapter, draft, and tensor data. Its current loader maps model layers to `ModelPath`, projectors to a list of `ProjectorPaths`, adapters to `AdapterPaths`, and a draft layer to `DraftPath`.[^ollama-loader] The current manifest package separately defines tensor and draft media types.[^ollama-layer-types]

These are semantically active layers, not incidental metadata. Ollama passes adapter and projector path lists into its runner, and represents the draft as a separate model path.[^ollama-runner] Ollama's model-list implementation also adds vision capability when at least one projector layer is present.[^ollama-vision]

The public `llava:latest` registry manifest retrieved on 2026-08-31 contains one model layer followed by one projector layer, then license, template, and parameter metadata.[^llava-manifest] An exact copy is retained at [`tests/fixtures/ollama/llava-latest-manifest.json`](../../tests/fixtures/ollama/llava-latest-manifest.json). `bakllava:latest` had the same model-plus-projector shape. By contrast, `qwen3-vl:latest` used one unified model layer and no projector, confirming that projector support must be conditional rather than assumed for every vision model.

### LM Studio import semantics

The current `lms import` interface accepts one file path per invocation.[^lms-import-source] It constructs the destination as:

```text
<models folder>/<user>/<repo>/<source basename>
```

and preserves that basename for copy, hard-link, and symbolic-link imports.[^lms-target-source] The official CLI documentation likewise describes importing one local model file and provides no batch or artifact-role option.[^lms-import-docs]

LM Studio's documented speculative-decoding interface selects a separate draft model resource. It does not document automatic association of a bundled draft file.[^lmstudio-draft]

No current LM Studio documentation or `lms load --help` option exposes an Ollama-style LoRA/adapter association. `lms import` can place an arbitrary file, but placement alone is not evidence that LM Studio can apply an Ollama adapter to its base model. Adapter support is therefore outside the safe initial scope.

## End-to-end validation

Validation used:

- LM Studio `0.4.23+1`;
- `lms` commit `07b7252d6de26a3a58c1bb80ed7e75a2b17f5eb6`;
- the installed Ministral 3 3B GGUF and its projector; and
- temporary hard links, so no model bytes were copied and no model was loaded.

Temporary aliases were given the planned StudioLink naming shape:

```text
ministral-3-3b-validation-deadbeef.gguf
mmproj-ministral-3-3b-validation-cafebabe.gguf
```

Each alias was imported separately with:

```text
lms import <alias> --yes --user-repo studiolink-validation/mmproj-pair --hard-link
```

After both imports, `lms ls --json` returned exactly one inventory entry:

```json
{
"type": "llm",
"modelKey": "mmproj-pair",
"publisher": "studiolink-validation",
"path": "studiolink-validation/mmproj-pair/ministral-3-3b-validation-deadbeef.gguf",
"sizeBytes": 2986795328,
"architecture": "mistral3",
"vision": true
}
```

The reported size was exactly the base file plus the projector file. The installed LM Studio index identified the `mmproj-...gguf` file as the model's `visionAdapter`. This confirms all of the assumptions needed for one-projector support:

1. separate `lms import` calls can build one logical model bundle;
2. same-directory placement is sufficient;
3. an `mmproj-` prefix is recognized;
4. digest-keyed renamed files remain associated; and
5. `lms ls --json` is a viable public reconciliation seam for the resulting model.

### Multiple-projector negative test

A second reversible experiment imported one model and two `mmproj-*.gguf` files into the same repository. LM Studio returned one vision model but indexed only one projector:

```json
{
"entryPoint": "ministral-multi-validation.gguf",
"visionAdapter": "mmproj-ministral-multi-two.gguf",
"allFiles": [
"ministral-multi-validation.gguf",
"mmproj-ministral-multi-two.gguf"
]
}
```

The other projector was ignored. The public inventory did not explain or expose the ambiguity. StudioLink must therefore reject multiple projectors until LM Studio provides a documented selection mechanism.

All temporary aliases, imported targets, and resulting inventory entries were removed after validation.

## Supported-layer matrix

| Ollama layer | Initial handling | Reason |
|---|---|---|
| `image.model` | Import; exactly one required | Confirmed GGUF entry point |
| `image.projector` | Import when exactly one; `mmproj-` alias | Confirmed as LM Studio `visionAdapter` |
| Second projector | Reject model | LM Studio silently selected only one |
| `image.adapter` | Reject model | Semantically required by Ollama; no documented LM Studio association seam |
| `image.draft` | Reject model | LM Studio selects draft models separately; `lms import` cannot preserve the bundle relationship |
| `image.tensor` | Reject model | Not a standalone GGUF import supported by `lms import` |
| template/system/params/license/config | Do not import as artifacts | Manifest metadata, not LM Studio model files |

## Consequences for Phase 1

1. Add artifacts without changing the user-facing model selection seam.
2. Treat model and projector as required artifacts for readiness and sync.
3. Preserve the existing primary model alias naming; prefix projector aliases with `mmproj-`.
4. Import both into the same `user_repo` using separate CLI calls.
5. Do not allow `--direct` for projector bundles because the opaque blob basename loses the required `mmproj-` role marker.
6. Do not claim support for adapters, drafts, tensor-only manifests, or multiple projectors.
7. Add `lms ls --json` inventory parsing before relying on inferred destination paths for multi-artifact reconciliation.

## Remaining uncertainty

The validation covers current GGUF model-plus-projector bundles on LM Studio 0.4.23. LM Studio's projector pairing rule is observable but not documented as a stable interface. StudioLink should retain integration tests around inventory behavior and fail clearly if a future LM Studio version stops reporting the imported bundle as vision-capable.

[^ollama-loader]: Ollama source, [`server/images.go` lines 717–740](https://github.com/ollama/ollama/blob/f96e7aa0513b9973a0ccc71be414c2ecb9d65b1a/server/images.go#L717-L740).
[^ollama-layer-types]: Ollama source, [`manifest/layer.go` lines 20–24](https://github.com/ollama/ollama/blob/f96e7aa0513b9973a0ccc71be414c2ecb9d65b1a/manifest/layer.go#L20-L24).
[^ollama-runner]: Ollama source, [`server/sched.go` runner construction](https://github.com/ollama/ollama/blob/f96e7aa0513b9973a0ccc71be414c2ecb9d65b1a/server/sched.go#L577) and [`server/routes.go` draft model path](https://github.com/ollama/ollama/blob/f96e7aa0513b9973a0ccc71be414c2ecb9d65b1a/server/routes.go#L2368).
[^ollama-vision]: Ollama source, [`server/model_list_cache.go` lines 341–391](https://github.com/ollama/ollama/blob/f96e7aa0513b9973a0ccc71be414c2ecb9d65b1a/server/model_list_cache.go#L341-L391).
[^llava-manifest]: Ollama registry, [`library/llava:latest` manifest](https://registry.ollama.ai/v2/library/llava/manifests/latest), retrieved 2026-08-31.
[^lms-import-source]: LM Studio CLI source, [single `<file-path>` argument](https://github.com/lmstudio-ai/lms/blob/07b7252d6de26a3a58c1bb80ed7e75a2b17f5eb6/src/subcommands/importCmd.ts#L71-L74).
[^lms-target-source]: LM Studio CLI source, [destination path construction](https://github.com/lmstudio-ai/lms/blob/07b7252d6de26a3a58c1bb80ed7e75a2b17f5eb6/src/subcommands/importCmd.ts#L176) and [hard-link implementation](https://github.com/lmstudio-ai/lms/blob/07b7252d6de26a3a58c1bb80ed7e75a2b17f5eb6/src/subcommands/importCmd.ts#L247-L252).
[^lms-import-docs]: LM Studio documentation, [`lms import`](https://lmstudio.ai/docs/cli/local-models/import).
[^lmstudio-draft]: LM Studio documentation, [Speculative Decoding](https://lmstudio.ai/docs/app/advanced/speculative-decoding).
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.1"
__version__ = "0.3.0"
19 changes: 19 additions & 0 deletions src/studiolink/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,13 @@ def run_scan(args: argparse.Namespace, service: StudioLinkService) -> int:
for model in models:
print(f"- {model.canonical_name} [{model.readiness.value}]")
print(f" blob: {model.blob_path or 'missing'}")
for artifact in model.artifacts:
if artifact.role.value != "model":
print(
f" {artifact.role.value}: "
f"{artifact.blob_path or 'missing'} "
f"[{artifact.readiness.value}]"
)
if model.issues:
print(f" issues: {'; '.join(model.issues)}")
return 0
Expand Down Expand Up @@ -403,6 +410,18 @@ def _model_to_json(model: object) -> dict[str, object]:
"gguf_valid": getattr(model, "gguf_valid"),
"issues": list(getattr(model, "issues")),
"user_repo": getattr(model, "user_repo"),
"artifacts": [
{
"role": artifact.role.value,
"media_type": artifact.media_type,
"digest": artifact.digest,
"blob_path": (str(artifact.blob_path) if artifact.blob_path else None),
"readiness": artifact.readiness.value,
"gguf_valid": artifact.gguf_valid,
"issues": list(artifact.issues),
}
for artifact in getattr(model, "artifacts", ())
],
}


Expand Down
49 changes: 48 additions & 1 deletion src/studiolink/lmstudio_adapter.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
from __future__ import annotations

import json
import subprocess

from studiolink.config import StudioLinkConfig
from studiolink.models import ImportResult, LinkMode
from studiolink.models import ImportResult, LinkMode, LMStudioModel

DEFAULT_TIMEOUT = 60
# Importing with --copy moves multi-GB GGUF files; give it an hour instead of
Expand Down Expand Up @@ -62,6 +63,52 @@ def get_import_capabilities(self) -> set[LinkMode]:
capabilities.add(LinkMode.SYMBOLIC_LINK)
return capabilities

def list_models(self) -> tuple[LMStudioModel, ...]:
command = [str(self.config.lms_exe), "ls", "--json"]
try:
result = self._run(command, check=True)
except subprocess.CalledProcessError as exc:
raise LMStudioError(
f"Failed to list LM Studio models: {exc.stderr}",
exc.cmd,
exc.returncode,
exc.stderr,
) from exc
try:
payload = json.loads(result.stdout)
except json.JSONDecodeError as exc:
raise LMStudioError(
f"LM Studio returned invalid model inventory JSON: {exc}",
command,
result.returncode,
result.stderr,
) from exc
if not isinstance(payload, list):
raise LMStudioError(
"LM Studio model inventory was not a JSON list",
command,
result.returncode,
result.stderr,
)
inventory: list[LMStudioModel] = []
for item in payload:
if not isinstance(item, dict):
raise LMStudioError(
"LM Studio model inventory contained an invalid entry",
command,
result.returncode,
result.stderr,
)
inventory.append(
LMStudioModel(
model_key=str(item.get("modelKey", "")),
path=str(item.get("path", "")),
vision=item.get("vision") is True,
model_type=str(item.get("type", "")),
)
)
return tuple(inventory)

def import_model(
self,
source_path: str,
Expand Down
Loading
Loading