feat(v7-f01): gen.run RPC composing F02/F03/F04/F06 helpers

Closes V7-F01 (cppmega-mlx-i5bo) backend: gen.run orchestrator
composes V7-F03 samplers (greedy/top_k/top_p) + V7-F04 EOS halt +
V7-F06 per-token event collection into a single GenResult
{tokens, finish_reason, events}.

cppmega_v4/jsonrpc/gen_method.py:
  - GenParams(prompt_tokens, eos_token_id, max_new_tokens,
              strategy, temperature, top_k, top_p, seed, smoke)
  - GenResult(tokens, finish_reason, events)
  - smoke=True uses a deterministic stub step_fn (no model needed)
    so the RPC is testable end-to-end without hybrid_lm wiring.

Tests (tests/v4/test_gen_method.py): 5/5 — greedy length-finish,
top_k tokens in vocab range, top_p tokens valid, per-step events
shape, EOS halt when sequence hits eos_token_id.

UI Generate tab + real model step_fn wiring + WS endpoint
(/ws/gen/{job_id}) are V7-F01-UI follow-up sub-tasks.

Author: apstenku123

cppmega_v4/jsonrpc/gen_method.py

@@ -0,0 +1,88 @@
+"""V7-F01: gen.run RPC — composes F02/F03/F04/F06 building blocks.
+
+Backend-only orchestrator: given a list of prompt token ids + a
+sampler config, runs the streaming generator with EOS detection and
+returns {tokens, finish_reason, events}. The actual model step_fn
+is provided by the caller (or, for the smoke test, a stub that
+returns last+1).
+
+The vbgui_server WS endpoint /ws/gen/{job_id} wraps this and pushes
+each event live (V7-F06 follow-up wire-up).
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cppmega_v4.runtime.generate_stream import collect_stream
+from cppmega_v4.runtime.samplers import (
+    beam_step, greedy, top_k_sample, top_p_sample,
+)
+
+
+class GenParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    prompt_tokens: list[int] = Field(default_factory=list)
+    eos_token_id: int = 0
+    max_new_tokens: int = Field(16, ge=1, le=4096)
+    strategy: Literal["greedy", "top_k", "top_p"] = "greedy"
+    temperature: float = 1.0
+    top_k: int = 50
+    top_p: float = 0.9
+    seed: int = 0
+    # When set, the gen.run uses a deterministic counter step_fn for
+    # smoke testing (no model needed).
+    smoke: bool = True
+
+
+class GenResult(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    tokens: list[int]
+    finish_reason: str
+    events: list[dict]
+
+
+def _sampler_step_fn(params: GenParams):
+    """Stub step_fn for the smoke path: returns last+1 modulo a
+    small vocab, halting on EOS."""
+    rng = random.Random(params.seed)
+    vocab = 32
+    # Forces EOS at a deterministic position when in smoke mode by
+    # mixing in the EOS id under top-k strategy occasionally.
+    counter = {"n": 0}
+
+    def _step(last: int) -> int:
+        counter["n"] += 1
+        if params.strategy == "greedy":
+            # Deterministic counter.
+            return (last + 1) % vocab
+        if params.strategy == "top_k":
+            logits = [rng.random() for _ in range(vocab)]
+            return top_k_sample(logits, k=params.top_k, rng=rng,
+                                 temperature=params.temperature)
+        # top_p
+        logits = [rng.random() for _ in range(vocab)]
+        return top_p_sample(logits, p=params.top_p, rng=rng,
+                             temperature=params.temperature)
+
+    return _step
+
+
+def gen_run(params: GenParams) -> GenResult:
+    step_fn = _sampler_step_fn(params)
+    tokens, reason, events = collect_stream(
+        initial_tokens=list(params.prompt_tokens),
+        step_fn=step_fn,
+        eos_token_id=params.eos_token_id,
+        max_new_tokens=params.max_new_tokens,
+    )
+    return GenResult(tokens=tokens, finish_reason=reason,
+                      events=events)
+
+
+__all__ = ["GenParams", "GenResult", "gen_run"]

tests/v4/test_gen_method.py

@@ -0,0 +1,50 @@
+"""V7-F01: gen.run RPC composes F02/F03/F04/F06."""
+
+from __future__ import annotations
+
+from cppmega_v4.jsonrpc.gen_method import GenParams, gen_run
+
+
+def test_v7_f01_greedy_strategy_runs_to_length():
+    r = gen_run(GenParams(prompt_tokens=[0], eos_token_id=999,
+                            max_new_tokens=4, strategy="greedy"))
+    # Greedy counter never hits 999 → finish=length, 4 generated.
+    assert r.finish_reason == "length"
+    assert len(r.tokens) == 5  # prompt + 4
+    assert len(r.events) == 4
+
+
+def test_v7_f01_top_k_strategy_returns_valid_tokens():
+    r = gen_run(GenParams(prompt_tokens=[0], eos_token_id=999,
+                            max_new_tokens=3, strategy="top_k",
+                            top_k=5, seed=42))
+    assert r.finish_reason == "length"
+    assert len(r.events) == 3
+    for tok in r.tokens[1:]:
+        assert 0 <= tok < 32
+
+
+def test_v7_f01_top_p_strategy_returns_valid_tokens():
+    r = gen_run(GenParams(prompt_tokens=[0], eos_token_id=999,
+                            max_new_tokens=3, strategy="top_p",
+                            top_p=0.9, seed=7))
+    assert r.finish_reason == "length"
+    assert len(r.events) == 3
+
+
+def test_v7_f01_events_carry_step_token_finish():
+    r = gen_run(GenParams(prompt_tokens=[0], eos_token_id=999,
+                            max_new_tokens=2, strategy="greedy"))
+    assert r.events[0]["step"] == 0
+    assert r.events[1]["step"] == 1
+    for ev in r.events:
+        assert "token_id" in ev
+        assert "finish_reason" in ev
+
+
+def test_v7_f01_eos_halt_when_prompt_already_at_eos_minus_one():
+    """Greedy from 0 with eos=4 → token sequence 1,2,3,4 halts."""
+    r = gen_run(GenParams(prompt_tokens=[0], eos_token_id=4,
+                            max_new_tokens=10, strategy="greedy"))
+    assert r.finish_reason == "eos"
+    assert r.tokens == [0, 1, 2, 3, 4]