freesolo-flash-dev 1.4.5__tar.gz → 1.4.6__tar.gz

{freesolo_flash_dev-1.4.5 → freesolo_flash_dev-1.4.6}/CHANGELOG.md

@@ -35,6 +35,13 @@ This file starts at 1.1.35. Earlier releases are not reconstructed here; use
   run recovery, deployment recovery and the background loops; a plane started beside it serves
   HTTP and leaves new runs queued for the holder until the old plane exits.
 
+- SFT rows accept `tools`: OpenAI-style function declarations, validated and normalized exactly
+  as a chat request's `tools`. They are rendered through the chat template into every training
+  view of the row (transcript, prompt boundary and loss-mask probe), so a tool-calling adapter
+  trains on the prompt it is served with. Previously every SFT row rendered without tools, so for
+  Qwen3.5 the `# Tools` block that serving prepends to the system turn never appeared in
+  training. The block is prompt only, so supervised tokens are unchanged. Rows without `tools`
+  render as before; `tools` on an image-bearing row is refused.
 - Custom training rows accept a rectangular `target_tokens` matrix, `[len(tokens)-1, K]`
   with K up to 64, scoring K tokens at every position instead of the next token. `weights`
   then has the same shape and logprobs come back with it, so `forward_backward` computes

{freesolo_flash_dev-1.4.5 → freesolo_flash_dev-1.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.4.5
+Version: 1.4.6
 Summary: Flash — managed LoRA post-training (SFT/GRPO) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash
@@ -352,8 +352,14 @@ The estimate tokenizes raw `input`/`output` fields plus the statically readable
 contract. SFT rows can instead supply `prompt_messages`, a nonempty chat-message list
 that is authoritative for both profiling and training. This preserves stored multi-turn
 histories and screenshot blocks; image-bearing transcripts use unpacked execution.
-The row still requires `input` for dataset identity. Environment-added prompts, few-shot
-examples, tool schemas, filters, and transformations are **not** executed, so real training
+The row still requires `input` for dataset identity. A row for a tool-calling agent can also
+supply `tools`, the same OpenAI-style function declarations a chat request sends. Flash
+validates them as serving does and renders them into the row's prompt through the chat template,
+so the adapter trains on the prompt it is served with: Qwen3.5, for example, prepends a
+`# Tools` block to the system turn. The block is prompt, not target, so it lengthens rows
+without adding supervised tokens. Without `tools`, a row trained for a tool-calling deployment
+never sees that block. Environment-added prompts, few-shot
+examples, environment-built tool schemas, filters, and transformations are **not** executed, so real training
 can retain fewer rows, truncate more often, and cost more than the estimate. If no readable dataset exists, cost, dry-run, and
 submit all fail before GPU allocation rather than billing a profiling run.
 

{freesolo_flash_dev-1.4.5 → freesolo_flash_dev-1.4.6}/README.md

@@ -252,8 +252,14 @@ The estimate tokenizes raw `input`/`output` fields plus the statically readable
 contract. SFT rows can instead supply `prompt_messages`, a nonempty chat-message list
 that is authoritative for both profiling and training. This preserves stored multi-turn
 histories and screenshot blocks; image-bearing transcripts use unpacked execution.
-The row still requires `input` for dataset identity. Environment-added prompts, few-shot
-examples, tool schemas, filters, and transformations are **not** executed, so real training
+The row still requires `input` for dataset identity. A row for a tool-calling agent can also
+supply `tools`, the same OpenAI-style function declarations a chat request sends. Flash
+validates them as serving does and renders them into the row's prompt through the chat template,
+so the adapter trains on the prompt it is served with: Qwen3.5, for example, prepends a
+`# Tools` block to the system turn. The block is prompt, not target, so it lengthens rows
+without adding supervised tokens. Without `tools`, a row trained for a tool-calling deployment
+never sees that block. Environment-added prompts, few-shot
+examples, environment-built tool schemas, filters, and transformations are **not** executed, so real training
 can retain fewer rows, truncate more often, and cost more than the estimate. If no readable dataset exists, cost, dry-run, and
 submit all fail before GPU allocation rather than billing a profiling run.
 

freesolo_flash_dev-1.4.6/flash/engine/profiling/sft_tools.py

@@ -0,0 +1,49 @@
+"""tool declarations an SFT row trains against.
+
+A tool-calling agent is served with ``tools=``, and the chat template renders those declarations
+into the prompt (Qwen3.5 prepends a ``# Tools`` block to the system turn). A row rendered without
+them trains on a prompt the deployed adapter never sees. A row may therefore carry ``tools`` -- the
+same per-example field as OpenAI fine-tuning data -- which is validated and normalized exactly as a
+chat request's ``tools`` are (``text_tokenizer`` renders ``tools_wire(normalize_tools(...))``), then
+rendered into every training view of the row. A row without ``tools`` renders as before.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from flash.serve.request.tool_calls import normalize_tools, tools_wire
+
+
+def sft_row_tools(example) -> list[dict[str, Any]] | None:
+    """The row's tools in the form serving renders them, or None when it declares none."""
+    if not isinstance(example, dict) or example.get("tools") is None:
+        return None
+    try:
+        return tools_wire(normalize_tools(example["tools"]))
+    except ValueError as exc:
+        raise ValueError(f"sft tools: {exc}") from exc
+
+
+def sft_template_kwargs(thinking: bool, tools: list[dict[str, Any]] | None) -> dict[str, Any]:
+    """Chat-template kwargs for every training view of a row.
+
+    The transcript, the prompt boundary, the reasoning probe and the loss mask's field probe all
+    render with these, so the supervised tokens are located in exactly the text that is trained on.
+    Without tools this is the pre-existing thinking-only render.
+    """
+    kwargs: dict[str, Any] = {"enable_thinking": thinking, "preserve_thinking": False}
+    if tools is not None:
+        kwargs["tools"] = tools
+    return kwargs
+
+
+def reject_image_row_tools(example, *, image_bearing: bool) -> None:
+    """Refuse tools on an image row before any tokenizer or processor is resolved.
+
+    The image pipeline tokenizes through the processor's own render, so accepting them would silently
+    train the row without the declarations it was given. Validating here, while rows are collected,
+    also makes a malformed declaration fail with its own message rather than as a capability error.
+    """
+    if sft_row_tools(example) is not None and image_bearing:
+        raise ValueError("sft tools are not supported on image-bearing rows")

{freesolo_flash_dev-1.4.5 → freesolo_flash_dev-1.4.6}/flash/engine/profiling/sft_workload.py

@@ -15,6 +15,7 @@ from flash.content.multimodal import NormalizedImages
 from flash.content.thinking import messages_for_chat_template
 from flash.engine.plan.recipe import RECIPE
 from flash.engine.plan.steps import resolve_update_horizon, sft_update_steps
+from flash.engine.profiling import sft_tools
 from flash.engine.profiling.sft_image_rows import (
     estimate_sft_image_row,
     process_sft_image_row,
@@ -417,22 +418,24 @@ def _text_sft_row_spec(
     max_length: int,
     row_index: int,
     multiturn: bool,
+    tools: list[dict[str, Any]] | None = None,
 ) -> tuple[str, _RowReasoning, dict[str, Any]]:
     normalized_prompt = messages_for_chat_template(prompt_messages)
     normalized_completion = messages_for_chat_template(completion_messages)
     normalized_source = [*normalized_prompt, *normalized_completion]
-    text = render_transcript(normalized_source)
+    template_kwargs = sft_tools.sft_template_kwargs(spec.thinking, tools)
+    render = partial(render_transcript, tools=tools)
+    text = render(normalized_source)
     prompt_text = tokenizer.apply_chat_template(
         normalized_prompt,
         tokenize=False,
         add_generation_prompt=True,
-        enable_thinking=spec.thinking,
-        preserve_thinking=False,
+        **template_kwargs,
     )
     reasoning = _row_reasoning(
         prompt_messages,
         completion_messages,
-        render=render_transcript,
+        render=render,
         tokenizer=tokenizer,
         max_length=max_length,
     )
@@ -444,7 +447,7 @@ def _text_sft_row_spec(
             "prompt_text": prompt_text,
             "target_messages": normalized_completion,
             "source_messages": normalized_source,
-            "template_kwargs": {"enable_thinking": spec.thinking, "preserve_thinking": False},
+            "template_kwargs": template_kwargs,
             # measurement carried alongside the row rather than in it: the parquet row is built from
             # an explicit key list below, so neither key reaches verl.
             "row_index": row_index,
@@ -481,13 +484,12 @@ def _tokenize_prompt_rows(
     # denominator. summed after filtering instead.
     reasoning_by_index: dict[int, _RowReasoning] = {}
 
-    def render_transcript(messages: list[dict]) -> str:
+    def render_transcript(messages: list[dict], tools: list[dict[str, Any]] | None = None) -> str:
         return tokenizer.apply_chat_template(
             messages_for_chat_template(messages),
             tokenize=False,
             add_generation_prompt=False,
-            enable_thinking=spec.thinking,
-            preserve_thinking=False,
+            **sft_tools.sft_template_kwargs(spec.thinking, tools),
         )
 
     for row_index, (
@@ -498,6 +500,7 @@ def _tokenize_prompt_rows(
     ) in enumerate(prompt_rows):
         has_images = record_has_images(example, prompt_messages)
         _reject_image_completion(completion_messages, image_bearing=has_images)
+        tools = sft_tools.sft_row_tools(example)
         # read before the image branch rewrites `completion_messages` to its text-only form.
         multiturn = len(completion_messages) > 1
         if multiturn:
@@ -561,6 +564,7 @@ def _tokenize_prompt_rows(
                 max_length=max_length,
                 row_index=row_index,
                 multiturn=multiturn,
+                tools=tools,
             )
             sampled_texts.append(text)
             reasoning_by_index[row_index] = reasoning
@@ -913,6 +917,9 @@ def prepare_sft_workload(
         else:
             prompt_messages = env.prompt_messages(example)
         completion_messages, coerced_scalar_output = _sft_completion_with_provenance(env, example)
+        sft_tools.reject_image_row_tools(
+            example, image_bearing=record_has_images(example, prompt_messages)
+        )
         prompt_rows.append((example, prompt_messages, completion_messages, coerced_scalar_output))
     package_root = getattr(env, "package_root", None)
     multimodal = any(

{freesolo_flash_dev-1.4.5 → freesolo_flash_dev-1.4.6}/flash/server/asgi/app.py

@@ -198,16 +198,18 @@ async def _lead_when_free(work: _LeaderWork) -> None:
     work.recovery = asyncio.ensure_future(asyncio.to_thread(work.recover))
     try:
         await asyncio.shield(work.recovery)
+        # Starting the loops can fail too, e.g. the deployment-job pool is full of jobs the plane
+        # accepted in standby. Leave standby only once the holder's work is actually running.
+        work.start()
     except asyncio.CancelledError:
         raise
     except Exception:
-        # A lone plane fails startup when recovery fails; a takeover must not keep serving as if
-        # it led. Stop, and let the restart recover from a clean start.
-        _log.critical("control-plane recovery failed after lease takeover; stopping", exc_info=True)
+        # A lone plane fails startup when recovery or its loops fail; a takeover must not keep
+        # serving as if it led. Stop, and let the restart recover from a clean start.
+        _log.critical("control-plane takeover failed; stopping", exc_info=True)
         _stop_plane()
         return
     work.app.state.plane_standby = False
-    work.start()
 
 
 def create_app():

{freesolo_flash_dev-1.4.5 → freesolo_flash_dev-1.4.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "freesolo-flash-dev"
-version = "1.4.5"
+version = "1.4.6"
 description ="Flash — managed LoRA post-training (SFT/GRPO) for Freesolo environments, driven by the `flash` CLI"
 readme = "README.md"
 # The training and serving stack is validated on Python 3.11 and 3.12.
@@ -209,7 +209,7 @@ artifacts = ["flash/py.typed"]
 # auto-published by .github/workflows/publish-dev.yml: a push to `dev` whose version isn't yet on
 # PyPI publishes it; pushes that don't change it find it already published and no-op. So cutting a
 # dev-channel release = bump this (and [project].version) and merge to `dev`.
-version = "1.4.5"
+version = "1.4.6"
 
 [tool.pytest.ini_options]
 pythonpath = ["."]

{freesolo_flash_dev-1.4.5 → freesolo_flash_dev-1.4.6}/tests/test_plane_lease.py

@@ -192,6 +192,28 @@ def test_takeover_recovery_failure_stops_the_plane_instead_of_serving_as_leader(
         assert loops == []
 
 
+def test_takeover_that_cannot_start_its_loops_stops_the_plane(monkeypatch):
+    """Recovery succeeding is not enough: e.g. a full deployment-job pool fails the loops' start."""
+    import flash.server.asgi.app as app_mod
+
+    recovered, stopped = [], threading.Event()
+    _stub_lifespan(monkeypatch, recovered)
+
+    def pool_full(self):
+        raise RuntimeError("deployment job capacity reached")
+
+    monkeypatch.setattr(app_mod, "_stop_plane", stopped.set)
+    monkeypatch.setattr(app_mod._LeaderWork, "start", pool_full)
+    old_plane = _hold_elsewhere()
+
+    with TestClient(app_mod.create_app()) as client:
+        _release_elsewhere(old_plane)
+        assert stopped.wait(10)
+        assert recovered == ["runs", "deployments"]
+        # never leaves standby, so submissions are not launched by a plane without its loops.
+        assert client.app.state.plane_standby is True
+
+
 def test_shutdown_waits_for_takeover_recovery_before_releasing_the_lease(monkeypatch):
     import flash.server.asgi.app as app_mod
     import flash.server.platform.runtime as server_runtime

freesolo_flash_dev-1.4.6/tests/test_sft_tools.py

@@ -0,0 +1,264 @@
+"""SFT rows that carry ``tools`` train on the prompt the served adapter actually sees.
+
+Serving renders a chat request's ``tools`` into the prompt (``text_tokenizer`` passes
+``tools_wire(normalize_tools(...))`` to the chat template). An SFT row rendered without them trains
+on a different prompt than the deployed adapter receives; for Qwen3.5 the difference is a whole
+``# Tools`` block at the top of the system turn.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import replace
+from typing import ClassVar
+
+import pytest
+
+from flash.core.spec import EnvironmentSpec, JobSpec, TrainSpec
+from flash.engine.profiling.sft_workload import prepare_sft_workload
+from flash.engine.profiling.workload_profile import sft_profile_input_digest
+from flash.serve.request.tool_calls import normalize_tools, tools_wire
+from tests.test_sft_workload import FakeTokenizer
+
+
+def _spec(max_context_tokens: int = 256) -> JobSpec:
+    # a tool block is long; the shared fixture's 32-token cap would truncate every target away
+    spec = JobSpec(
+        model="test/model",
+        model_revision="a" * 40,
+        algorithm="sft",
+        environment=EnvironmentSpec(id="team/example", resolved_sha="b" * 40),
+        train=TrainSpec(epochs=1, batch_size=1, max_context_tokens=max_context_tokens),
+        seed=7,
+    )
+    digest = sft_profile_input_digest(
+        spec, tokenizer_revision=spec.model_revision, producer_version="1.2.3"
+    )
+    return replace(
+        spec, workload_profile_input_digest=digest, workload_profile_producer_version="1.2.3"
+    )
+
+
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "find_user_id_by_email",
+            "description": "Find a user id by email.",
+            "parameters": {
+                "type": "object",
+                "properties": {"email": {"type": "string"}},
+                "required": ["email"],
+                "additionalProperties": False,
+            },
+        },
+    }
+]
+
+
+class RecordingToolTokenizer(FakeTokenizer):
+    """Renders declared tools into the text and records every render's tools argument."""
+
+    calls: ClassVar[list[object]] = []
+
+    def apply_chat_template(
+        self, messages, *, tokenize, add_generation_prompt, enable_thinking, **kwargs
+    ):
+        tools = kwargs.get("tools", "<absent>")
+        type(self).calls.append(tools)
+        text = super().apply_chat_template(
+            messages,
+            tokenize=tokenize,
+            add_generation_prompt=add_generation_prompt,
+            enable_thinking=enable_thinking,
+        )
+        if tools != "<absent>" and tools is not None:
+            names = ",".join(tool["function"]["name"] for tool in tools)
+            text = f"[tools:{names}]" + text
+        return text
+
+
+class ToolRowEnvironment:
+    multi_turn = False
+    package_root = None
+
+    def __init__(self, rows):
+        self._rows = rows
+
+    def dataset(self):
+        return list(self._rows)
+
+    def prompt_messages(self, row):
+        raise AssertionError("stored prompt_messages must be used")
+
+    def sft_completion(self, row):
+        return [{"role": "assistant", "content": row["answer"]}]
+
+
+def _row(**extra):
+    return {
+        "input": "cancel",
+        "prompt_messages": [
+            {"role": "system", "content": "policy"},
+            {"role": "user", "content": "cancel #W1"},
+        ],
+        "answer": "email?",
+        **extra,
+    }
+
+
+def _prepare(rows):
+    RecordingToolTokenizer.calls = []
+    return prepare_sft_workload(
+        _spec(),
+        ToolRowEnvironment(rows),
+        tokenizer_loader=lambda *_: RecordingToolTokenizer(),
+        producer_version="1.2.3",
+        packing_support=lambda *_: ("pure-attention", True),
+    )
+
+
+def test_a_row_with_tools_renders_them_in_every_training_view() -> None:
+    prepared = _prepare([_row(tools=TOOLS)])
+
+    expected = tools_wire(normalize_tools(TOOLS))
+    # transcript, prompt boundary and any mask probe: none may render the row without its tools
+    assert RecordingToolTokenizer.calls
+    assert all(call == expected for call in RecordingToolTokenizer.calls)
+    assert prepared.sampled_texts == ["[tools:find_user_id_by_email]policycancel #W1email?"]
+    assert prepared.profile.retained_examples == 1
+    # the tool block is prompt, not target: it lengthens the row but adds no supervised token
+    plain = _prepare([_row()])
+    assert len(prepared.rows[0]["input_ids"]) > len(plain.rows[0]["input_ids"])
+    assert sum(prepared.rows[0]["loss_mask"]) == sum(plain.rows[0]["loss_mask"])
+
+
+def test_a_row_without_tools_renders_exactly_as_before() -> None:
+    prepared = _prepare([_row()])
+
+    assert RecordingToolTokenizer.calls
+    assert all(call == "<absent>" for call in RecordingToolTokenizer.calls)
+    assert prepared.sampled_texts == ["policycancel #W1email?"]
+
+
+def test_explicit_null_tools_is_the_same_as_no_tools() -> None:
+    _prepare([_row(tools=None)])
+
+    assert all(call == "<absent>" for call in RecordingToolTokenizer.calls)
+
+
+def test_tools_are_normalized_as_serving_normalizes_a_request() -> None:
+    # key order in the authored declaration must not change the rendered (and trained) prompt
+    reordered = [
+        {
+            "function": {
+                "parameters": TOOLS[0]["function"]["parameters"],
+                "description": TOOLS[0]["function"]["description"],
+                "name": TOOLS[0]["function"]["name"],
+            },
+            "type": "function",
+        }
+    ]
+    _prepare([_row(tools=reordered)])
+    reordered_calls = list(RecordingToolTokenizer.calls)
+    _prepare([_row(tools=TOOLS)])
+
+    assert json.dumps(reordered_calls) == json.dumps(RecordingToolTokenizer.calls)
+
+
+@pytest.mark.parametrize(
+    "tools",
+    [
+        [],
+        "find_user_id_by_email",
+        [{"type": "function"}],
+        [{"type": "retrieval", "function": TOOLS[0]["function"]}],
+    ],
+)
+def test_malformed_tools_fail_the_profile(tools) -> None:
+    with pytest.raises(ValueError, match="sft tools"):
+        _prepare([_row(tools=tools)])
+
+
+def test_tools_on_an_image_row_are_refused(monkeypatch) -> None:
+    import flash.content.multimodal as multimodal
+
+    monkeypatch.setattr(multimodal, "record_has_images", lambda *_: True)
+    with pytest.raises(ValueError, match="not supported on image-bearing rows"):
+        _prepare([_row(tools=TOOLS)])
+
+
+@pytest.mark.skipif(
+    os.environ.get("FLASH_SFT_TOOLS_TEMPLATE_LIVE") != "1",
+    reason="real Qwen3.5 template parity disabled; set FLASH_SFT_TOOLS_TEMPLATE_LIVE=1",
+)
+def test_qwen35_training_text_is_the_served_prompt_plus_the_target() -> None:
+    transformers = pytest.importorskip("transformers")
+    tokenizer = transformers.AutoTokenizer.from_pretrained(
+        "Qwen/Qwen3.5-9B", revision="c202236235762e1c871ad0ccb60c8ee5ba337b9a"
+    )
+    rows = [
+        _row(tools=TOOLS),
+        {
+            **_row(tools=TOOLS),
+            "answer": None,
+            "output": {
+                "messages": [
+                    {"role": "assistant", "content": "What is your email?"},
+                    {"role": "user", "content": "my email is a@b.c"},
+                    {
+                        "role": "assistant",
+                        "content": "",
+                        "tool_calls": [
+                            {
+                                "id": "c1",
+                                "type": "function",
+                                "function": {
+                                    "name": "find_user_id_by_email",
+                                    "arguments": {"email": "a@b.c"},
+                                },
+                            }
+                        ],
+                    },
+                ]
+            },
+        },
+    ]
+
+    class Env(ToolRowEnvironment):
+        def sft_completion(self, row):
+            if row.get("output"):
+                return row["output"]["messages"]
+            return super().sft_completion(row)
+
+    prepared = prepare_sft_workload(
+        _spec(max_context_tokens=4096),
+        Env(rows),
+        tokenizer_loader=lambda *_: tokenizer,
+        producer_version="1.2.3",
+        packing_support=lambda *_: ("pure-attention", True),
+    )
+    served_tools = tools_wire(normalize_tools(TOOLS))
+    for row, text in zip(rows, prepared.sampled_texts, strict=True):
+        completion = Env(rows).sft_completion(row)
+        served = tokenizer.apply_chat_template(
+            [*row["prompt_messages"], *completion],
+            tools=served_tools,
+            tokenize=False,
+            add_generation_prompt=False,
+            enable_thinking=False,
+        )
+        assert text == served
+        assert text.startswith("<|im_start|>system\n# Tools")
+    # the multi-turn row's loss covers the assistant turns (text and tool call) and nothing else:
+    # not the tool block, the policy or the customer's turn
+    multiturn = prepared.rows[1]
+    supervised = tokenizer.decode(
+        [t for t, m in zip(multiturn["input_ids"], multiturn["loss_mask"], strict=True) if m]
+    )
+    assert "What is your email?" in supervised
+    assert "find_user_id_by_email" in supervised
+    assert "# Tools" not in supervised
+    assert "policy" not in supervised
+    assert "my email is" not in supervised

{freesolo_flash_dev-1.4.5 → freesolo_flash_dev-1.4.6}/uv.lock

@@ -1297,7 +1297,7 @@ wheels = [
 
 [[package]]
 name = "freesolo-flash"
-version = "1.4.5"
+version = "1.4.6"
 source = { editable = "." }
 
 [package.optional-dependencies]