diff --git a/README.md b/README.md index 6375dba..cef8326 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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. @@ -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 ` 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 ` 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` | @@ -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 @@ -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 diff --git a/docs/research/multi-artifact-validation.md b/docs/research/multi-artifact-validation.md new file mode 100644 index 0000000..e2add03 --- /dev/null +++ b/docs/research/multi-artifact-validation.md @@ -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 +/// +``` + +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 --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 `` 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). diff --git a/src/studiolink/__init__.py b/src/studiolink/__init__.py index 0a93a73..8fe341e 100644 --- a/src/studiolink/__init__.py +++ b/src/studiolink/__init__.py @@ -2,4 +2,4 @@ __all__ = ["__version__"] -__version__ = "0.2.1" +__version__ = "0.3.0" diff --git a/src/studiolink/cli.py b/src/studiolink/cli.py index 4119404..6efc2ab 100644 --- a/src/studiolink/cli.py +++ b/src/studiolink/cli.py @@ -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 @@ -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", ()) + ], } diff --git a/src/studiolink/lmstudio_adapter.py b/src/studiolink/lmstudio_adapter.py index 216534f..fe32d02 100644 --- a/src/studiolink/lmstudio_adapter.py +++ b/src/studiolink/lmstudio_adapter.py @@ -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 @@ -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, diff --git a/src/studiolink/models.py b/src/studiolink/models.py index f8b5b04..73f065e 100644 --- a/src/studiolink/models.py +++ b/src/studiolink/models.py @@ -31,6 +31,32 @@ class ModelReadiness(StrEnum): INVALID = "invalid" +class ArtifactRole(StrEnum): + MODEL = "model" + PROJECTOR = "projector" + + +@dataclass(slots=True, frozen=True) +class OllamaArtifact: + role: ArtifactRole + media_type: str + digest: str | None + blob_path: Path | None + declared_size: int | None + blob_size: int | None + gguf_valid: bool + manifest_index: int + issues: tuple[str, ...] = () + + @property + def readiness(self) -> ModelReadiness: + if self.gguf_valid: + return ModelReadiness.READY + if any("blob is missing" in issue for issue in self.issues): + return ModelReadiness.STALE + return ModelReadiness.INVALID + + @dataclass(slots=True, frozen=True) class OllamaModel: canonical_name: str @@ -46,11 +72,25 @@ class OllamaModel: blob_size: int | None gguf_valid: bool issues: tuple[str, ...] = () + artifacts: tuple[OllamaArtifact, ...] = () @property def readiness(self) -> ModelReadiness: if self.gguf_valid: return ModelReadiness.READY + if any("not supported" in issue for issue in self.issues): + return ModelReadiness.INVALID + if self.artifacts: + if any( + artifact.readiness is ModelReadiness.INVALID + for artifact in self.artifacts + ): + return ModelReadiness.INVALID + if any( + artifact.readiness is ModelReadiness.STALE + for artifact in self.artifacts + ): + return ModelReadiness.STALE if any( "blob is missing from the Ollama blob store" in issue for issue in self.issues @@ -76,11 +116,30 @@ def user_repo(self) -> str: repo_parts.append(self.repository.replace("/", "--")) return f"ollama/{'-'.join(repo_parts)}" + @property + def import_user_repo(self) -> str: + if not any( + artifact.role is ArtifactRole.PROJECTOR for artifact in self.artifacts + ): + return self.user_repo + identity = "-".join( + (artifact.digest or "unknown").split(":")[-1][:12] + for artifact in self.artifacts + ) + return f"{self.user_repo}--bundle-{identity}" + @property def import_filename(self) -> str: + return self._import_filename(self.model_digest) + + def artifact_import_filename(self, artifact: OllamaArtifact) -> str: + prefix = "mmproj-" if artifact.role is ArtifactRole.PROJECTOR else "" + return prefix + self._import_filename(artifact.digest) + + def _import_filename(self, digest: str | None) -> str: # Keep the hash portion of the digest so re-pulled models (same name, # new digest) get a distinct alias instead of reusing the stale one. - digest_hash = (self.model_digest or "unknown").split(":")[-1][:12] + digest_hash = (digest or "unknown").split(":")[-1][:12] raw = f"{self.canonical_name}-{digest_hash}" safe = "".join( ch if ch.isalnum() or ch in ("-", "_", ".") else "-" for ch in raw @@ -99,26 +158,20 @@ class OllamaScanReport: @dataclass(slots=True, frozen=True) -class SyncRecord: - canonical_name: str +class SyncedArtifact: + role: ArtifactRole digest: str blob_path: Path import_alias_path: Path - user_repo: str - link_mode: LinkMode - imported_at: datetime imported_model_path: Path | None = None import_command: tuple[str, ...] = field(default_factory=tuple) def to_json(self) -> dict[str, object]: return { - "canonical_name": self.canonical_name, + "role": self.role.value, "digest": self.digest, "blob_path": str(self.blob_path), "import_alias_path": str(self.import_alias_path), - "user_repo": self.user_repo, - "link_mode": self.link_mode.value, - "imported_at": self.imported_at.isoformat(), "imported_model_path": ( None if self.imported_model_path is None @@ -128,18 +181,15 @@ def to_json(self) -> dict[str, object]: } @classmethod - def from_json(cls, payload: dict[str, object]) -> "SyncRecord": + def from_json(cls, payload: dict[str, object]) -> "SyncedArtifact": import_command = payload.get("import_command", []) if not isinstance(import_command, list): raise TypeError("import_command must be a list") return cls( - canonical_name=str(payload["canonical_name"]), + role=ArtifactRole(str(payload["role"])), digest=str(payload["digest"]), blob_path=Path(str(payload["blob_path"])), import_alias_path=Path(str(payload["import_alias_path"])), - user_repo=str(payload["user_repo"]), - link_mode=LinkMode(str(payload["link_mode"])), - imported_at=datetime.fromisoformat(str(payload["imported_at"])), imported_model_path=( Path(str(payload["imported_model_path"])) if payload.get("imported_model_path") @@ -149,17 +199,156 @@ def from_json(cls, payload: dict[str, object]) -> "SyncRecord": ) +@dataclass(slots=True, frozen=True) +class SyncRecord: + canonical_name: str + user_repo: str + link_mode: LinkMode + imported_at: datetime + artifacts: tuple[SyncedArtifact, ...] + vision_confirmed: bool = True + + @property + def primary_artifact(self) -> SyncedArtifact: + return next( + artifact + for artifact in self.artifacts + if artifact.role is ArtifactRole.MODEL + ) + + # Compatibility properties for callers and schema-v1 JSON consumers. + @property + def digest(self) -> str: + return self.primary_artifact.digest + + @property + def blob_path(self) -> Path: + return self.primary_artifact.blob_path + + @property + def import_alias_path(self) -> Path: + return self.primary_artifact.import_alias_path + + @property + def imported_model_path(self) -> Path | None: + return self.primary_artifact.imported_model_path + + @property + def import_command(self) -> tuple[str, ...]: + return self.primary_artifact.import_command + + def to_json(self) -> dict[str, object]: + primary = self.primary_artifact + return { + "canonical_name": self.canonical_name, + "user_repo": self.user_repo, + "link_mode": self.link_mode.value, + "imported_at": self.imported_at.isoformat(), + "artifacts": [artifact.to_json() for artifact in self.artifacts], + "vision_confirmed": self.vision_confirmed, + # Keep the original primary-artifact fields additive for CLI JSON + # consumers while state schema v2 adopts the artifacts collection. + "digest": primary.digest, + "blob_path": str(primary.blob_path), + "import_alias_path": str(primary.import_alias_path), + "imported_model_path": ( + None + if primary.imported_model_path is None + else str(primary.imported_model_path) + ), + "import_command": list(primary.import_command), + } + + @classmethod + def from_json(cls, payload: dict[str, object]) -> "SyncRecord": + artifacts_payload = payload.get("artifacts") + if artifacts_payload is not None: + if not isinstance(artifacts_payload, list): + raise TypeError("artifacts must be a list") + artifacts = tuple( + SyncedArtifact.from_json(item) + for item in artifacts_payload + if isinstance(item, dict) + ) + if len(artifacts) != len(artifacts_payload) or not artifacts: + raise TypeError("artifacts must contain artifact objects") + else: + import_command = payload.get("import_command", []) + if not isinstance(import_command, list): + raise TypeError("import_command must be a list") + artifacts = ( + SyncedArtifact( + role=ArtifactRole.MODEL, + digest=str(payload["digest"]), + blob_path=Path(str(payload["blob_path"])), + import_alias_path=Path(str(payload["import_alias_path"])), + imported_model_path=( + Path(str(payload["imported_model_path"])) + if payload.get("imported_model_path") + else None + ), + import_command=tuple(str(item) for item in import_command), + ), + ) + if sum(artifact.role is ArtifactRole.MODEL for artifact in artifacts) != 1: + raise ValueError("sync record must contain exactly one model artifact") + if sum(artifact.role is ArtifactRole.PROJECTOR for artifact in artifacts) > 1: + raise ValueError("sync record cannot contain multiple projector artifacts") + return cls( + canonical_name=str(payload["canonical_name"]), + user_repo=str(payload["user_repo"]), + link_mode=LinkMode(str(payload["link_mode"])), + imported_at=datetime.fromisoformat(str(payload["imported_at"])), + artifacts=artifacts, + vision_confirmed=( + payload.get("vision_confirmed") is True + if any( + artifact.role is ArtifactRole.PROJECTOR for artifact in artifacts + ) + else True + ), + ) + + def is_synced( model: OllamaModel, record: SyncRecord | None, *, expected_target: Path | None = None, ) -> bool: - """Check if state and the imported LM Studio file match the model.""" - if record is None or record.digest != model.model_digest: + """Check if state and every imported LM Studio artifact match the model.""" + if record is None: + return False + expected = ( + tuple((artifact.role, artifact.digest) for artifact in model.artifacts) + if model.artifacts + else ((ArtifactRole.MODEL, model.model_digest),) + ) + actual = tuple((artifact.role, artifact.digest) for artifact in record.artifacts) + if actual != expected: return False - target = record.imported_model_path or expected_target - return target.is_file() if target is not None else True + if any(role is ArtifactRole.PROJECTOR for role, _ in expected): + if not record.vision_confirmed: + return False + for artifact in record.artifacts: + target = artifact.imported_model_path + if artifact.role is ArtifactRole.MODEL and target is None: + target = expected_target + if target is None: + if artifact.role is ArtifactRole.PROJECTOR: + return False + continue + if not target.is_file(): + return False + return True + + +@dataclass(slots=True, frozen=True) +class LMStudioModel: + model_key: str + path: str + vision: bool + model_type: str @dataclass(slots=True, frozen=True) diff --git a/src/studiolink/ollama_adapter.py b/src/studiolink/ollama_adapter.py index 906d891..f5783f8 100644 --- a/src/studiolink/ollama_adapter.py +++ b/src/studiolink/ollama_adapter.py @@ -6,9 +6,20 @@ from pathlib import Path from studiolink.config import StudioLinkConfig -from studiolink.models import OllamaModel, OllamaScanReport +from studiolink.models import ( + ArtifactRole, + OllamaArtifact, + OllamaModel, + OllamaScanReport, +) MODEL_MEDIA_TYPE = "application/vnd.ollama.image.model" +PROJECTOR_MEDIA_TYPE = "application/vnd.ollama.image.projector" +UNSUPPORTED_MEDIA_TYPES = { + "application/vnd.ollama.image.adapter": "adapter", + "application/vnd.ollama.image.draft": "draft", + "application/vnd.ollama.image.tensor": "tensor", +} GGUF_MAGIC = b"GGUF" SHA256_DIGEST_PATTERN = re.compile(r"^sha256:[0-9a-fA-F]{64}$") @@ -119,44 +130,42 @@ def _parse_manifest(self, manifest_path: Path) -> OllamaModel | None: issues.append("manifest layers must be a list") layers = [] - model_layer = None - for layer in layers: - if isinstance(layer, dict) and layer.get("mediaType") == MODEL_MEDIA_TYPE: - model_layer = layer - break - - model_digest = None - blob_path = None - declared_size = None - blob_size = None - gguf_valid = False + artifact_layers: list[tuple[int, dict[str, object], ArtifactRole]] = [] + unsupported_roles: set[str] = set() + for index, layer in enumerate(layers): + if not isinstance(layer, dict): + continue + media_type = layer.get("mediaType") + if media_type == MODEL_MEDIA_TYPE: + artifact_layers.append((index, layer, ArtifactRole.MODEL)) + elif media_type == PROJECTOR_MEDIA_TYPE: + artifact_layers.append((index, layer, ArtifactRole.PROJECTOR)) + elif isinstance(media_type, str) and media_type in UNSUPPORTED_MEDIA_TYPES: + unsupported_roles.add(UNSUPPORTED_MEDIA_TYPES[media_type]) - if model_layer is None: + model_count = sum(role is ArtifactRole.MODEL for _, _, role in artifact_layers) + projector_count = sum( + role is ArtifactRole.PROJECTOR for _, _, role in artifact_layers + ) + if model_count == 0: issues.append("missing Ollama model layer") - else: - model_digest = str(model_layer.get("digest", "")).strip() or None - declared_size = self._as_int(model_layer.get("size")) - if model_digest is None: - issues.append("model layer is missing a digest") - elif SHA256_DIGEST_PATTERN.fullmatch(model_digest) is None: - issues.append("model layer has an invalid SHA-256 digest") - else: - blob_path = self.config.ollama_blobs_dir / model_digest.replace( - ":", "-" - ) - logger.debug("Looking for blob: %s", blob_path) - if not blob_path.exists(): - logger.debug("Blob not found: %s", blob_path) - issues.append("model blob is missing from the Ollama blob store") - else: - blob_size = blob_path.stat().st_size - logger.debug("Found blob: %s (size=%d bytes)", blob_path, blob_size) - if self._has_gguf_header(blob_path): - logger.debug("Blob has valid GGUF header: %s", blob_path) - gguf_valid = True - else: - logger.debug("Blob missing GGUF magic bytes: %s", blob_path) - issues.append("blob does not start with GGUF magic bytes") + elif model_count > 1: + issues.append("multiple Ollama model layers are not supported") + if projector_count > 1: + issues.append("multiple Ollama projector layers are not supported") + for role in sorted(unsupported_roles): + issues.append(f"Ollama {role} layers are not supported") + + artifacts = tuple( + self._parse_artifact(layer, role, index) + for index, layer, role in artifact_layers + ) + for artifact in artifacts: + issues.extend(artifact.issues) + primary = next( + (artifact for artifact in artifacts if artifact.role is ArtifactRole.MODEL), + None, + ) canonical_name = self._canonical_name(registry, namespace, repository, tag) fully_qualified_name = f"{registry}/{namespace}/{repository}:{tag}" @@ -168,11 +177,58 @@ def _parse_manifest(self, manifest_path: Path) -> OllamaModel | None: repository=repository, tag=tag, manifest_path=manifest_path, - model_digest=model_digest, + model_digest=primary.digest if primary else None, + blob_path=primary.blob_path if primary else None, + declared_size=primary.declared_size if primary else None, + blob_size=primary.blob_size if primary else None, + gguf_valid=( + bool(artifacts) + and model_count == 1 + and projector_count <= 1 + and not unsupported_roles + and all(artifact.gguf_valid for artifact in artifacts) + ), + issues=tuple(issues), + artifacts=artifacts, + ) + + def _parse_artifact( + self, layer: dict[str, object], role: ArtifactRole, manifest_index: int + ) -> OllamaArtifact: + label = role.value + digest = str(layer.get("digest", "")).strip() or None + declared_size = self._as_int(layer.get("size")) + blob_path = None + blob_size = None + gguf_valid = False + issues: list[str] = [] + if digest is None: + issues.append(f"{label} layer is missing a digest") + elif SHA256_DIGEST_PATTERN.fullmatch(digest) is None: + issues.append(f"{label} layer has an invalid SHA-256 digest") + else: + blob_path = self.config.ollama_blobs_dir / digest.replace(":", "-") + logger.debug("Looking for %s blob: %s", label, blob_path) + if not blob_path.exists(): + issues.append(f"{label} blob is missing from the Ollama blob store") + else: + blob_size = blob_path.stat().st_size + gguf_valid = self._has_gguf_header(blob_path) + if not gguf_valid: + issues.append( + "blob does not start with GGUF magic bytes" + if role is ArtifactRole.MODEL + else f"{label} blob does not start with GGUF magic bytes" + ) + return OllamaArtifact( + role=role, + media_type=str(layer.get("mediaType", "")), + digest=digest, blob_path=blob_path, declared_size=declared_size, blob_size=blob_size, gguf_valid=gguf_valid, + manifest_index=manifest_index, issues=tuple(issues), ) diff --git a/src/studiolink/ports.py b/src/studiolink/ports.py index 1704185..6272d9c 100644 --- a/src/studiolink/ports.py +++ b/src/studiolink/ports.py @@ -2,7 +2,13 @@ from typing import Protocol, runtime_checkable -from studiolink.models import ImportResult, LinkMode, OllamaModel, OllamaScanReport +from studiolink.models import ( + ImportResult, + LinkMode, + LMStudioModel, + OllamaModel, + OllamaScanReport, +) @runtime_checkable @@ -18,6 +24,8 @@ def get_version(self) -> str | None: ... def get_import_capabilities(self) -> set[LinkMode]: ... + def list_models(self) -> tuple[LMStudioModel, ...]: ... + def import_model( self, source_path: str, diff --git a/src/studiolink/service.py b/src/studiolink/service.py index 55fd20d..b736c48 100644 --- a/src/studiolink/service.py +++ b/src/studiolink/service.py @@ -3,14 +3,17 @@ import logging import os from dataclasses import dataclass +from pathlib import Path from typing import TYPE_CHECKING from studiolink.config import StudioLinkConfig from studiolink.lmstudio_adapter import LMStudioAdapter from studiolink.models import ( + ArtifactRole, DoctorCheck, ImportMode, LinkMode, + LMStudioModel, ModelReadiness, OllamaModel, OllamaScanReport, @@ -74,10 +77,23 @@ def scan_report(self) -> OllamaScanReport: def status(self) -> list[StatusEntry]: models = self.scan() records = self.state.get_all_records() + needs_inventory = any( + model.readiness is ModelReadiness.READY + and any( + artifact.role is ArtifactRole.PROJECTOR for artifact in model.artifacts + ) + and records.get(model.canonical_name) is not None + for model in models + ) + inventory = self.lmstudio.list_models() if needs_inventory else None return [ StatusEntry( model=model, - synced=self._record_is_synced(model, records.get(model.canonical_name)), + synced=self._record_is_synced( + model, + records.get(model.canonical_name), + inventory=inventory, + ), sync_record=records.get(model.canonical_name), ) for model in models @@ -130,11 +146,20 @@ def prune(self, *, dry_run: bool = False) -> PruneReport: raise RuntimeError(f"Ollama manifest scan was incomplete: {details}") models = list(scan.models) - expected: dict[str, OllamaModel] = { - model.import_filename: model - for model in models - if model.readiness is ModelReadiness.READY and model.blob_path is not None - } + expected: dict[str, Path] = {} + for model in models: + if model.readiness is not ModelReadiness.READY: + continue + if model.artifacts: + expected.update( + { + model.artifact_import_filename(artifact): artifact.blob_path + for artifact in model.artifacts + if artifact.blob_path is not None + } + ) + elif model.blob_path is not None: + expected[model.import_filename] = model.blob_path records = self.state.get_all_records() unready_names = { model.canonical_name @@ -142,9 +167,10 @@ def prune(self, *, dry_run: bool = False) -> PruneReport: if model.readiness is not ModelReadiness.READY } protected_aliases = { - record.import_alias_path + artifact.import_alias_path for name, record in records.items() if record.link_mode is LinkMode.SYMBOLIC_LINK or name in unready_names + for artifact in record.artifacts } alias_results: list[PruneResult] = [] @@ -156,12 +182,12 @@ def prune(self, *, dry_run: bool = False) -> PruneReport: if path in protected_aliases: logger.debug("Preserving required import alias: %s", path) continue - model = expected.get(path.name) - if model is not None and same_file(path, model.blob_path or path): + expected_blob = expected.get(path.name) + if expected_blob is not None and same_file(path, expected_blob): continue reason = ( "alias no longer points at the current model blob" - if model is not None + if expected_blob is not None else "model no longer present in Ollama (or was re-pulled)" ) try: @@ -347,7 +373,13 @@ def _volume_compatibility_check(self) -> DoctorCheck: ) return DoctorCheck("hard-link volume compatibility", ok, details) - def _record_is_synced(self, model: OllamaModel, record: SyncRecord | None) -> bool: + def _record_is_synced( + self, + model: OllamaModel, + record: SyncRecord | None, + *, + inventory: tuple[LMStudioModel, ...] | None = None, + ) -> bool: expected_target = None if record is not None and record.imported_model_path is None: expected_target = ( @@ -355,7 +387,28 @@ def _record_is_synced(self, model: OllamaModel, record: SyncRecord | None) -> bo / record.user_repo / record.import_alias_path.name ) - return is_synced(model, record, expected_target=expected_target) + if not is_synced(model, record, expected_target=expected_target): + return False + if not any( + artifact.role is ArtifactRole.PROJECTOR for artifact in model.artifacts + ): + return True + if record is None or inventory is None: + return False + primary_target = record.imported_model_path or expected_target + if primary_target is None: + return False + try: + relative_target = primary_target.relative_to( + self.config.lmstudio_models_dir + ).as_posix() + except ValueError: + return False + return any( + item.path.replace("\\", "/").casefold() == relative_target.casefold() + and item.vision + for item in inventory + ) def _select_models( self, discovered: list[OllamaModel], requested_names: list[str] diff --git a/src/studiolink/state.py b/src/studiolink/state.py index 6a91922..3e661f4 100644 --- a/src/studiolink/state.py +++ b/src/studiolink/state.py @@ -63,7 +63,7 @@ def _parse_record(name: str, record_data: object) -> SyncRecord | None: def _save_raw(self, records: Mapping[str, object]) -> None: """Persist raw JSON dict to disk atomically.""" self.path.parent.mkdir(parents=True, exist_ok=True) - payload = json.dumps({"schema_version": 1, "sync_records": records}, indent=2) + payload = json.dumps({"schema_version": 2, "sync_records": records}, indent=2) tmp_path = self.path.parent / (self.path.name + ".tmp") tmp_path.write_text(payload, encoding="utf-8") os.replace(tmp_path, self.path) diff --git a/src/studiolink/syncer.py b/src/studiolink/syncer.py index 4e16a93..03525df 100644 --- a/src/studiolink/syncer.py +++ b/src/studiolink/syncer.py @@ -3,17 +3,21 @@ import logging import os import subprocess +import time from datetime import datetime, timezone from pathlib import Path from studiolink.config import StudioLinkConfig from studiolink.lmstudio_adapter import LMStudioError from studiolink.models import ( + ArtifactRole, ImportMode, ImportResult, LinkMode, ModelReadiness, + OllamaArtifact, OllamaModel, + SyncedArtifact, SyncRecord, SyncResult, is_synced, @@ -23,6 +27,9 @@ logger = logging.getLogger("studiolink") +INVENTORY_ATTEMPTS = 10 +INVENTORY_RETRY_DELAY = 0.5 + def same_file(left: Path, right: Path) -> bool: """Check whether two paths reference the same inode (hard link).""" @@ -94,7 +101,11 @@ def _sync_one( / existing.user_repo / existing.import_alias_path.name ) - if is_synced(model, existing, expected_target=expected_target): + already_synced = is_synced(model, existing, expected_target=expected_target) + has_projector = any( + artifact.role is ArtifactRole.PROJECTOR for artifact in model.artifacts + ) + if already_synced and not has_projector: logger.debug("Model %s is already synced, skipping", model.canonical_name) return SyncResult( model=model, @@ -103,20 +114,16 @@ def _sync_one( record=existing, ) if model.readiness is ModelReadiness.STALE: - logger.debug("Model %s is stale (blob missing)", model.canonical_name) + logger.debug("Model %s has a missing artifact", model.canonical_name) return SyncResult( model=model, status="error", message=( - "model blob is missing from the Ollama blob store; " + "model artifact is missing from the Ollama blob store; " f"run `ollama pull {model.canonical_name}` to restore it" ), ) - if ( - model.readiness is ModelReadiness.INVALID - or model.blob_path is None - or model.model_digest is None - ): + if model.readiness is ModelReadiness.INVALID: logger.debug("Model %s is invalid: %s", model.canonical_name, model.issues) return SyncResult( model=model, @@ -124,89 +131,298 @@ def _sync_one( message="model is not ready for import: " + "; ".join(model.issues or ("unknown error",)), ) - if import_mode is ImportMode.DIRECT: - alias_path = model.blob_path - alias_created = False - logger.debug("Using Ollama blob directly: %s", alias_path) - else: - try: - alias_path, alias_created = self._ensure_import_alias(model, link_mode) - logger.debug( - "Importing model via LM Studio: %s (mode=%s, dry_run=%s)", - alias_path, - link_mode, - dry_run, - ) - except RuntimeError as exc: - logger.debug("Failed to create import alias: %s", exc) + + artifacts = self._model_artifacts(model) + if import_mode is ImportMode.DIRECT and len(artifacts) > 1: + return SyncResult( + model=model, + status="error", + message=( + "--direct is not supported for multi-artifact models; " + "projector imports require an mmproj- alias" + ), + ) + + existing_by_identity = { + (artifact.role, artifact.digest): artifact + for artifact in (existing.artifacts if existing is not None else ()) + } + completed: list[SyncedArtifact] = [] + last_result: ImportResult | None = None + imported_at = ( + existing.imported_at + if existing is not None + else datetime.now(tz=timezone.utc) + ) + + for artifact in artifacts: + if artifact.digest is None or artifact.blob_path is None: return SyncResult( model=model, status="error", - message=str(exc), + message=f"{artifact.role.value} artifact is not importable", + ) + prior = existing_by_identity.get((artifact.role, artifact.digest)) + prior_target = prior.imported_model_path if prior is not None else None + if prior is not None and prior_target is None: + prior_target = ( + self.config.lmstudio_models_dir + / (existing.user_repo if existing else model.import_user_repo) + / prior.import_alias_path.name ) - - import_error: Exception | None = None - import_result: ImportResult | None = None - try: - import_result = self.lmstudio.import_model( - str(alias_path), - user_repo=model.user_repo, - link_mode=link_mode, - dry_run=dry_run, - ) - logger.debug("LM Studio import completed: %s", import_result.return_code) - except (LMStudioError, subprocess.TimeoutExpired) as exc: - # One failing model must not abort the rest of the batch. - logger.debug("LM Studio import failed: %s", exc) - import_error = exc - finally: - should_remove_alias = dry_run or link_mode is LinkMode.COPY if ( - should_remove_alias - and (alias_created or link_mode is LinkMode.COPY) - and alias_path.exists() - and import_mode is not ImportMode.DIRECT + prior is not None + and prior_target is not None + and prior_target.is_file() ): - logger.debug("Cleaning up temporary import alias: %s", alias_path) + completed.append( + SyncedArtifact( + role=prior.role, + digest=prior.digest, + blob_path=prior.blob_path, + import_alias_path=prior.import_alias_path, + imported_model_path=prior_target, + import_command=prior.import_command, + ) + ) + continue + + if import_mode is ImportMode.DIRECT: + alias_path = artifact.blob_path + alias_created = False + else: try: - alias_path.unlink() - alias_path.parent.rmdir() - except OSError as exc: - logger.warning( - "Could not clean up import alias %s: %s", alias_path, exc + alias_path, alias_created = self._ensure_import_alias( + model, artifact, link_mode + ) + except RuntimeError as exc: + return self._partial_result( + model, + records, + completed, + link_mode, + imported_at, + str(exc), + dry_run, ) - if import_error is not None: - return SyncResult(model=model, status="error", message=str(import_error)) - if import_result is None: - return SyncResult( - model=model, - status="error", - message="LM Studio import returned no result", + import_result: ImportResult | None = None + import_error: Exception | None = None + try: + import_result = self.lmstudio.import_model( + str(alias_path), + user_repo=model.import_user_repo, + link_mode=link_mode, + dry_run=dry_run, + ) + except (LMStudioError, subprocess.TimeoutExpired) as exc: + import_error = exc + finally: + self._clean_temporary_alias( + alias_path, + alias_created, + link_mode, + import_mode, + dry_run, + ) + + if import_error is not None or import_result is None: + message = ( + str(import_error) + if import_error is not None + else "LM Studio import returned no result" + ) + return self._partial_result( + model, + records, + completed, + link_mode, + imported_at, + message, + dry_run, + ) + + last_result = import_result + completed.append( + SyncedArtifact( + role=artifact.role, + digest=artifact.digest, + blob_path=artifact.blob_path, + import_alias_path=alias_path, + imported_model_path=( + self.config.lmstudio_models_dir + / model.import_user_repo + / alias_path.name + ), + import_command=import_result.command, + ) ) + if not dry_run: + partial = self._make_record( + model, completed, link_mode, imported_at, vision_confirmed=False + ) + records[model.canonical_name] = partial + self.state.save(records) - record = SyncRecord( - canonical_name=model.canonical_name, - digest=model.model_digest, - blob_path=model.blob_path, - import_alias_path=alias_path, - user_repo=model.user_repo, - link_mode=link_mode, - imported_at=datetime.now(tz=timezone.utc), - imported_model_path=( - self.config.lmstudio_models_dir / model.user_repo / alias_path.name - ), - import_command=import_result.command, + vision_confirmed = True + if len(artifacts) > 1 and not dry_run: + try: + vision_confirmed = self._vision_bundle_is_indexed(model, completed) + except LMStudioError as exc: + return self._partial_result( + model, + records, + completed, + link_mode, + imported_at, + str(exc), + dry_run, + ) + if not vision_confirmed: + return self._partial_result( + model, + records, + completed, + link_mode, + imported_at, + "LM Studio did not index the projector bundle as vision-capable", + dry_run, + ) + + record = self._make_record( + model, completed, link_mode, imported_at, vision_confirmed=vision_confirmed ) + if not dry_run: + records[model.canonical_name] = record + self.state.save(records) + status = "dry-run" if dry_run else "synced" + if already_synced and last_result is None and not dry_run: + status = "skipped" return SyncResult( model=model, - status="dry-run" if dry_run else "synced", - message=_format_import_message(import_result), + status=status, + message=( + _format_import_message(last_result) + if last_result is not None + else "imported artifacts already present" + ), record=record, ) + @staticmethod + def _model_artifacts(model: OllamaModel) -> tuple[OllamaArtifact, ...]: + if model.artifacts: + return model.artifacts + if model.model_digest is None or model.blob_path is None: + return () + return ( + OllamaArtifact( + role=ArtifactRole.MODEL, + media_type="application/vnd.ollama.image.model", + digest=model.model_digest, + blob_path=model.blob_path, + declared_size=model.declared_size, + blob_size=model.blob_size, + gguf_valid=model.gguf_valid, + manifest_index=0, + issues=model.issues, + ), + ) + + def _make_record( + self, + model: OllamaModel, + artifacts: list[SyncedArtifact], + link_mode: LinkMode, + imported_at: datetime, + *, + vision_confirmed: bool, + ) -> SyncRecord: + return SyncRecord( + canonical_name=model.canonical_name, + user_repo=model.import_user_repo, + link_mode=link_mode, + imported_at=imported_at, + artifacts=tuple(artifacts), + vision_confirmed=vision_confirmed, + ) + + def _partial_result( + self, + model: OllamaModel, + records: dict[str, SyncRecord], + completed: list[SyncedArtifact], + link_mode: LinkMode, + imported_at: datetime, + message: str, + dry_run: bool, + ) -> SyncResult: + record = None + if completed: + record = self._make_record( + model, + completed, + link_mode, + imported_at, + vision_confirmed=False, + ) + if not dry_run: + records[model.canonical_name] = record + self.state.save(records) + return SyncResult(model=model, status="error", message=message, record=record) + + def _vision_bundle_is_indexed( + self, model: OllamaModel, artifacts: list[SyncedArtifact] + ) -> bool: + primary = next( + artifact for artifact in artifacts if artifact.role is ArtifactRole.MODEL + ) + if primary.imported_model_path is None: + return False + try: + expected = primary.imported_model_path.relative_to( + self.config.lmstudio_models_dir + ).as_posix() + except ValueError: + return False + for attempt in range(INVENTORY_ATTEMPTS): + if any( + item.path.replace("\\", "/").casefold() == expected.casefold() + and item.vision + for item in self.lmstudio.list_models() + ): + return True + if attempt + 1 < INVENTORY_ATTEMPTS: + time.sleep(INVENTORY_RETRY_DELAY) + return False + + @staticmethod + def _clean_temporary_alias( + alias_path: Path, + alias_created: bool, + link_mode: LinkMode, + import_mode: ImportMode, + dry_run: bool, + ) -> None: + should_remove = dry_run or link_mode is LinkMode.COPY + if not ( + should_remove + and (alias_created or link_mode is LinkMode.COPY) + and alias_path.exists() + and import_mode is not ImportMode.DIRECT + ): + return + try: + alias_path.unlink() + alias_path.parent.rmdir() + except OSError as exc: + logger.warning("Could not clean up import alias %s: %s", alias_path, exc) + def _ensure_import_alias( - self, model: OllamaModel, link_mode: LinkMode + self, + model: OllamaModel, + artifact: OllamaArtifact, + link_mode: LinkMode, ) -> tuple[Path, bool]: staging_dir = self.config.import_staging_dir if link_mode is LinkMode.COPY: @@ -214,15 +430,25 @@ def _ensure_import_alias( # this temporary hard link on the Ollama filesystem so copy mode # still works when StudioLink state lives on another volume. staging_dir = self.config.ollama_models_dir / ".studiolink-imports" - return _ensure_import_alias(model, staging_dir) + return _ensure_import_alias(model, staging_dir, artifact) -def _ensure_import_alias(model: OllamaModel, staging_dir: Path) -> tuple[Path, bool]: - alias_path = staging_dir / model.import_filename - if model.blob_path is None: +def _ensure_import_alias( + model: OllamaModel, + staging_dir: Path, + artifact: OllamaArtifact | None = None, +) -> tuple[Path, bool]: + blob_path = artifact.blob_path if artifact is not None else model.blob_path + alias_name = ( + model.artifact_import_filename(artifact) + if artifact is not None + else model.import_filename + ) + alias_path = staging_dir / alias_name + if blob_path is None: raise RuntimeError(f"No blob path for model {model.canonical_name}") if alias_path.exists(): - if same_file(alias_path, model.blob_path): + if same_file(alias_path, blob_path): logger.debug("Import alias already exists: %s", alias_path) return alias_path, False # The alias survived a re-pull but now points at the old blob content; @@ -231,8 +457,8 @@ def _ensure_import_alias(model: OllamaModel, staging_dir: Path) -> tuple[Path, b alias_path.unlink() staging_dir.mkdir(parents=True, exist_ok=True) try: - os.link(model.blob_path, alias_path) - logger.debug("Created hard link: %s -> %s", alias_path, model.blob_path) + os.link(blob_path, alias_path) + logger.debug("Created hard link: %s -> %s", alias_path, blob_path) return alias_path, True except OSError as exc: raise RuntimeError(f"Failed to create import alias (hard link): {exc}") from exc diff --git a/tests/conftest.py b/tests/conftest.py index 11c5417..b15e2d4 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -17,9 +17,12 @@ from studiolink.config import StudioLinkConfig # noqa: E402 from studiolink.lmstudio_adapter import LMStudioError # noqa: E402 from studiolink.models import ( # noqa: E402 + ArtifactRole, ImportResult, LinkMode, + LMStudioModel, OllamaModel, + SyncedArtifact, SyncRecord, ) @@ -141,12 +144,17 @@ def make_sync_record( ) -> SyncRecord: return SyncRecord( canonical_name=canonical_name, - digest=digest, - blob_path=Path("blob"), - import_alias_path=Path("alias"), user_repo="ollama/llama3", link_mode=LinkMode.HARD_LINK, imported_at=datetime(2026, 1, 1, tzinfo=timezone.utc), + artifacts=( + SyncedArtifact( + role=ArtifactRole.MODEL, + digest=digest, + blob_path=Path("blob"), + import_alias_path=Path("alias"), + ), + ), ) @@ -158,6 +166,7 @@ def __init__(self) -> None: self.fail_for: set[str] = set() self.timeout_for: set[str] = set() self.models_dir: Path | None = None + self.inventory_override: tuple[LMStudioModel, ...] | None = None def get_version(self) -> str | None: return "0.3.17 (fake)" @@ -165,6 +174,26 @@ def get_version(self) -> str | None: def get_import_capabilities(self) -> set[LinkMode]: return {LinkMode.HARD_LINK, LinkMode.COPY, LinkMode.SYMBOLIC_LINK} + def list_models(self) -> tuple[LMStudioModel, ...]: + if self.inventory_override is not None: + return self.inventory_override + if self.models_dir is None or not self.models_dir.exists(): + return () + inventory = [] + for path in self.models_dir.rglob("*.gguf"): + if path.name.startswith("mmproj-"): + continue + relative = path.relative_to(self.models_dir) + inventory.append( + LMStudioModel( + model_key=path.stem, + path=relative.as_posix(), + vision=any(path.parent.glob("mmproj-*.gguf")), + model_type="llm", + ) + ) + return tuple(inventory) + def import_model( self, source_path: str, diff --git a/tests/fixtures/ollama/llava-latest-manifest.json b/tests/fixtures/ollama/llava-latest-manifest.json new file mode 100644 index 0000000..10d97d6 --- /dev/null +++ b/tests/fixtures/ollama/llava-latest-manifest.json @@ -0,0 +1,36 @@ +{ + "schemaVersion": 2, + "mediaType": "application/vnd.docker.distribution.manifest.v2+json", + "config": { + "mediaType": "application/vnd.docker.container.image.v1+json", + "digest": "sha256:7c658f9561e5dbbafb042a00f6a4de57877adddd957809111f3123e272632b4d", + "size": 564 + }, + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": "sha256:170370233dd5c5415250a2ecd5c71586352850729062ccef1496385647293868", + "size": 4108916992 + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": "sha256:72d6f08a42f656d36b356dbe0920675899a99ce21192fd66266fb7d82ed07539", + "size": 624434368 + }, + { + "mediaType": "application/vnd.ollama.image.license", + "digest": "sha256:43070e2d4e532684de521b885f385d0841030efa2b1a20bafb76133a5e1379c1", + "size": 11356 + }, + { + "mediaType": "application/vnd.ollama.image.template", + "digest": "sha256:c43332387573e98fdfad4a606171279955b53d891ba2500552c2984a6560ffb4", + "size": 67 + }, + { + "mediaType": "application/vnd.ollama.image.params", + "digest": "sha256:ed11eda7790d05b49395598a42b155812b17e263214292f7b87d15e14003d337", + "size": 30 + } + ] +} diff --git a/tests/test_cli.py b/tests/test_cli.py index 6198958..02379a9 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -186,6 +186,7 @@ def test_scan_json(self, fake_service, capsys): payload = json.loads(out(capsys)) assert payload[0]["canonical_name"] == "llama3:1b" assert payload[0]["readiness"] == "ready" + assert payload[0]["artifacts"] == [] def test_status_json(self, fake_service, capsys): assert cli.main(["status", "--json"]) == 0 diff --git a/tests/test_lmstudio_adapter.py b/tests/test_lmstudio_adapter.py index 8b9858c..1153703 100644 --- a/tests/test_lmstudio_adapter.py +++ b/tests/test_lmstudio_adapter.py @@ -1,9 +1,52 @@ +import json +import subprocess + import pytest from studiolink.lmstudio_adapter import LMStudioAdapter, LMStudioError from studiolink.models import LinkMode +def test_list_models_parses_json_inventory(make_config, monkeypatch): + config = make_config() + adapter = LMStudioAdapter(config) + payload = [ + { + "type": "llm", + "modelKey": "mmproj-pair", + "path": "ollama/llava/llava-deadbeef.gguf", + "vision": True, + } + ] + + monkeypatch.setattr( + adapter, + "_run", + lambda *args, **kwargs: subprocess.CompletedProcess( + args[0], 0, json.dumps(payload), "" + ), + ) + + inventory = adapter.list_models() + + assert len(inventory) == 1 + assert inventory[0].model_key == "mmproj-pair" + assert inventory[0].path == "ollama/llava/llava-deadbeef.gguf" + assert inventory[0].vision is True + + +def test_list_models_rejects_invalid_json(make_config, monkeypatch): + adapter = LMStudioAdapter(make_config()) + monkeypatch.setattr( + adapter, + "_run", + lambda *args, **kwargs: subprocess.CompletedProcess(args[0], 0, "nope", ""), + ) + + with pytest.raises(LMStudioError, match="invalid model inventory JSON"): + adapter.list_models() + + def test_import_wraps_os_execution_error(make_config, monkeypatch): config = make_config() adapter = LMStudioAdapter(config) diff --git a/tests/test_models.py b/tests/test_models.py index fe9b8f1..4f9cea0 100644 --- a/tests/test_models.py +++ b/tests/test_models.py @@ -65,6 +65,46 @@ def test_custom_registry_dots_replaced(self): assert model.user_repo == "ollama/ghcr-io-team-gemma" +class TestImportRepository: + def test_projector_bundles_use_digest_isolated_repository(self): + from dataclasses import replace + from pathlib import Path + + from studiolink.models import ArtifactRole, OllamaArtifact + + model = make_ollama_model("llava:latest", DIGEST_A) + projector = OllamaArtifact( + role=ArtifactRole.PROJECTOR, + media_type="application/vnd.ollama.image.projector", + digest=DIGEST_B, + blob_path=Path("projector"), + declared_size=1, + blob_size=1, + gguf_valid=True, + manifest_index=1, + ) + primary = OllamaArtifact( + role=ArtifactRole.MODEL, + media_type="application/vnd.ollama.image.model", + digest=DIGEST_A, + blob_path=Path("model"), + declared_size=1, + blob_size=1, + gguf_valid=True, + manifest_index=0, + ) + model = replace(model, artifacts=(primary, projector)) + + assert model.import_user_repo == ( + "ollama/llava--bundle-aaaaaaaaaaaa-bbbbbbbbbbbb" + ) + changed = replace( + model, + artifacts=(primary, replace(projector, digest="sha256:" + "c" * 64)), + ) + assert changed.import_user_repo != model.import_user_repo + + class TestReadiness: def test_ready(self): assert make_ollama_model("m:1").readiness is ModelReadiness.READY @@ -109,6 +149,31 @@ def test_import_command_defaults_empty(self): restored = make_sync_record().to_json() assert restored["import_command"] == [] + def test_projector_artifact_roundtrip(self): + from dataclasses import replace + from pathlib import Path + + from studiolink.models import ArtifactRole, SyncedArtifact + + record = make_sync_record() + projector = SyncedArtifact( + role=ArtifactRole.PROJECTOR, + digest=DIGEST_B, + blob_path=Path("projector-blob"), + import_alias_path=Path("mmproj-model.gguf"), + imported_model_path=Path("models/ollama/model/mmproj-model.gguf"), + import_command=("lms", "import"), + ) + record = replace( + record, + artifacts=(*record.artifacts, projector), + vision_confirmed=True, + ) + + restored = type(record).from_json(record.to_json()) + + assert restored == record + class TestPruneTypes: def test_prune_result_json(self): diff --git a/tests/test_ollama_adapter.py b/tests/test_ollama_adapter.py index f8a4eb7..e81ef69 100644 --- a/tests/test_ollama_adapter.py +++ b/tests/test_ollama_adapter.py @@ -1,5 +1,7 @@ +import json from pathlib import Path +import pytest from conftest import ( DIGEST_A, blob_filename, @@ -7,7 +9,7 @@ write_manifest, ) -from studiolink.models import ModelReadiness +from studiolink.models import ArtifactRole, ModelReadiness from studiolink.ollama_adapter import OllamaAdapter @@ -32,6 +34,28 @@ def test_finds_ready_model(self, make_config): assert model.declared_size == 1234 assert model.issues == () + def test_scans_model_and_projector_as_one_ready_model(self, make_config): + config = make_config() + fixture = ( + Path(__file__).parent / "fixtures" / "ollama" / "llava-latest-manifest.json" + ) + content = json.loads(fixture.read_text(encoding="utf-8")) + write_manifest(config, repository="llava", content=content) + for layer in content["layers"][:2]: + write_blob(config, layer["digest"]) + + model = scan_one(config) + + assert model.canonical_name == "llava:1b" + assert model.readiness is ModelReadiness.READY + assert [artifact.role for artifact in model.artifacts] == [ + ArtifactRole.MODEL, + ArtifactRole.PROJECTOR, + ] + assert model.artifact_import_filename(model.artifacts[1]).startswith( + "mmproj-llava-1b-" + ) + def test_declared_size_garbage_is_tolerated(self, make_config): config = make_config() write_manifest( @@ -76,6 +100,85 @@ def test_missing_model_layer(self, make_config): assert model.readiness is ModelReadiness.INVALID assert "missing Ollama model layer" in model.issues + def test_missing_projector_blob_makes_bundle_stale(self, make_config): + config = make_config() + write_manifest( + config, + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": "sha256:" + "c" * 64, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + + model = scan_one(config) + + assert model.readiness is ModelReadiness.STALE + assert "projector blob is missing from the Ollama blob store" in model.issues + + @pytest.mark.parametrize( + ("extra_layers", "issue"), + [ + ( + [ + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": "sha256:" + "c" * 64, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": "sha256:" + "d" * 64, + }, + ], + "multiple Ollama projector layers are not supported", + ), + ( + [ + { + "mediaType": "application/vnd.ollama.image.adapter", + "digest": "sha256:" + "c" * 64, + } + ], + "Ollama adapter layers are not supported", + ), + ( + [ + { + "mediaType": "application/vnd.ollama.image.draft", + "digest": "sha256:" + "c" * 64, + } + ], + "Ollama draft layers are not supported", + ), + ], + ) + def test_unsupported_artifact_combinations_are_invalid( + self, make_config, extra_layers, issue + ): + config = make_config() + layers = [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + *extra_layers, + ] + write_manifest(config, content={"layers": layers}) + write_blob(config, DIGEST_A) + + model = scan_one(config) + + assert model.readiness is ModelReadiness.INVALID + assert issue in model.issues + class TestMalformedManifests: def test_io_failure_is_isolated_and_marks_scan_incomplete( diff --git a/tests/test_service.py b/tests/test_service.py index bc49bd7..c4b02ef 100644 --- a/tests/test_service.py +++ b/tests/test_service.py @@ -24,6 +24,13 @@ def build_service(config, lmstudio): ) +def replace_primary(record, **changes): + return replace( + record, + artifacts=(replace(record.primary_artifact, **changes),), + ) + + class TestDoctorVolumeCheck: def test_same_device_passes(self, make_config, fake_lmstudio): config = make_config() @@ -157,7 +164,7 @@ def test_preserves_alias_when_current_manifest_is_not_ready( alias = config.import_staging_dir / model.import_filename os.link(blob, alias) StateStore(config.state_file).upsert( - replace( + replace_primary( make_sync_record(model.canonical_name, DIGEST_A), import_alias_path=alias, ) @@ -182,8 +189,10 @@ def test_preserves_alias_required_by_symbolic_import( alias = config.import_staging_dir / model.import_filename os.link(blob, alias) record = replace( - make_sync_record(model.canonical_name, DIGEST_A), - import_alias_path=alias, + replace_primary( + make_sync_record(model.canonical_name, DIGEST_A), + import_alias_path=alias, + ), link_mode=LinkMode.SYMBOLIC_LINK, ) StateStore(config.state_file).upsert(record) @@ -210,6 +219,44 @@ def test_keeps_healthy_alias(self, make_config, fake_lmstudio): assert report.aliases == () assert (config.import_staging_dir / model.import_filename).exists() + def test_keeps_all_healthy_projector_bundle_aliases( + self, make_config, fake_lmstudio + ): + config = make_config() + fake_lmstudio.models_dir = config.lmstudio_models_dir + service = build_service(config, fake_lmstudio) + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = service.scan()[0] + assert service.sync(model_names=[model.canonical_name])[0].status == "synced" + + report = service.prune() + + assert report.aliases == () + assert all( + ( + config.import_staging_dir / model.artifact_import_filename(artifact) + ).exists() + for artifact in model.artifacts + ) + def test_removes_same_name_alias_pointing_elsewhere( self, make_config, fake_lmstudio ): @@ -341,7 +388,7 @@ def test_status_reports_synced_only_when_imported_target_exists( target.parent.mkdir(parents=True) target.write_bytes(b"GGUFxxxx") StateStore(config.state_file).upsert( - replace( + replace_primary( make_sync_record("llama3:1b", DIGEST_A), imported_model_path=target, ) @@ -380,6 +427,39 @@ def test_status_reconciles_legacy_record_with_derived_target( assert entries[0].display_status == "pending" assert entries[0].synced is False + def test_status_requires_projector_bundle_in_lm_studio_inventory( + self, make_config, fake_lmstudio + ): + config = make_config() + fake_lmstudio.models_dir = config.lmstudio_models_dir + service = build_service(config, fake_lmstudio) + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + assert service.sync(model_names=["llava:1b"])[0].status == "synced" + fake_lmstudio.inventory_override = () + + entries = service.status() + + assert entries[0].display_status == "pending" + assert entries[0].synced is False + def test_status_reports_pending_when_imported_target_was_deleted( self, make_config, fake_lmstudio ): @@ -389,7 +469,7 @@ def test_status_reports_pending_when_imported_target_was_deleted( write_blob(config, DIGEST_A) missing_target = config.lmstudio_models_dir / "ollama" / "llama3" / "gone.gguf" StateStore(config.state_file).upsert( - replace( + replace_primary( make_sync_record("llama3:1b", DIGEST_A), imported_model_path=missing_target, ) diff --git a/tests/test_state.py b/tests/test_state.py index 414fa20..826d7db 100644 --- a/tests/test_state.py +++ b/tests/test_state.py @@ -3,7 +3,7 @@ import pytest from conftest import DIGEST_A, make_sync_record -from studiolink.models import SyncRecord +from studiolink.models import ArtifactRole, SyncRecord from studiolink.state import StateStore @@ -79,6 +79,14 @@ def test_non_dict_record_is_skipped(self, tmp_path): ) assert set(StateStore(path).get_all_records()) == {"good:1"} + def test_record_without_primary_model_artifact_is_skipped(self, tmp_path): + path = tmp_path / "state.json" + record = make_sync_record("bad:1", DIGEST_A).to_json() + record["artifacts"][0]["role"] = "projector" + write_raw_state(path, {"schema_version": 2, "sync_records": {"bad:1": record}}) + + assert StateStore(path).get_all_records() == {} + def test_missing_sync_records_key(self, tmp_path): path = tmp_path / "state.json" write_raw_state(path, {"schema_version": 1}) @@ -94,7 +102,7 @@ def test_no_temp_file_left_behind(self, tmp_path): assert path.exists() assert not (tmp_path / "state.json.tmp").exists() payload = json.loads(path.read_text(encoding="utf-8")) - assert payload["schema_version"] == 1 + assert payload["schema_version"] == 2 assert "a:1" in payload["sync_records"] def test_overwrite_keeps_consistent_state(self, tmp_path): @@ -105,6 +113,39 @@ def test_overwrite_keeps_consistent_state(self, tmp_path): assert set(store.get_all_records()) == {"a:1", "b:1"} +class TestSchemaMigration: + def test_legacy_record_becomes_one_model_artifact(self, tmp_path): + path = tmp_path / "state.json" + legacy = { + "canonical_name": "m:1", + "digest": DIGEST_A, + "blob_path": "blob", + "import_alias_path": "alias.gguf", + "user_repo": "ollama/m", + "link_mode": "hard-link", + "imported_at": "2026-01-01T00:00:00+00:00", + "imported_model_path": "models/ollama/m/alias.gguf", + "import_command": ["lms", "import"], + } + write_raw_state(path, {"schema_version": 1, "sync_records": {"m:1": legacy}}) + + record = StateStore(path).get_record("m:1") + + assert record is not None + assert len(record.artifacts) == 1 + assert record.artifacts[0].role is ArtifactRole.MODEL + assert record.artifacts[0].digest == DIGEST_A + + def test_writes_schema_version_two(self, tmp_path): + path = tmp_path / "state.json" + StateStore(path).upsert(make_sync_record("m:1", DIGEST_A)) + + payload = json.loads(path.read_text(encoding="utf-8")) + + assert payload["schema_version"] == 2 + assert payload["sync_records"]["m:1"]["artifacts"][0]["role"] == "model" + + class TestRecordSchema: def test_record_serializes_link_mode(self, tmp_path): path = tmp_path / "state.json" diff --git a/tests/test_syncer.py b/tests/test_syncer.py index 7cf15f9..22d7cd8 100644 --- a/tests/test_syncer.py +++ b/tests/test_syncer.py @@ -9,7 +9,15 @@ write_manifest, ) -from studiolink.models import ImportMode, ImportResult, LinkMode, ModelReadiness +import studiolink.syncer as syncer_module +from studiolink.lmstudio_adapter import LMStudioError +from studiolink.models import ( + ArtifactRole, + ImportMode, + ImportResult, + LinkMode, + ModelReadiness, +) from studiolink.ollama_adapter import OllamaAdapter from studiolink.state import StateStore from studiolink.syncer import ( @@ -80,6 +88,260 @@ def test_direct_mode_imports_blob_path_without_alias(self, make_syncer): assert not config.import_staging_dir.exists() +class TestProjectorBundle: + def test_sync_imports_model_and_projector_into_one_repository(self, make_syncer): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "synced" + assert len(fake.calls) == 2 + assert {call["user_repo"] for call in fake.calls} == {model.import_user_repo} + assert fake.calls[1]["source_path"].endswith( + model.artifact_import_filename(model.artifacts[1]) + ) + assert "/mmproj-" in fake.calls[1]["source_path"].replace("\\", "/") + record = StateStore(config.state_file).get_record(model.canonical_name) + assert record is not None + assert [artifact.role for artifact in record.artifacts] == [ + ArtifactRole.MODEL, + ArtifactRole.PROJECTOR, + ] + assert all( + artifact.imported_model_path is not None + and artifact.imported_model_path.is_file() + for artifact in record.artifacts + ) + + def test_waits_for_lm_studio_to_index_projector(self, make_syncer, monkeypatch): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + real_list = fake.list_models + calls = 0 + + def delayed_inventory(): + nonlocal calls + calls += 1 + return () if calls == 1 else real_list() + + monkeypatch.setattr(fake, "list_models", delayed_inventory) + monkeypatch.setattr(syncer_module.time, "sleep", lambda _: None) + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "synced" + assert calls == 2 + + def test_resync_rechecks_projector_inventory(self, make_syncer, monkeypatch): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + assert syncer.sync([model], **sync_kwargs())[0].status == "synced" + fake.inventory_override = () + monkeypatch.setattr(syncer_module.time, "sleep", lambda _: None) + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "error" + assert "vision-capable" in result.message + + def test_inventory_failure_is_reported_for_model(self, make_syncer, monkeypatch): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + + def fail_inventory(): + raise LMStudioError("inventory unavailable", ["lms"], 1, "boom") + + monkeypatch.setattr(fake, "list_models", fail_inventory) + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "error" + assert "inventory unavailable" in result.message + record = StateStore(config.state_file).get_record(model.canonical_name) + assert record is not None + assert record.vision_confirmed is False + + def test_projector_failure_saves_progress_and_retry_resumes(self, make_syncer): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + model = scan_models(config)[0] + projector_alias = config.import_staging_dir / model.artifact_import_filename( + model.artifacts[1] + ) + fake.fail_for = {str(projector_alias)} + + first = syncer.sync([model], **sync_kwargs())[0] + + assert first.status == "error" + partial = StateStore(config.state_file).get_record(model.canonical_name) + assert partial is not None + assert [artifact.role for artifact in partial.artifacts] == [ArtifactRole.MODEL] + + fake.fail_for.clear() + second = syncer.sync([model], **sync_kwargs())[0] + + assert second.status == "synced" + assert len(fake.calls) == 3 + assert fake.calls[-1]["source_path"] == str(projector_alias) + complete = StateStore(config.state_file).get_record(model.canonical_name) + assert complete is not None and len(complete.artifacts) == 2 + assert complete.vision_confirmed is True + + def test_missing_projector_prevents_every_import(self, make_syncer): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + model = scan_models(config)[0] + + result = syncer.sync([model], **sync_kwargs())[0] + + assert result.status == "error" + assert "ollama pull llava:1b" in result.message + assert fake.calls == [] + + def test_direct_mode_rejects_projector_bundle(self, make_syncer): + syncer, config, fake = make_syncer() + projector_digest = "sha256:" + "c" * 64 + write_manifest( + config, + repository="llava", + content={ + "layers": [ + { + "mediaType": "application/vnd.ollama.image.model", + "digest": DIGEST_A, + }, + { + "mediaType": "application/vnd.ollama.image.projector", + "digest": projector_digest, + }, + ] + }, + ) + write_blob(config, DIGEST_A) + write_blob(config, projector_digest) + + result = syncer.sync( + scan_models(config), + **sync_kwargs(import_mode=ImportMode.DIRECT), + )[0] + + assert result.status == "error" + assert "--direct is not supported" in result.message + assert fake.calls == [] + + class TestCrossVolumeCopy: def test_copy_stages_on_ollama_volume_not_state_volume( self, make_syncer, monkeypatch