Scan models dir for GGUF files; ACESTEP_MODELS as filter/gate

Co-authored-by: lmangani <1423657+lmangani@users.noreply.github.com>
Agent-Logs-Url: https://github.com/audiohacking/acestep-cpp-api/sessions/8c812542-7f5b-4523-9ab9-8b884ad75b21

Author: Copilot

README.md

@@ -52,23 +52,38 @@ Per-request `lm_model_path` and **`ACESTEP_MODEL_MAP`** values use the same reso
 
 ## Multi-model support (GET /v1/models + per-request `model`)
 
-Register multiple DiT models via `ACESTEP_MODEL_MAP` (JSON). The available model list is **derived automatically** from the map keys — no separate list variable is needed. Select a model per-request using the `model` field in `/release_task`.
+`GET /v1/models` **automatically scans `ACESTEP_MODELS_DIR`** for `.gguf` files and returns them as the available model list. No extra configuration is required.
 
 ```bash
 export ACESTEP_MODELS_DIR="$HOME/models/acestep"
-export ACESTEP_MODEL_MAP='{"acestep-v15-turbo":"acestep-v15-turbo-Q8_0.gguf","acestep-v15-turbo-shift3":"acestep-v15-turbo-shift3-Q8_0.gguf"}'
-# Optional: set which model name is default (first map key is used if omitted)
-# export ACESTEP_DEFAULT_MODEL=acestep-v15-turbo
+# /v1/models will list every .gguf file found there, e.g.:
+# ["acestep-v15-turbo-Q8_0.gguf", "acestep-v15-turbo-shift3-Q8_0.gguf"]
 ```
 
+Use the discovered filename as the `model` value per-request:
+
 ```bash
-# List models
-curl http://localhost:8001/v1/models
+curl http://localhost:8001/v1/models   # discover available names
 
-# Generate with a specific model
 curl -X POST http://localhost:8001/release_task \
   -H 'Content-Type: application/json' \
-  -d '{"prompt": "jazz piano trio", "model": "acestep-v15-turbo-shift3"}'
+  -d '{"prompt": "jazz piano trio", "model": "acestep-v15-turbo-shift3-Q8_0.gguf"}'
+```
+
+**Optional: logical names via `ACESTEP_MODEL_MAP`** — map friendly names to GGUF filenames:
+
+```bash
+export ACESTEP_MODELS_DIR="$HOME/models/acestep"
+export ACESTEP_MODEL_MAP='{"acestep-v15-turbo":"acestep-v15-turbo-Q8_0.gguf","acestep-v15-turbo-shift3":"acestep-v15-turbo-shift3-Q8_0.gguf"}'
+# Now use the short names: "model": "acestep-v15-turbo"
+```
+
+**Optional: `ACESTEP_MODELS` as a filter/gate** — restrict the list to a subset:
+
+```bash
+export ACESTEP_MODELS_DIR="$HOME/models/acestep"
+export ACESTEP_MODELS="acestep-v15-turbo-Q8_0.gguf,acestep-v15-turbo-shift3-Q8_0.gguf"
+# Only those two filenames appear in /v1/models even if more .gguf files exist
 ```
 
 Generation parameters (`inference_steps`, `guidance_scale`, `bpm`, etc.) are **always per-request** and are never fixed by environment variables.

docs/API.md

@@ -415,18 +415,18 @@ curl -X POST http://localhost:8001/create_random_sample \
 
 - **URL**: `GET /v1/models`
 
-Returns the DiT models registered on this server. The list is derived automatically from `ACESTEP_MODEL_MAP` (no separate list variable required).
+Returns the DiT models available on this server. The list is discovered automatically by scanning `ACESTEP_MODELS_DIR` for `.gguf` files. `ACESTEP_MODEL_MAP` (if set) overrides discovery with explicit logical names. `ACESTEP_MODELS` acts as a filter/gate on the discovered list.
 
 ### 8.2 Response
 
 ```json
 {
   "data": {
     "models": [
-      { "name": "acestep-v15-turbo",        "is_default": true  },
-      { "name": "acestep-v15-turbo-shift3", "is_default": false }
+      { "name": "acestep-v15-turbo-Q8_0.gguf", "is_default": true  },
+      { "name": "acestep-v15-turbo-shift3-Q8_0.gguf", "is_default": false }
     ],
-    "default_model": "acestep-v15-turbo"
+    "default_model": "acestep-v15-turbo-Q8_0.gguf"
   },
   "code": 200,
   "error": null,
@@ -441,16 +441,49 @@ Returns the DiT models registered on this server. The list is derived automatica
 curl http://localhost:8001/v1/models
 ```
 
-### 8.4 Registering Multiple Models
+### 8.4 Model discovery order
 
-Set `ACESTEP_MODEL_MAP` to a JSON object mapping logical names to GGUF file paths (bare filenames resolve under `ACESTEP_MODELS_DIR`):
+1. **`ACESTEP_MODEL_MAP`** (explicit) — JSON map of `{"logical-name": "file.gguf", …}`. The logical names are exposed as the model names. Use this when you want human-friendly names instead of raw filenames.
+2. **`ACESTEP_MODELS_DIR` scan** (automatic) — `.gguf` files found in the models directory are listed by their filename (e.g. `acestep-v15-turbo-Q8_0.gguf`). Sorted alphabetically.
+3. **Fallback** — `[defaultModel]` when no directory is set and no map is configured.
+
+`ACESTEP_MODELS` (comma-separated names) acts as a **filter/gate** on whichever source is discovered (map keys or scanned filenames). Only names present in the filter are returned.
+
+### 8.5 Selecting a model per-request
+
+Use the `model` field in `/release_task` with a name from the list:
+
+```bash
+# Auto-discover — just set the models dir
+export ACESTEP_MODELS_DIR="$HOME/models/acestep"
+
+# List what was found
+curl http://localhost:8001/v1/models
+# → ["acestep-v15-turbo-Q8_0.gguf", "acestep-v15-turbo-shift3-Q8_0.gguf", ...]
+
+# Select one per-request
+curl -X POST http://localhost:8001/release_task \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt": "jazz piano trio", "model": "acestep-v15-turbo-shift3-Q8_0.gguf"}'
+```
+
+Or use `ACESTEP_MODEL_MAP` for logical names:
 
 ```bash
 export ACESTEP_MODELS_DIR="$HOME/models/acestep"
 export ACESTEP_MODEL_MAP='{"acestep-v15-turbo":"acestep-v15-turbo-Q8_0.gguf","acestep-v15-turbo-shift3":"acestep-v15-turbo-shift3-Q8_0.gguf"}'
+
+curl -X POST http://localhost:8001/release_task \
+  -H 'Content-Type: application/json' \
+  -d '{"prompt": "jazz piano trio", "model": "acestep-v15-turbo-shift3"}'
 ```
 
-The `/v1/models` response will list exactly those names. Select one per-request via the `model` field in `/release_task`.
+Or gate the list to a subset:
+
+```bash
+export ACESTEP_MODELS_DIR="$HOME/models/acestep"
+export ACESTEP_MODELS="acestep-v15-turbo-Q8_0.gguf,acestep-v15-turbo-shift3-Q8_0.gguf"
+```
 
 ---
 
@@ -561,11 +594,15 @@ Only **paths** and server-level settings are configured via environment variable
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `ACESTEP_MODEL_MAP` | `{}` | JSON map of `{"name": "path.gguf", …}` — drives both the `/v1/models` list **and** per-request `model` parameter validation |
-| `ACESTEP_DEFAULT_MODEL` | first key of map, or `"acestep-v15-turbo"` | Name used when no `model` is specified |
-| `ACESTEP_MODELS` | *(derived from map)* | Override the `/v1/models` list explicitly (comma-separated names) |
-
-> **Note**: `ACESTEP_MODEL_MAP` is the canonical source for multi-model setup. `ACESTEP_MODELS` and `ACESTEP_DEFAULT_MODEL` are optional overrides.
+| `ACESTEP_MODEL_MAP` | `{}` | JSON map of `{"name": "file.gguf", …}` — explicit name→path mapping. Drives both `/v1/models` and per-request `model` validation. Takes precedence over directory scan. |
+| `ACESTEP_DEFAULT_MODEL` | first map key / first scanned file / `"acestep-v15-turbo"` | Name used when no `model` is specified per-request |
+| `ACESTEP_MODELS` | *(all discovered)* | Comma-separated **filter/gate** applied to the discovered list (map keys or scanned filenames). Only names in this list are returned by `/v1/models`. |
+
+> **Recommended minimal setup** (no `ACESTEP_MODEL_MAP` needed):
+> ```bash
+> export ACESTEP_MODELS_DIR="$HOME/models/acestep"
+> # /v1/models will automatically list every .gguf file in that directory
+> ```
 
 ### Queue / Storage
 

src/config.ts

@@ -1,5 +1,5 @@
 /** Env-based config. Binaries: https://github.com/audiohacking/acestep.cpp/releases/tag/v0.0.3 */
-import { resolveModelFile, resolveModelMapPaths, resolveAcestepBinDir } from "./paths";
+import { resolveModelFile, resolveModelMapPaths, resolveAcestepBinDir, listGgufFiles } from "./paths";
 
 function parseModelMap(raw: string): Record<string, string> {
   if (!raw.trim()) return {};
@@ -85,32 +85,74 @@ export const config = {
    * List of available model names shown by GET /v1/models.
    *
    * Resolution order:
-   * 1. `ACESTEP_MODELS` (comma-separated) — explicit override.
-   * 2. Keys of `ACESTEP_MODEL_MAP` — derived automatically when a map is configured.
-   * 3. `[defaultModel]` — single-model fallback so the endpoint always returns something.
+   * 1. `ACESTEP_MODEL_MAP` keys — when an explicit name→path map is configured.
+   * 2. `.gguf` files found in `modelsDir` — discovered at runtime.
+   * 3. Fallback: `ACESTEP_MODELS` list as-is (no dir to scan), or `[defaultModel]`.
+   *
+   * `ACESTEP_MODELS` (comma-separated) acts as a **filter/gate** on the discovered list
+   * (steps 1 & 2). When set, only names present in that list are returned.
    */
   get modelsList(): string[] {
-    const explicit = process.env.ACESTEP_MODELS?.trim();
-    if (explicit) return explicit.split(",").map((s) => s.trim()).filter(Boolean);
+    const filterRaw = process.env.ACESTEP_MODELS?.trim();
+    const allowed = filterRaw ? new Set(filterRaw.split(",").map((s) => s.trim()).filter(Boolean)) : null;
+
+    // 1. Explicit MODEL_MAP: use map keys
     const mapKeys = Object.keys(getModelMapRaw());
-    if (mapKeys.length > 0) return mapKeys;
+    if (mapKeys.length > 0) {
+      return allowed ? mapKeys.filter((k) => allowed.has(k)) : mapKeys;
+    }
+
+    // 2. Scan models directory for .gguf files
+    const dir = this.modelsDir;
+    if (dir) {
+      const scanned = listGgufFiles(dir);
+      if (scanned.length > 0) {
+        return allowed ? scanned.filter((n) => allowed.has(n)) : scanned;
+      }
+    }
+
+    // 3. Fallback: use ACESTEP_MODELS list directly, or [defaultModel]
+    if (allowed) return [...allowed];
     const def = this.defaultModel;
     return def ? [def] : [];
   },
 
+  /**
+   * Model name → resolved file path map derived from scanning `modelsDir`.
+   * Used by `resolveDitPath` so per-request `model` accepts discovered filenames.
+   * Only populated when `ACESTEP_MODEL_MAP` is not set.
+   */
+  get scannedModelMap(): Record<string, string> {
+    if (Object.keys(getModelMapRaw()).length > 0) return {};
+    const dir = this.modelsDir;
+    if (!dir) return {};
+    const files = listGgufFiles(dir);
+    const out: Record<string, string> = {};
+    for (const f of files) {
+      out[f] = resolveModelFile(f);
+    }
+    return out;
+  },
+
   /**
    * The default model name (used when no `model` is specified per request).
    *
    * Resolution order:
    * 1. `ACESTEP_DEFAULT_MODEL` — explicit override.
    * 2. First key of `ACESTEP_MODEL_MAP` — when a map is configured.
-   * 3. `"acestep-v15-turbo"` — hardcoded fallback label.
+   * 3. First `.gguf` file in `modelsDir` — when the directory is scanned.
+   * 4. `"acestep-v15-turbo"` — hardcoded fallback label.
    */
   get defaultModel(): string {
     const explicit = process.env.ACESTEP_DEFAULT_MODEL?.trim();
     if (explicit) return explicit;
     const mapKeys = Object.keys(getModelMapRaw());
-    if (mapKeys.length > 0) return mapKeys[0] as string;
+    if (mapKeys.length > 0) return mapKeys[0];
+    const dir = this.modelsDir;
+    if (dir) {
+      const scanned = listGgufFiles(dir);
+      if (scanned.length > 0) return scanned[0];
+    }
     return "acestep-v15-turbo";
   },
 

src/paths.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "fs";
+import { existsSync, readdirSync } from "fs";
 import { dirname, join, resolve, isAbsolute } from "path";
 
 /**
@@ -74,3 +74,18 @@ export function resolveReferenceAudioPath(pathOrName: string): string {
   if (isAbsolute(p)) return p;
   return join(resolve(getResourceRoot()), p);
 }
+
+/**
+ * Returns basenames of `.gguf` files found in `dir`, sorted alphabetically.
+ * Returns `[]` if `dir` is empty, does not exist, or cannot be read.
+ */
+export function listGgufFiles(dir: string): string[] {
+  if (!dir) return [];
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.toLowerCase().endsWith(".gguf"))
+      .sort();
+  } catch {
+    return [];
+  }
+}

src/worker.ts

@@ -106,9 +106,11 @@ export function resolveLmPath(body: Record<string, unknown>): string {
 
 export function resolveDitPath(body: Record<string, unknown>): string {
   const modelName = typeof body.model === "string" ? body.model.trim() : "";
-  if (modelName && config.modelMap[modelName]) return config.modelMap[modelName];
-  if (modelName && !config.modelMap[modelName]) {
-    throw new Error(`Unknown model "${modelName}". Set ACESTEP_MODEL_MAP JSON or use a configured name.`);
+  if (modelName) {
+    if (config.modelMap[modelName]) return config.modelMap[modelName];
+    const scanned = config.scannedModelMap;
+    if (scanned[modelName]) return scanned[modelName];
+    throw new Error(`Unknown model "${modelName}". Use GET /v1/models to list available models.`);
   }
   if (!config.ditModelPath) throw new Error("ACESTEP_DIT_MODEL or ACESTEP_CONFIG_PATH not set");
   return config.ditModelPath;