mlx-stack 0.3.4__tar.gz → 0.3.6__tar.gz

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/.github/workflows/ci.yml

@@ -5,6 +5,9 @@ on:
     branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
   cancel-in-progress: true

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/.github/workflows/integration-nightly.yml

@@ -9,6 +9,9 @@ on:
         description: "Specific model ID to test (blank = all non-gated models that fit in memory)"
         required: false
 
+permissions:
+  contents: read
+
 concurrency:
   group: nightly-integration
   cancel-in-progress: true

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/.github/workflows/integration-prerelease.yml

@@ -5,6 +5,9 @@ on:
     types: [created]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 concurrency:
   group: prerelease-integration
   cancel-in-progress: true

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

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

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/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.6](https://github.com/weklund/mlx-stack/compare/v0.3.5...v0.3.6) (2026-04-04)
+
+
+### Bug Fixes
+
+* add explicit permissions to CI and integration workflows ([#34](https://github.com/weklund/mlx-stack/issues/34)) ([0f8bfb0](https://github.com/weklund/mlx-stack/commit/0f8bfb0a17df82142261284f8d6405918ae6b759))
+
+## [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)
 
 

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/Makefile

@@ -4,11 +4,12 @@
 install:
 	uv sync --dev
 
-## Lint source and tests
+## Lint source and tests (ruff + pyright)
 lint:
 	uv run ruff check src/ tests/
+	uv run python -m pyright
 
-## Run type checker across the full project
+## Run type checker only (alias kept for CI compatibility)
 typecheck:
 	uv run python -m pyright
 

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mlx-stack
-Version: 0.3.4
+Version: 0.3.6
 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
@@ -43,8 +43,7 @@ Most local LLM tools serve **one model at a time** and leave you to figure out w
 
 ```bash
 uv tool install mlx-stack
-mlx-stack init --accept-defaults   # detects hardware, picks models, generates configs
-mlx-stack up                       # 3 model servers + API gateway, one command
+mlx-stack setup                    # detects hardware, picks models, pulls, starts — one command
 # → OpenAI-compatible API at http://localhost:4000/v1
 ```
 
@@ -170,6 +169,33 @@ uvx mlx-stack profile
 
 ## Quick Start
 
+The fastest way to get running is the interactive setup command:
+
+```bash
+mlx-stack setup
+```
+
+This walks you through hardware detection, model selection, downloading, and starting all services in one guided flow. For CI or scripting, pass `--accept-defaults` to skip all prompts:
+
+```bash
+mlx-stack setup --accept-defaults
+```
+
+The OpenAI-compatible API is now available at `http://localhost:4000/v1`.
+
+```bash
+# Check service health
+mlx-stack status
+
+# Stop everything when done
+mlx-stack down
+```
+
+<details>
+<summary>Manual step-by-step setup</summary>
+
+If you prefer full control over each step:
+
 ```bash
 # 1. Detect your hardware
 mlx-stack profile
@@ -187,17 +213,20 @@ mlx-stack up
 mlx-stack status
 ```
 
-The OpenAI-compatible API is now available at `http://localhost:4000/v1`.
-
-```bash
-# Stop everything when done
-mlx-stack down
-```
+</details>
 
 ## CLI Reference
 
 ### Setup & Configuration
 
+**`mlx-stack setup`** — Interactive guided setup: detects hardware, selects models, pulls weights, and starts the stack in one command.
+
+| Option | Description |
+|--------|-------------|
+| `--accept-defaults` | Skip all prompts and use recommended defaults |
+| `--intent <balanced\|agent-fleet>` | Use case intent (prompted if not provided) |
+| `--budget-pct <10-90>` | Memory budget as percentage of unified memory (default: 40) |
+
 | Command | Description |
 |---------|-------------|
 | `mlx-stack profile` | Detect Apple Silicon hardware and save profile to `~/.mlx-stack/profile.json` |
@@ -323,7 +352,7 @@ mlx-stack is designed to run unattended on always-on hardware like a Mac Mini.
 ### Quick setup
 
 ```bash
-mlx-stack init --accept-defaults
+mlx-stack setup --accept-defaults
 mlx-stack install
 ```
 
@@ -436,14 +465,12 @@ See [DEVELOPING.md](DEVELOPING.md) for the full developer guide, including proje
 # Install dev dependencies
 uv sync
 
-# Run tests
-uv run pytest
-
-# Type checking
-uv run python -m pyright
+# Run all checks (lint + typecheck + tests) — same as CI
+make check
 
-# Linting
-uv run ruff check src/ tests/
+# Or individually
+make lint    # ruff + pyright
+make test    # pytest with coverage
 ```
 
 ## Contributing

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/README.md

@@ -14,8 +14,7 @@ Most local LLM tools serve **one model at a time** and leave you to figure out w
 
 ```bash
 uv tool install mlx-stack
-mlx-stack init --accept-defaults   # detects hardware, picks models, generates configs
-mlx-stack up                       # 3 model servers + API gateway, one command
+mlx-stack setup                    # detects hardware, picks models, pulls, starts — one command
 # → OpenAI-compatible API at http://localhost:4000/v1
 ```
 
@@ -141,6 +140,33 @@ uvx mlx-stack profile
 
 ## Quick Start
 
+The fastest way to get running is the interactive setup command:
+
+```bash
+mlx-stack setup
+```
+
+This walks you through hardware detection, model selection, downloading, and starting all services in one guided flow. For CI or scripting, pass `--accept-defaults` to skip all prompts:
+
+```bash
+mlx-stack setup --accept-defaults
+```
+
+The OpenAI-compatible API is now available at `http://localhost:4000/v1`.
+
+```bash
+# Check service health
+mlx-stack status
+
+# Stop everything when done
+mlx-stack down
+```
+
+<details>
+<summary>Manual step-by-step setup</summary>
+
+If you prefer full control over each step:
+
 ```bash
 # 1. Detect your hardware
 mlx-stack profile
@@ -158,17 +184,20 @@ mlx-stack up
 mlx-stack status
 ```
 
-The OpenAI-compatible API is now available at `http://localhost:4000/v1`.
-
-```bash
-# Stop everything when done
-mlx-stack down
-```
+</details>
 
 ## CLI Reference
 
 ### Setup & Configuration
 
+**`mlx-stack setup`** — Interactive guided setup: detects hardware, selects models, pulls weights, and starts the stack in one command.
+
+| Option | Description |
+|--------|-------------|
+| `--accept-defaults` | Skip all prompts and use recommended defaults |
+| `--intent <balanced\|agent-fleet>` | Use case intent (prompted if not provided) |
+| `--budget-pct <10-90>` | Memory budget as percentage of unified memory (default: 40) |
+
 | Command | Description |
 |---------|-------------|
 | `mlx-stack profile` | Detect Apple Silicon hardware and save profile to `~/.mlx-stack/profile.json` |
@@ -294,7 +323,7 @@ mlx-stack is designed to run unattended on always-on hardware like a Mac Mini.
 ### Quick setup
 
 ```bash
-mlx-stack init --accept-defaults
+mlx-stack setup --accept-defaults
 mlx-stack install
 ```
 
@@ -407,14 +436,12 @@ See [DEVELOPING.md](DEVELOPING.md) for the full developer guide, including proje
 # Install dev dependencies
 uv sync
 
-# Run tests
-uv run pytest
-
-# Type checking
-uv run python -m pyright
+# Run all checks (lint + typecheck + tests) — same as CI
+make check
 
-# Linting
-uv run ruff check src/ tests/
+# Or individually
+make lint    # ruff + pyright
+make test    # pytest with coverage
 ```
 
 ## Contributing

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/pyproject.toml

@@ -67,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.4 → mlx_stack-0.3.6}/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.4'
-__version_tuple__ = version_tuple = (0, 3, 4)
+__version__ = version = '0.3.6'
+__version_tuple__ = version_tuple = (0, 3, 6)
 
 __commit_id__ = commit_id = None

{mlx_stack-0.3.4 → mlx_stack-0.3.6}/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.4 → mlx_stack-0.3.6}/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.4 → mlx_stack-0.3.6}/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.4 → mlx_stack-0.3.6}/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.4 → mlx_stack-0.3.6}/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.4 → mlx_stack-0.3.6}/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.4 → mlx_stack-0.3.6}/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.4 → mlx_stack-0.3.6}/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.4 → mlx_stack-0.3.6}/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)