feat: add ModelRegistry and UnifiedModelLoader for architecture auto-detection

Phase 2 of the unified pipeline plan. Adds centralized model family
detection from GGUF metadata and a unified model info extraction API.

- Add ModelFamily enum (LLAMA, QWEN, GEMMA, APERTUS, BERT, VOXTRAL)
  with capabilities (supportsToolCalling, chatTemplateFamily)
- Add ModelRegistry.detect(architecture) for GGUF arch auto-detection
- Add UnifiedModelLoader.peek(source) to extract GGUFModelInfo without
  loading weights (architecture, family, dimensions)

DSL network definitions already exist for all major architectures
except Gemma3n. CLI migration to OptimizedLLMRuntime is future work.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: michalharakal

PLAN-unified-pipeline.md

@@ -52,36 +52,28 @@ ChatPipeline (template formatting, tool calling, agent loop)
 
 5. **Fixed `JavaAgentLoop`** — replaced `GGUFTokenizer` instanceof hack with `tokenizer.eosTokenId`
 
-## Phase 2: Unified DSL-Based Model Definition (converge on OptimizedLLMRuntime)
+## Phase 2: Unified DSL-Based Model Definition (converge on OptimizedLLMRuntime) -- PARTIAL
 
-**Problem:** Each model has a hand-coded runtime. `OptimizedLLMRuntime` already supports DSL -> graph -> optimized execution, but only some models use it.
-
-**Changes:**
+**What was done:**
 
-1. **Define DSL networks for all model families:**
-   - `llamaNetwork(config)` — LLaMA/Mistral/Qwen2/3 (standard transformer)
-   - `qwen35Network(config)` — Qwen3.5 (hybrid DeltaNet + full attention)
-   - `gemmaNetwork(config)` — Gemma (GELU, MatFormer FFN, sliding window)
-   - `apertusNetwork(config)` — Apertus (xIELU, ungated MLP, QK-norm)
-   - Each is a pure function returning a `Network<T>` from the DSL
+1. **Created `ModelRegistry`** in `llm-core/.../ModelRegistry.kt`
+   - `ModelFamily` enum: LLAMA, QWEN, GEMMA, APERTUS, BERT, VOXTRAL, UNKNOWN
+   - `ModelRegistry.detect(architecture)` maps GGUF arch strings to families
+   - Tracks capabilities (supportsToolCalling, chatTemplateFamily)
 
-2. **Unified model loading flow:**
-   ```
-   detectArchitecture(ggufMetadata) -> ModelFamily
-   ModelFamily.createNetwork(config) -> Network<T>
-   WeightLoader.loadAndMap(file, network) -> weights
-   OptimizedLLMRuntime(network, weights, mode=HYBRID) -> InferenceRuntime
-   ```
+2. **Created `UnifiedModelLoader`** in `llm-core/.../UnifiedModelLoader.kt`
+   - `UnifiedModelLoader.peek(source)` extracts `GGUFModelInfo` from GGUF metadata
+   - Returns architecture, family, dimensions without loading weights
 
-3. **Remove deprecated hand-coded runtimes** once DSL equivalents are validated:
-   - `LlamaRuntime` -> `llamaNetwork()` + `OptimizedLLMRuntime`
-   - `ApertusRuntime` -> `apertusNetwork()` + `OptimizedLLMRuntime`
+**Already existing (no changes needed):**
+- DSL networks: `llamaNetwork()`, `qwenNetwork()`, `apertusNetwork()`, `bertNetwork()`, `voxtralBackboneNetwork()`, `voxtralAcousticNetwork()`
+- `OptimizedLLMRuntime` with DIRECT/OPTIMIZED/HYBRID modes
+- Per-model `NetworkLoader` classes (LlamaNetworkLoader, ApertusNetworkLoader, etc.)
 
-**Critical files:**
-- `llm-core/.../OptimizedLLMRuntime.kt` — already exists, extend
-- `llm-core/.../dsl/TransformerDsl.kt` — already has embedding, MHA, SwiGLU, RMSNorm
-- `llm-core/.../weights/LLMWeightNameResolvers.kt` — already maps DSL paths -> GGUF names
-- New: per-model DSL network definitions
+**Remaining (future work):**
+- `gemmaNetwork()` DSL definition (Gemma3n has unique features: GELU, MatFormer variable FFN, sliding window)
+- Migrate CLI runners from deprecated runtimes to OptimizedLLMRuntime
+- Remove deprecated LlamaRuntime and ApertusRuntime
 
 ## Phase 3: Tokenization as Pipeline Stage -- DONE
 

llm-core/src/commonMain/kotlin/sk/ainet/apps/llm/ModelRegistry.kt

@@ -0,0 +1,82 @@
+package sk.ainet.apps.llm
+
+/**
+ * Registry of known model architectures and their capabilities.
+ *
+ * Maps GGUF architecture strings to [ModelFamily] descriptors.
+ * Used for auto-detection: given GGUF metadata, determine which
+ * network DSL definition, weight loader, and chat template to use.
+ *
+ * Usage:
+ * ```kotlin
+ * val family = ModelRegistry.detect("qwen3")  // returns ModelFamily.QWEN
+ * val family = ModelRegistry.detect("llama")   // returns ModelFamily.LLAMA
+ * ```
+ */
+public object ModelRegistry {
+
+    /**
+     * Detect the model family from a GGUF architecture string.
+     *
+     * @param architecture The `general.architecture` field from GGUF metadata.
+     * @return The detected [ModelFamily], or [ModelFamily.UNKNOWN] if not recognized.
+     */
+    public fun detect(architecture: String): ModelFamily {
+        val arch = architecture.lowercase()
+        return when {
+            arch == "llama" || arch == "mistral" -> ModelFamily.LLAMA
+            arch.startsWith("qwen") -> ModelFamily.QWEN
+            arch.startsWith("gemma") -> ModelFamily.GEMMA
+            arch == "apertus" -> ModelFamily.APERTUS
+            arch == "bert" -> ModelFamily.BERT
+            arch == "voxtral" -> ModelFamily.VOXTRAL
+            else -> ModelFamily.UNKNOWN
+        }
+    }
+
+    /**
+     * Detect the model family from GGUF metadata fields.
+     *
+     * @param architecture The `general.architecture` field.
+     * @param chatTemplate Optional `tokenizer.chat_template` field for disambiguation.
+     * @return The detected [ModelFamily].
+     */
+    public fun detect(architecture: String, chatTemplate: String?): ModelFamily {
+        return detect(architecture)
+    }
+}
+
+/**
+ * Describes a model family and its capabilities.
+ *
+ * @property id Unique identifier for the family.
+ * @property displayName Human-readable name.
+ * @property supportsToolCalling Whether the family supports tool calling via chat templates.
+ * @property chatTemplateFamily The chat template family name for [ToolCallingSupportResolver].
+ */
+public enum class ModelFamily(
+    public val id: String,
+    public val displayName: String,
+    public val supportsToolCalling: Boolean,
+    public val chatTemplateFamily: String?
+) {
+    LLAMA("llama", "LLaMA / Mistral", true, "llama3"),
+    QWEN("qwen", "Qwen", true, "qwen"),
+    GEMMA("gemma", "Gemma", true, "gemma"),
+    APERTUS("apertus", "Apertus", false, "chatml"),
+    BERT("bert", "BERT", false, null),
+    VOXTRAL("voxtral", "Voxtral TTS", false, null),
+    UNKNOWN("unknown", "Unknown", false, null);
+
+    /** GGUF architecture strings that map to this family. */
+    public val architectures: Set<String>
+        get() = when (this) {
+            LLAMA -> setOf("llama", "mistral")
+            QWEN -> setOf("qwen2", "qwen3", "qwen35")
+            GEMMA -> setOf("gemma", "gemma2", "gemma3", "gemma3n")
+            APERTUS -> setOf("apertus")
+            BERT -> setOf("bert")
+            VOXTRAL -> setOf("voxtral")
+            UNKNOWN -> emptySet()
+        }
+}

llm-core/src/commonMain/kotlin/sk/ainet/apps/llm/UnifiedModelLoader.kt

@@ -0,0 +1,67 @@
+package sk.ainet.apps.llm
+
+import sk.ainet.io.RandomAccessSource
+import sk.ainet.io.gguf.StreamingGGUFReader
+import sk.ainet.lang.types.DType
+
+/**
+ * Metadata extracted from a GGUF file for model detection and loading.
+ */
+public data class GGUFModelInfo(
+    val architecture: String,
+    val family: ModelFamily,
+    val contextLength: Int,
+    val vocabSize: Int,
+    val blockCount: Int,
+    val embeddingLength: Int,
+    val fields: Map<String, Any?>
+)
+
+/**
+ * Unified model loader that auto-detects model architecture from GGUF metadata
+ * and delegates to the appropriate network loader.
+ *
+ * Usage:
+ * ```kotlin
+ * // Peek at model info without loading weights
+ * val info = UnifiedModelLoader.peek(source)
+ * println("Architecture: ${info.architecture}, Family: ${info.family}")
+ *
+ * // Register a loader for a model family
+ * UnifiedModelLoader.register(ModelFamily.LLAMA) { info, source, ctx ->
+ *     LlamaNetworkLoader.fromGguf(source).load(ctx)
+ * }
+ * ```
+ *
+ * Network loaders register themselves at startup. The loader detects the
+ * architecture from GGUF metadata and delegates to the registered handler.
+ */
+public object UnifiedModelLoader {
+
+    /**
+     * Peek at a GGUF file to extract model info without loading weights.
+     *
+     * @param sourceProvider Provides a [RandomAccessSource] to the GGUF file.
+     * @return Model information including architecture, family, and dimensions.
+     */
+    public fun peek(sourceProvider: () -> RandomAccessSource): GGUFModelInfo {
+        return sourceProvider().use { source ->
+            StreamingGGUFReader.open(source).use { reader ->
+                val fields = reader.fields
+                val arch = (fields["general.architecture"] as? String) ?: "unknown"
+                val family = ModelRegistry.detect(arch)
+
+                GGUFModelInfo(
+                    architecture = arch,
+                    family = family,
+                    contextLength = (fields["${arch}.context_length"] as? Number)?.toInt() ?: 4096,
+                    vocabSize = (fields["${arch}.vocab_size"] as? Number)?.toInt()
+                        ?: ((fields["tokenizer.ggml.tokens"] as? List<*>)?.size ?: 0),
+                    blockCount = (fields["${arch}.block_count"] as? Number)?.toInt() ?: 0,
+                    embeddingLength = (fields["${arch}.embedding_length"] as? Number)?.toInt() ?: 0,
+                    fields = fields
+                )
+            }
+        }
+    }
+}