feat: add fine-tunes preview endpoint

Stainless-Generated-From: ed7c75d5257a7bbf495683f9fede1f07f2eeacc1

Author: stlc-workflow-app[bot]

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 140
+configured_endpoints: 141

api.md

@@ -425,6 +425,8 @@ Types:
 
 ```python
 from together.types import (
+    FineTunePreviewResponse,
+    FineTunePreviewRow,
     FinetuneEvent,
     FinetuneEventType,
     FinetuneModelLimits,
@@ -452,6 +454,7 @@ Methods:
 - <code title="get /fine-tunes/{id}/events">client.fine_tuning.<a href="./src/together/resources/fine_tuning.py">list_events</a>(id) -> <a href="./src/together/types/fine_tuning_list_events_response.py">FineTuningListEventsResponse</a></code>
 - <code title="get /fine-tunes/{id}/metrics">client.fine_tuning.<a href="./src/together/resources/fine_tuning.py">list_metrics</a>(id, \*\*<a href="src/together/types/fine_tuning_list_metrics_params.py">params</a>) -> <a href="./src/together/types/fine_tuning_list_metrics_response.py">FineTuningListMetricsResponse</a></code>
 - <code title="get /fine-tunes/models/limits">client.fine_tuning.<a href="./src/together/resources/fine_tuning.py">model_limits</a>(\*\*<a href="src/together/types/fine_tuning_model_limits_params.py">params</a>) -> <a href="./src/together/types/finetune_model_limits.py">FinetuneModelLimits</a></code>
+- <code title="post /fine-tunes/preview">client.fine_tuning.<a href="./src/together/resources/fine_tuning.py">preview</a>(\*\*<a href="src/together/types/fine_tuning_preview_params.py">params</a>) -> <a href="./src/together/types/fine_tune_preview_response.py">FineTunePreviewResponse</a></code>
 
 # CodeInterpreter
 

scripts/mock

@@ -12,6 +12,7 @@
 from ..types import (
     fine_tuning_delete_params,
     fine_tuning_content_params,
+    fine_tuning_preview_params,
     fine_tuning_list_metrics_params,
     fine_tuning_model_limits_params,
     fine_tuning_estimate_price_params,
@@ -40,6 +41,7 @@
 from ..lib.resources.fine_tuning import create_finetune_request
 from ..types.finetune_model_limits import FinetuneModelLimits
 from ..types.fine_tuning_list_response import FineTuningListResponse
+from ..types.fine_tune_preview_response import FineTunePreviewResponse
 from ..types.fine_tuning_cancel_response import FineTuningCancelResponse
 from ..types.fine_tuning_delete_response import FineTuningDeleteResponse
 from ..types.fine_tuning_list_events_response import FineTuningListEventsResponse
@@ -748,6 +750,64 @@ def model_limits(
             cast_to=FinetuneModelLimits,
         )
 
+    def preview(
+        self,
+        *,
+        model: str,
+        training_file: str,
+        top_k: int | Omit = omit,
+        train_on_inputs: bool | Omit = omit,
+        training_method: Literal["sft"] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> FineTunePreviewResponse:
+        """
+        Preview how sampled rows from a fine-tuning training file will be tokenized
+        before packing.
+
+        Args:
+          model: Name of the base model whose tokenizer and chat template will be used.
+
+          training_file: File-ID of the uploaded JSONL training file to sample for preview.
+
+          top_k: Maximum number of rows from the start of the training file to tokenize.
+
+          train_on_inputs: Whether prompt or user-message tokens should contribute to training loss in the
+              preview.
+
+          training_method: Fine-tuning method to preview. Only supervised fine-tuning is currently
+              supported.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._post(
+            "/fine-tunes/preview",
+            body=maybe_transform(
+                {
+                    "model": model,
+                    "training_file": training_file,
+                    "top_k": top_k,
+                    "train_on_inputs": train_on_inputs,
+                    "training_method": training_method,
+                },
+                fine_tuning_preview_params.FineTuningPreviewParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=FineTunePreviewResponse,
+        )
+
 
 class AsyncFineTuningResource(AsyncAPIResource):
     @cached_property
@@ -1439,6 +1499,64 @@ async def model_limits(
             cast_to=FinetuneModelLimits,
         )
 
+    async def preview(
+        self,
+        *,
+        model: str,
+        training_file: str,
+        top_k: int | Omit = omit,
+        train_on_inputs: bool | Omit = omit,
+        training_method: Literal["sft"] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> FineTunePreviewResponse:
+        """
+        Preview how sampled rows from a fine-tuning training file will be tokenized
+        before packing.
+
+        Args:
+          model: Name of the base model whose tokenizer and chat template will be used.
+
+          training_file: File-ID of the uploaded JSONL training file to sample for preview.
+
+          top_k: Maximum number of rows from the start of the training file to tokenize.
+
+          train_on_inputs: Whether prompt or user-message tokens should contribute to training loss in the
+              preview.
+
+          training_method: Fine-tuning method to preview. Only supervised fine-tuning is currently
+              supported.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._post(
+            "/fine-tunes/preview",
+            body=await async_maybe_transform(
+                {
+                    "model": model,
+                    "training_file": training_file,
+                    "top_k": top_k,
+                    "train_on_inputs": train_on_inputs,
+                    "training_method": training_method,
+                },
+                fine_tuning_preview_params.FineTuningPreviewParams,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=FineTunePreviewResponse,
+        )
+
 
 class FineTuningResourceWithRawResponse:
     def __init__(self, fine_tuning: FineTuningResource) -> None:
@@ -1475,6 +1593,9 @@ def __init__(self, fine_tuning: FineTuningResource) -> None:
         self.model_limits = to_raw_response_wrapper(
             fine_tuning.model_limits,
         )
+        self.preview = to_raw_response_wrapper(
+            fine_tuning.preview,
+        )
 
 
 class AsyncFineTuningResourceWithRawResponse:
@@ -1512,6 +1633,9 @@ def __init__(self, fine_tuning: AsyncFineTuningResource) -> None:
         self.model_limits = async_to_raw_response_wrapper(
             fine_tuning.model_limits,
         )
+        self.preview = async_to_raw_response_wrapper(
+            fine_tuning.preview,
+        )
 
 
 class FineTuningResourceWithStreamingResponse:
@@ -1549,6 +1673,9 @@ def __init__(self, fine_tuning: FineTuningResource) -> None:
         self.model_limits = to_streamed_response_wrapper(
             fine_tuning.model_limits,
         )
+        self.preview = to_streamed_response_wrapper(
+            fine_tuning.preview,
+        )
 
 
 class AsyncFineTuningResourceWithStreamingResponse:
@@ -1586,3 +1713,6 @@ def __init__(self, fine_tuning: AsyncFineTuningResource) -> None:
         self.model_limits = async_to_streamed_response_wrapper(
             fine_tuning.model_limits,
         )
+        self.preview = async_to_streamed_response_wrapper(
+            fine_tuning.preview,
+        )

src/together/resources/fine_tuning.py

@@ -43,6 +43,7 @@
 from .file_delete_response import FileDeleteResponse as FileDeleteResponse
 from .rerank_create_params import RerankCreateParams as RerankCreateParams
 from .batch_create_response import BatchCreateResponse as BatchCreateResponse
+from .fine_tune_preview_row import FineTunePreviewRow as FineTunePreviewRow
 from .finetune_model_limits import FinetuneModelLimits as FinetuneModelLimits
 from .image_generate_params import ImageGenerateParams as ImageGenerateParams
 from .model_upload_response import ModelUploadResponse as ModelUploadResponse
@@ -55,7 +56,9 @@
 from .audio_speech_stream_chunk import AudioSpeechStreamChunk as AudioSpeechStreamChunk
 from .fine_tuning_delete_params import FineTuningDeleteParams as FineTuningDeleteParams
 from .fine_tuning_list_response import FineTuningListResponse as FineTuningListResponse
+from .fine_tune_preview_response import FineTunePreviewResponse as FineTunePreviewResponse
 from .fine_tuning_content_params import FineTuningContentParams as FineTuningContentParams
+from .fine_tuning_preview_params import FineTuningPreviewParams as FineTuningPreviewParams
 from .fine_tuning_cancel_response import FineTuningCancelResponse as FineTuningCancelResponse
 from .fine_tuning_delete_response import FineTuningDeleteResponse as FineTuningDeleteResponse
 from .endpoint_list_hardware_params import EndpointListHardwareParams as EndpointListHardwareParams

src/together/types/__init__.py

@@ -0,0 +1,28 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List
+from typing_extensions import Literal
+
+from .._models import BaseModel
+from .fine_tune_preview_row import FineTunePreviewRow
+
+__all__ = ["FineTunePreviewResponse"]
+
+
+class FineTunePreviewResponse(BaseModel):
+    """Tokenized preview for sampled rows from a fine-tuning training file."""
+
+    dataset_format: Literal["general", "conversation", "instruction"]
+    """Detected SFT dataset format for the sampled rows."""
+
+    max_seq_length: int
+    """Maximum sequence length configured for the requested model."""
+
+    model: str
+    """Name of the base model used to tokenize the sampled rows."""
+
+    rows: List[FineTunePreviewRow]
+    """Tokenized preview rows, in the same order as the sampled training file rows."""
+
+    train_on_inputs: bool
+    """Whether prompt or user-message tokens contribute to training loss."""

src/together/types/fine_tune_preview_response.py

@@ -0,0 +1,32 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List
+
+from .._models import BaseModel
+
+__all__ = ["FineTunePreviewRow"]
+
+
+class FineTunePreviewRow(BaseModel):
+    """Tokenized representation of one sampled fine-tuning row."""
+
+    input_ids: List[int]
+    """Token IDs produced for the sampled row."""
+
+    labels: List[int]
+    """Training labels for each token; masked tokens use -100."""
+
+    num_tokens: int
+    """Total number of tokens in the preview row after truncation."""
+
+    num_trained_tokens: int
+    """Number of tokens in the row that contribute to training loss."""
+
+    tokens: List[str]
+    """Raw token strings produced for the sampled row."""
+
+    trained_spans: List[List[int]]
+    """Half-open token index ranges that contribute to training loss."""
+
+    truncated: bool
+    """Whether the row was truncated to the model maximum sequence length."""

src/together/types/fine_tune_preview_row.py

@@ -0,0 +1,30 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, TypedDict
+
+__all__ = ["FineTuningPreviewParams"]
+
+
+class FineTuningPreviewParams(TypedDict, total=False):
+    model: Required[str]
+    """Name of the base model whose tokenizer and chat template will be used."""
+
+    training_file: Required[str]
+    """File-ID of the uploaded JSONL training file to sample for preview."""
+
+    top_k: int
+    """Maximum number of rows from the start of the training file to tokenize."""
+
+    train_on_inputs: bool
+    """
+    Whether prompt or user-message tokens should contribute to training loss in the
+    preview.
+    """
+
+    training_method: Literal["sft"]
+    """Fine-tuning method to preview.
+
+    Only supervised fine-tuning is currently supported.
+    """