mlx-stack 0.3.3__tar.gz → 0.3.5__tar.gz

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/.github/workflows/ci.yml

@@ -49,3 +49,31 @@ jobs:
         with:
           name: coverage-report
           path: coverage.xml
+
+  catalog-validation:
+    name: Catalog Validation
+    runs-on: macos-latest
+    needs: ci
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Validate catalog entries
+        run: make test-catalog

mlx_stack-0.3.5/.github/workflows/integration-nightly.yml

@@ -0,0 +1,58 @@
+name: Nightly Integration
+
+on:
+  schedule:
+    - cron: "0 6 * * *"  # 6 AM UTC daily
+  workflow_dispatch:
+    inputs:
+      model:
+        description: "Specific model ID to test (blank = all non-gated models that fit in memory)"
+        required: false
+
+concurrency:
+  group: nightly-integration
+  cancel-in-progress: true
+
+jobs:
+  smoke:
+    name: Model Smoke Tests
+    runs-on: macos-latest
+    timeout-minutes: 120
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Install project dependencies
+        run: make install
+
+      - name: Install vllm-mlx
+        run: uv tool install vllm-mlx==0.2.6
+
+      - name: Run smoke tests
+        run: |
+          MODEL_FILTER="${{ github.event.inputs.model }}"
+          if [ -n "$MODEL_FILTER" ]; then
+            uv run pytest -m smoke -k "$MODEL_FILTER" -v --tb=long
+          else
+            uv run pytest -m smoke -v --tb=long
+          fi
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+
+      - name: Upload compatibility matrix
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: compatibility-matrix
+          path: ~/.mlx-stack-test-cache/reports/

mlx_stack-0.3.5/.github/workflows/integration-prerelease.yml

@@ -0,0 +1,53 @@
+name: Pre-Release Integration
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+concurrency:
+  group: prerelease-integration
+  cancel-in-progress: true
+
+jobs:
+  stack-integration:
+    name: Full Stack Integration
+    runs-on: macos-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Install project dependencies
+        run: uv sync --dev
+
+      - name: Install openai for harness tests
+        run: uv pip install openai>=1.0
+
+      - name: Install vllm-mlx and litellm
+        run: |
+          uv tool install vllm-mlx==0.2.6
+          uv tool install "litellm[proxy]==1.83.0"
+
+      - name: Run stack integration tests
+        run: uv run pytest -m "integration or harness" -v --tb=long
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: integration-results
+          path: ~/.mlx-stack-test-cache/reports/

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/.gitignore

@@ -34,3 +34,4 @@ htmlcov/
 
 # Ruff
 .ruff_cache/
+REQUIREMENTS.md

mlx_stack-0.3.5/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.5"
+}

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.5](https://github.com/weklund/mlx-stack/compare/v0.3.4...v0.3.5) (2026-04-04)
+
+
+### Features
+
+* expand ruff lint rules with tier 1+2 quality rulesets ([#22](https://github.com/weklund/mlx-stack/issues/22)) ([75490f6](https://github.com/weklund/mlx-stack/commit/75490f6817a87a6b63818fa1f7c1660e59766ba3))
+
+
+### Refactors
+
+* **tests:** replace brittle mock-heavy tests with behavioral tests and shared factories ([#32](https://github.com/weklund/mlx-stack/issues/32)) ([9af6078](https://github.com/weklund/mlx-stack/commit/9af60781e14c1466219ee2644928db9c9a39041e))
+  - `FakeServiceLayer` replaces 10-deep `@patch` stacks in `TestRunUp`
+  - Consolidate ~50 duplicate helpers into `tests/factories.py`
+  - AAA comments (`# Arrange`, `# Act`, `# Assert`) across 17 test files
+  - `make lint` now includes pyright for shift-left type checking
+  - Net: -577 lines, 1,481 tests pass, 73% reduction in `@patch` usage
+
+## [0.3.4](https://github.com/weklund/mlx-stack/compare/v0.3.3...v0.3.4) (2026-04-03)
+
+
+### Features
+
+* 4-tier integration testing framework ([#16](https://github.com/weklund/mlx-stack/issues/16)) ([e3dcf9a](https://github.com/weklund/mlx-stack/commit/e3dcf9ae4eaa55ee8ca522819d3dc16846d3e1ea))
+
 ## [0.3.3](https://github.com/weklund/mlx-stack/compare/v0.3.2...v0.3.3) (2026-04-02)
 
 

mlx_stack-0.3.5/Makefile

@@ -0,0 +1,37 @@
+.PHONY: install lint typecheck test check test-catalog test-smoke test-integration test-harness
+
+## Install dev dependencies
+install:
+	uv sync --dev
+
+## Lint source and tests (ruff + pyright)
+lint:
+	uv run ruff check src/ tests/
+	uv run python -m pyright
+
+## Run type checker only (alias kept for CI compatibility)
+typecheck:
+	uv run python -m pyright
+
+## Run tests with coverage
+test:
+	uv run pytest --cov=src/mlx_stack -x -q --tb=short
+
+## Run all checks (same as CI)
+check: lint typecheck test
+
+## Run catalog validation (requires network, no models)
+test-catalog:
+	uv run pytest -m catalog_validation -v --tb=short
+
+## Run per-model smoke tests (requires macOS + vllm-mlx)
+test-smoke:
+	uv run pytest -m smoke -v --tb=long
+
+## Run full stack integration tests (requires macOS + vllm-mlx + litellm)
+test-integration:
+	uv run pytest -m integration -v --tb=long
+
+## Run harness compatibility tests (requires above + openai)
+test-harness:
+	uv run pytest -m harness -v --tb=long

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlx-stack
-Version: 0.3.3
+Version: 0.3.5
 Summary: CLI control plane for local LLM infrastructure on Apple Silicon
 Project-URL: Homepage, https://github.com/weklund/mlx-stack
 Project-URL: Repository, https://github.com/weklund/mlx-stack

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/pyproject.toml

@@ -53,9 +53,12 @@ packages = ["src/mlx_stack"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
-addopts = "-x -q --tb=short -m 'not integration'"
+addopts = "-x -q --tb=short -m 'not integration and not smoke and not catalog_validation and not harness'"
 markers = [
     "integration: real system integration tests (launchctl, etc.)",
+    "smoke: per-model smoke tests requiring model download and inference",
+    "catalog_validation: catalog data integrity checks (requires network, no models)",
+    "harness: external tool compatibility tests (OpenAI client, streaming)",
 ]
 
 [tool.ruff]
@@ -64,7 +67,40 @@ line-length = 100
 src = ["src", "tests"]
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "W"]
+select = [
+    # Tier 1 — high value, very safe
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "W",    # pycodestyle warnings
+    "UP",   # pyupgrade — modern Python syntax
+    "B",    # bugbear — common bug patterns
+    "SIM",  # simplify — reduce complexity
+    "C4",   # flake8-comprehensions
+    "RUF",  # Ruff-specific rules
+    # Tier 2 — strong value, minor tuning
+    "PIE",  # misc cleanup
+    "RET",  # return simplification
+    "PERF", # performance anti-patterns
+    "PT",   # pytest style
+    # "C90",  # mccabe complexity — enable after refactoring complex functions
+    "FURB", # modernization
+    "FLY",  # f-string conversion
+]
+ignore = [
+    "E501",   # line length (formatter handles this)
+    "SIM108", # ternary operator (opinionated)
+    "SIM117", # nested with statements (clearer in test mocking patterns)
+    "PT018",  # composite assertions (splitting weakens error messages)
+    "PT019",  # fixture without value (usefixtures less readable)
+    "PT017",  # assert in except (valid test pattern)
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.per-file-ignores]
+"src/mlx_stack/_version.py" = ["RUF022"]  # auto-generated by hatch-vcs
 
 [tool.pyright]
 pythonVersion = "3.13"

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.3'
-__version_tuple__ = version_tuple = (0, 3, 3)
+__version__ = version = '0.3.5'
+__version_tuple__ = version_tuple = (0, 3, 5)
 
 __commit_id__ = commit_id = None

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/bench.py

@@ -168,23 +168,16 @@ def _display_results(result: BenchmarkResult_, out: Console, save: bool = False)
         out.print(Text("Tool Calling", style="bold cyan"))
         tc = result.tool_call_result
         if tc.success:
-            out.print(
-                f"  [green]✓ Valid tool call[/green] — "
-                f"round-trip: {tc.round_trip_time:.2f}s"
-            )
+            out.print(f"  [green]✓ Valid tool call[/green] — round-trip: {tc.round_trip_time:.2f}s")
         else:
-            out.print(
-                f"  [red]✗ Tool call failed[/red] — {tc.error}"
-            )
+            out.print(f"  [red]✗ Tool call failed[/red] — {tc.error}")
         out.print()
     elif not result.tool_call_result:
         # Check if model supports tool calling from entry
         if not result.catalog_data_available:
             pass  # Skip silently if no catalog data
         else:
-            out.print(
-                "[dim]Tool calling: skipped (model does not support tool calling)[/dim]"
-            )
+            out.print("[dim]Tool calling: skipped (model does not support tool calling)[/dim]")
             out.print()
 
     # Iteration details
@@ -212,6 +205,8 @@ def _display_results(result: BenchmarkResult_, out: Console, save: bool = False)
 
     # Save confirmation
     if save:
-        out.print("[green]✓ Results saved.[/green] "
-                  "These will be used by 'recommend' and 'init' for scoring.")
+        out.print(
+            "[green]✓ Results saved.[/green] "
+            "These will be used by 'recommend' and 'init' for scoring."
+        )
         out.print()

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/config.py

@@ -138,9 +138,7 @@ def config_reset(yes: bool, force: bool) -> None:
         # Check if stdin is a TTY for interactive confirmation
         try:
             if click.get_text_stream("stdin").isatty():
-                confirmed = click.confirm(
-                    "Reset all configuration to defaults?", default=False
-                )
+                confirmed = click.confirm("Reset all configuration to defaults?", default=False)
             else:
                 console.print(
                     "[bold red]Error:[/bold red] Reset requires --yes or --force flag "

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/init.py

@@ -64,13 +64,10 @@ def _display_summary(result: dict) -> None:
     budget_gb = result["memory_budget_gb"]
     total_memory_gb = result.get("total_memory_gb", 0.0)
     out.print(
-        f"[dim]Hardware: {profile.chip} ({profile.memory_gb} GB) · "
-        f"Budget: {budget_gb:.1f} GB[/dim]"
+        f"[dim]Hardware: {profile.chip} ({profile.memory_gb} GB) · Budget: {budget_gb:.1f} GB[/dim]"
     )
     if total_memory_gb > 0:
-        out.print(
-            f"[dim]Total estimated memory: {total_memory_gb:.1f} GB[/dim]"
-        )
+        out.print(f"[dim]Total estimated memory: {total_memory_gb:.1f} GB[/dim]")
 
     # Warnings (e.g., memory budget exceeded with --add)
     init_warnings = result.get("warnings", [])
@@ -83,8 +80,7 @@ def _display_summary(result: dict) -> None:
     if stack.get("cloud_fallback"):
         out.print()
         out.print(
-            "[bold green]☁ Cloud Fallback[/bold green]  "
-            "Premium tier via OpenRouter configured"
+            "[bold green]☁ Cloud Fallback[/bold green]  Premium tier via OpenRouter configured"
         )
 
     # Missing models warning

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/install.py

@@ -42,9 +42,7 @@ def _display_status(status: AgentStatus) -> None:
     if not status.installed:
         out.print(Text("Status: not installed", style="dim"))
     elif status.running and status.pid is not None:
-        out.print(
-            Text(f"Status: installed and running (PID {status.pid})", style="green")
-        )
+        out.print(Text(f"Status: installed and running (PID {status.pid})", style="green"))
     else:
         out.print(Text("Status: installed but not running", style="yellow"))
 

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/logs.py

@@ -6,6 +6,7 @@ trigger on-demand rotation, and view archived logs.
 
 from __future__ import annotations
 
+import contextlib
 import sys
 
 import click
@@ -78,7 +79,7 @@ def _display_rotation_results(results: list) -> None:
             out.print(f"[green]✓[/green] {result.service}: rotated")
             any_rotated = True
         else:
-            out.print(f"[dim]–[/dim] {result.service}: no rotation needed")
+            out.print(f"[dim]-[/dim] {result.service}: no rotation needed")
 
     if not results:
         out.print(Text("No log files found to rotate.", style="yellow"))
@@ -213,11 +214,8 @@ def logs(
     # Handle --follow mode
     if follow:
         num = tail_lines if tail_lines is not None else DEFAULT_TAIL_LINES
-        try:
+        with contextlib.suppress(KeyboardInterrupt):
             follow_log(log_path, num_lines=num, output_callback=click.echo)
-        except KeyboardInterrupt:
-            # Belt-and-suspenders: ensure clean exit
-            pass
         return
 
     # Default: show tail of log

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/main.py

@@ -25,6 +25,7 @@ from mlx_stack.cli.models import models as models_command
 from mlx_stack.cli.profile import profile as profile_command
 from mlx_stack.cli.pull import pull as pull_command
 from mlx_stack.cli.recommend import recommend as recommend_command
+from mlx_stack.cli.setup import setup as setup_command
 from mlx_stack.cli.status import status as status_command
 from mlx_stack.cli.up import up as up_command
 from mlx_stack.cli.watch import watch as watch_command
@@ -73,6 +74,7 @@ class RichGroup(click.Group):
             }
 
             command_categories = {
+                "setup": "Setup & Configuration",
                 "profile": "Setup & Configuration",
                 "config": "Setup & Configuration",
                 "init": "Setup & Configuration",
@@ -165,6 +167,7 @@ def cli(ctx: click.Context) -> None:
 # These will be replaced by real implementations in subsequent features.
 
 
+cli.add_command(setup_command, "setup")
 cli.add_command(profile_command, "profile")
 cli.add_command(recommend_command, "recommend")
 cli.add_command(init_command, "init")

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/models.py

@@ -80,7 +80,7 @@ def _display_local_models() -> None:
             indicator_style = "bold green" if model.is_active else ""
 
             # Display name: prefer catalog name, fall back to directory name
-            display_name = model.catalog_name if model.catalog_name else model.name
+            display_name = model.catalog_name or model.name
 
             # Size
             size_str = format_size(model.disk_size_bytes)
@@ -217,7 +217,7 @@ def _display_catalog(
         local_style = "bold green" if cm.is_local else ""
 
         # Parameters
-        params_str = f"{cm.params_b:.1f}B" if cm.params_b >= 1.0 else f"{cm.params_b:.1f}B"
+        params_str = f"{cm.params_b:.1f}B"
 
         # Quantizations
         quants_str = ", ".join(cm.quants)
@@ -270,7 +270,9 @@ def _display_catalog(
 @click.option("--family", default=None, help="Filter catalog by model family (e.g., 'qwen3.5').")
 @click.option("--tag", default=None, help="Filter catalog by tag (e.g., 'agent-ready').")
 @click.option(
-    "--tool-calling", "tool_calling", is_flag=True,
+    "--tool-calling",
+    "tool_calling",
+    is_flag=True,
     help="Filter catalog to tool-calling-capable models only.",
 )
 def models(

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/profile.py

@@ -52,12 +52,8 @@ def profile() -> None:
 
     if hw.is_estimate:
         out.print()
-        out.print(
-            "[yellow]⚠ Bandwidth is estimated for unknown chip.[/yellow]"
-        )
-        out.print(
-            "  Run [bold]mlx-stack bench --save[/bold] to calibrate with real measurements."
-        )
+        out.print("[yellow]⚠ Bandwidth is estimated for unknown chip.[/yellow]")
+        out.print("  Run [bold]mlx-stack bench --save[/bold] to calibrate with real measurements.")
 
     out.print()
     from mlx_stack.core.paths import get_profile_path

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/pull.py

@@ -115,20 +115,13 @@ def _run_post_download_bench(model_id: str, quant: str, out: Console) -> None:
         from mlx_stack.core.benchmark import BenchmarkError, run_benchmark
 
         result = run_benchmark(target=model_id, save=True)
-        out.print(
-            f"  Prompt TPS: {result.prompt_tps_mean:.1f} ± {result.prompt_tps_std:.1f} tok/s"
-        )
-        out.print(
-            f"  Gen TPS:    {result.gen_tps_mean:.1f} ± {result.gen_tps_std:.1f} tok/s"
-        )
+        out.print(f"  Prompt TPS: {result.prompt_tps_mean:.1f} ± {result.prompt_tps_std:.1f} tok/s")
+        out.print(f"  Gen TPS:    {result.gen_tps_mean:.1f} ± {result.gen_tps_std:.1f} tok/s")
         out.print()
-        out.print(
-            "[dim]Results saved for use by 'recommend' and 'init' scoring.[/dim]"
-        )
+        out.print("[dim]Results saved for use by 'recommend' and 'init' scoring.[/dim]")
     except BenchmarkError as exc:
         out.print(
-            f"[yellow]Benchmark failed: {exc}[/yellow]\n"
-            f"Run 'mlx-stack bench {model_id}' to retry."
+            f"[yellow]Benchmark failed: {exc}[/yellow]\nRun 'mlx-stack bench {model_id}' to retry."
         )
     except Exception as exc:
         out.print(

{mlx_stack-0.3.3 → mlx_stack-0.3.5}/src/mlx_stack/cli/recommend.py

@@ -67,9 +67,7 @@ def parse_budget(raw: str) -> float:
 
     value = float(match.group(1))
     if value <= 0:
-        msg = (
-            f"Invalid budget '{raw}'. Budget must be a positive value."
-        )
+        msg = f"Invalid budget '{raw}'. Budget must be a positive value."
         raise click.BadParameter(msg, param_hint="'--budget'")
 
     return value
@@ -96,8 +94,7 @@ def _resolve_profile() -> HardwareProfile:
     # Auto-detect (in-memory only — recommend is display-only, no file writes)
     console.print("[dim]No saved profile found — detecting hardware...[/dim]")
     try:
-        profile = detect_hardware()
-        return profile
+        return detect_hardware()
     except HardwareError as exc:
         console.print(f"[bold red]Error:[/bold red] {exc}")
         raise SystemExit(1) from None
@@ -206,12 +203,8 @@ def _display_tier_table(result: RecommendationResult) -> None:
     has_estimates = any(t.model.is_estimated for t in result.tiers)
     if has_estimates:
         out.print()
-        out.print(
-            "[yellow]⚠ Some performance values are estimated from bandwidth ratio.[/yellow]"
-        )
-        out.print(
-            "  Run [bold]mlx-stack bench --save[/bold] to calibrate with real measurements."
-        )
+        out.print("[yellow]⚠ Some performance values are estimated from bandwidth ratio.[/yellow]")
+        out.print("  Run [bold]mlx-stack bench --save[/bold] to calibrate with real measurements.")
 
     out.print()
     out.print("[dim]This is a recommendation only — no files were written.[/dim]")
@@ -268,20 +261,15 @@ def _display_all_models(result: RecommendationResult) -> None:
     if openrouter_key:
         out.print()
         out.print(
-            "[bold green]☁ Cloud Fallback[/bold green]  "
-            "Premium tier via OpenRouter also available."
+            "[bold green]☁ Cloud Fallback[/bold green]  Premium tier via OpenRouter also available."
         )
 
     # Estimated warning
     has_estimates = any(m.is_estimated for m in result.all_scored)
     if has_estimates:
         out.print()
-        out.print(
-            "[yellow]⚠ Some performance values are estimated from bandwidth ratio.[/yellow]"
-        )
-        out.print(
-            "  Run [bold]mlx-stack bench --save[/bold] to calibrate with real measurements."
-        )
+        out.print("[yellow]⚠ Some performance values are estimated from bandwidth ratio.[/yellow]")
+        out.print("  Run [bold]mlx-stack bench --save[/bold] to calibrate with real measurements.")
 
     out.print()
     out.print("[dim]This is a recommendation only — no files were written.[/dim]")
@@ -329,8 +317,7 @@ def recommend(budget: str | None, intent: str | None, show_all: bool) -> None:
     elif intent not in VALID_INTENTS:
         valid = ", ".join(sorted(VALID_INTENTS))
         console.print(
-            f"[bold red]Error:[/bold red] Invalid intent '{intent}'. "
-            f"Valid intents: {valid}"
+            f"[bold red]Error:[/bold red] Invalid intent '{intent}'. Valid intents: {valid}"
         )
         raise SystemExit(1)