together 1.4.1__py3-none-any.whl → 1.4.5__py3-none-any.whl

together/cli/api/finetune.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 import json
-from datetime import datetime
+from datetime import datetime, timezone
 from textwrap import wrap
 from typing import Any, Literal
+import re
 
 import click
 from click.core import ParameterSource  # type: ignore[attr-defined]
@@ -17,8 +18,13 @@ from together.utils import (
     log_warn,
     log_warn_once,
     parse_timestamp,
+    format_timestamp,
+)
+from together.types.finetune import (
+    DownloadCheckpointType,
+    FinetuneTrainingLimits,
+    FinetuneEventType,
 )
-from together.types.finetune import DownloadCheckpointType, FinetuneTrainingLimits
 
 
 _CONFIRMATION_MESSAGE = (
@@ -104,6 +110,18 @@ def fine_tuning(ctx: click.Context) -> None:
     default="all-linear",
     help="Trainable modules for LoRA adapters. For example, 'all-linear', 'q_proj,v_proj'",
 )
+@click.option(
+    "--training-method",
+    type=click.Choice(["sft", "dpo"]),
+    default="sft",
+    help="Training method to use. Options: sft (supervised fine-tuning), dpo (Direct Preference Optimization)",
+)
+@click.option(
+    "--dpo-beta",
+    type=float,
+    default=0.1,
+    help="Beta parameter for DPO training (only used when '--training-method' is 'dpo')",
+)
 @click.option(
     "--suffix", type=str, default=None, help="Suffix for the fine-tuned model name"
 )
@@ -126,6 +144,14 @@ def fine_tuning(ctx: click.Context) -> None:
     help="Whether to mask the user messages in conversational data or prompts in instruction data. "
     "`auto` will automatically determine whether to mask the inputs based on the data format.",
 )
+@click.option(
+    "--from-checkpoint",
+    type=str,
+    default=None,
+    help="The checkpoint identifier to continue training from a previous fine-tuning job. "
+    "The format: {$JOB_ID/$OUTPUT_MODEL_NAME}:{$STEP}. "
+    "The step value is optional, without it the final checkpoint will be used.",
+)
 def create(
     ctx: click.Context,
     training_file: str,
@@ -152,6 +178,9 @@ def create(
     wandb_name: str,
     confirm: bool,
     train_on_inputs: bool | Literal["auto"],
+    training_method: str,
+    dpo_beta: float,
+    from_checkpoint: str,
 ) -> None:
     """Start fine-tuning"""
     client: Together = ctx.obj
@@ -180,6 +209,9 @@ def create(
         wandb_project_name=wandb_project_name,
         wandb_name=wandb_name,
         train_on_inputs=train_on_inputs,
+        training_method=training_method,
+        dpo_beta=dpo_beta,
+        from_checkpoint=from_checkpoint,
     )
 
     model_limits: FinetuneTrainingLimits = client.fine_tuning.get_model_limits(
@@ -261,7 +293,9 @@ def list(ctx: click.Context) -> None:
 
     response.data = response.data or []
 
-    response.data.sort(key=lambda x: parse_timestamp(x.created_at or ""))
+    # Use a default datetime for None values to make sure the key function always returns a comparable value
+    epoch_start = datetime.fromtimestamp(0, tz=timezone.utc)
+    response.data.sort(key=lambda x: parse_timestamp(x.created_at or "") or epoch_start)
 
     display_list = []
     for i in response.data:
@@ -344,6 +378,34 @@ def list_events(ctx: click.Context, fine_tune_id: str) -> None:
     click.echo(table)
 
 
+@fine_tuning.command()
+@click.pass_context
+@click.argument("fine_tune_id", type=str, required=True)
+def list_checkpoints(ctx: click.Context, fine_tune_id: str) -> None:
+    """List available checkpoints for a fine-tuning job"""
+    client: Together = ctx.obj
+
+    checkpoints = client.fine_tuning.list_checkpoints(fine_tune_id)
+
+    display_list = []
+    for checkpoint in checkpoints:
+        display_list.append(
+            {
+                "Type": checkpoint.type,
+                "Timestamp": format_timestamp(checkpoint.timestamp),
+                "Name": checkpoint.name,
+            }
+        )
+
+    if display_list:
+        click.echo(f"Job {fine_tune_id} contains the following checkpoints:")
+        table = tabulate(display_list, headers="keys", tablefmt="grid")
+        click.echo(table)
+        click.echo("\nTo download a checkpoint, use `together fine-tuning download`")
+    else:
+        click.echo(f"No checkpoints found for job {fine_tune_id}")
+
+
 @fine_tuning.command()
 @click.pass_context
 @click.argument("fine_tune_id", type=str, required=True)
@@ -358,7 +420,7 @@ def list_events(ctx: click.Context, fine_tune_id: str) -> None:
     "--checkpoint-step",
     type=int,
     required=False,
-    default=-1,
+    default=None,
     help="Download fine-tuning checkpoint. Defaults to latest.",
 )
 @click.option(
@@ -372,7 +434,7 @@ def download(
     ctx: click.Context,
     fine_tune_id: str,
     output_dir: str,
-    checkpoint_step: int,
+    checkpoint_step: int | None,
     checkpoint_type: DownloadCheckpointType,
 ) -> None:
     """Download fine-tuning checkpoint"""

together/client.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import os
-from typing import Dict
+import sys
+from typing import Dict, TYPE_CHECKING
 
 from together import resources
 from together.constants import BASE_URL, MAX_RETRIES, TIMEOUT_SECS
 from together.error import AuthenticationError
 from together.types import TogetherClient
 from together.utils import enforce_trailing_slash
+from together.utils.api_helpers import get_google_colab_secret
 
 
 class Together:
@@ -44,6 +46,9 @@ class Together:
         if not api_key:
             api_key = os.environ.get("TOGETHER_API_KEY")
 
+        if not api_key and "google.colab" in sys.modules:
+            api_key = get_google_colab_secret("TOGETHER_API_KEY")
+
         if not api_key:
             raise AuthenticationError(
                 "The api_key client option must be set either by passing api_key to the client or by setting the "
@@ -117,6 +122,9 @@ class AsyncTogether:
         if not api_key:
             api_key = os.environ.get("TOGETHER_API_KEY")
 
+        if not api_key and "google.colab" in sys.modules:
+            api_key = get_google_colab_secret("TOGETHER_API_KEY")
+
         if not api_key:
             raise AuthenticationError(
                 "The api_key client option must be set either by passing api_key to the client or by setting the "

together/constants.py

@@ -39,12 +39,18 @@ class DatasetFormat(enum.Enum):
     GENERAL = "general"
     CONVERSATION = "conversation"
     INSTRUCTION = "instruction"
+    PREFERENCE_OPENAI = "preference_openai"
 
 
 JSONL_REQUIRED_COLUMNS_MAP = {
     DatasetFormat.GENERAL: ["text"],
     DatasetFormat.CONVERSATION: ["messages"],
     DatasetFormat.INSTRUCTION: ["prompt", "completion"],
+    DatasetFormat.PREFERENCE_OPENAI: [
+        "input",
+        "preferred_output",
+        "non_preferred_output",
+    ],
 }
 REQUIRED_COLUMNS_MESSAGE = ["role", "content"]
 POSSIBLE_ROLES_CONVERSATION = ["system", "user", "assistant"]

together/legacy/finetune.py

@@ -161,7 +161,7 @@ class Finetune:
         cls,
         fine_tune_id: str,
         output: str | None = None,
-        step: int = -1,
+        step: int | None = None,
     ) -> Dict[str, Any]:
         """Legacy finetuning download function."""
 

together/resources/finetune.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
+import re
 from pathlib import Path
-from typing import Literal
+from typing import Literal, List
 
 from rich import print as rprint
 
@@ -22,9 +23,28 @@ from together.types import (
     TrainingType,
     FinetuneLRScheduler,
     FinetuneLinearLRSchedulerArgs,
+    TrainingMethodDPO,
+    TrainingMethodSFT,
+    FinetuneCheckpoint,
 )
-from together.types.finetune import DownloadCheckpointType
-from together.utils import log_warn_once, normalize_key
+from together.types.finetune import (
+    DownloadCheckpointType,
+    FinetuneEventType,
+    FinetuneEvent,
+)
+from together.utils import (
+    log_warn_once,
+    normalize_key,
+    get_event_step,
+)
+
+_FT_JOB_WITH_STEP_REGEX = r"^ft-[\dabcdef-]+:\d+$"
+
+
+AVAILABLE_TRAINING_METHODS = {
+    TrainingMethodSFT().method,
+    TrainingMethodDPO().method,
+}
 
 
 def createFinetuneRequest(
@@ -52,7 +72,11 @@ def createFinetuneRequest(
     wandb_project_name: str | None = None,
     wandb_name: str | None = None,
     train_on_inputs: bool | Literal["auto"] = "auto",
+    training_method: str = "sft",
+    dpo_beta: float | None = None,
+    from_checkpoint: str | None = None,
 ) -> FinetuneRequest:
+
     if batch_size == "max":
         log_warn_once(
             "Starting from together>=1.3.0, "
@@ -100,11 +124,20 @@ def createFinetuneRequest(
     if weight_decay is not None and (weight_decay < 0):
         raise ValueError("Weight decay should be non-negative")
 
+    if training_method not in AVAILABLE_TRAINING_METHODS:
+        raise ValueError(
+            f"training_method must be one of {', '.join(AVAILABLE_TRAINING_METHODS)}"
+        )
+
     lrScheduler = FinetuneLRScheduler(
         lr_scheduler_type="linear",
         lr_scheduler_args=FinetuneLinearLRSchedulerArgs(min_lr_ratio=min_lr_ratio),
     )
 
+    training_method_cls: TrainingMethodSFT | TrainingMethodDPO = TrainingMethodSFT()
+    if training_method == "dpo":
+        training_method_cls = TrainingMethodDPO(dpo_beta=dpo_beta)
+
     finetune_request = FinetuneRequest(
         model=model,
         training_file=training_file,
@@ -125,11 +158,77 @@ def createFinetuneRequest(
         wandb_project_name=wandb_project_name,
         wandb_name=wandb_name,
         train_on_inputs=train_on_inputs,
+        training_method=training_method_cls,
+        from_checkpoint=from_checkpoint,
     )
 
     return finetune_request
 
 
+def _process_checkpoints_from_events(
+    events: List[FinetuneEvent], id: str
+) -> List[FinetuneCheckpoint]:
+    """
+    Helper function to process events and create checkpoint list.
+
+    Args:
+        events (List[FinetuneEvent]): List of fine-tune events to process
+        id (str): Fine-tune job ID
+
+    Returns:
+        List[FinetuneCheckpoint]: List of available checkpoints
+    """
+    checkpoints: List[FinetuneCheckpoint] = []
+
+    for event in events:
+        event_type = event.type
+
+        if event_type == FinetuneEventType.CHECKPOINT_SAVE:
+            step = get_event_step(event)
+            checkpoint_name = f"{id}:{step}" if step is not None else id
+
+            checkpoints.append(
+                FinetuneCheckpoint(
+                    type=(
+                        f"Intermediate (step {step})"
+                        if step is not None
+                        else "Intermediate"
+                    ),
+                    timestamp=event.created_at,
+                    name=checkpoint_name,
+                )
+            )
+        elif event_type == FinetuneEventType.JOB_COMPLETE:
+            if hasattr(event, "model_path"):
+                checkpoints.append(
+                    FinetuneCheckpoint(
+                        type=(
+                            "Final Merged"
+                            if hasattr(event, "adapter_path")
+                            else "Final"
+                        ),
+                        timestamp=event.created_at,
+                        name=id,
+                    )
+                )
+
+            if hasattr(event, "adapter_path"):
+                checkpoints.append(
+                    FinetuneCheckpoint(
+                        type=(
+                            "Final Adapter" if hasattr(event, "model_path") else "Final"
+                        ),
+                        timestamp=event.created_at,
+                        name=id,
+                    )
+                )
+
+    # Sort by timestamp (newest first)
+    checkpoints.sort(key=lambda x: x.timestamp, reverse=True)
+
+    return checkpoints
+
+
 class FineTuning:
     def __init__(self, client: TogetherClient) -> None:
         self._client = client
@@ -162,6 +261,9 @@ class FineTuning:
         verbose: bool = False,
         model_limits: FinetuneTrainingLimits | None = None,
         train_on_inputs: bool | Literal["auto"] = "auto",
+        training_method: str = "sft",
+        dpo_beta: float | None = None,
+        from_checkpoint: str | None = None,
     ) -> FinetuneResponse:
         """
         Method to initiate a fine-tuning job
@@ -207,6 +309,12 @@ class FineTuning:
                 For datasets with the "messages" field (conversational format) or "prompt" and "completion" fields
                 (Instruction format), inputs will be masked.
                 Defaults to "auto".
+            training_method (str, optional): Training method. Defaults to "sft".
+                Supported methods: "sft", "dpo".
+            dpo_beta (float, optional): DPO beta parameter. Defaults to None.
+            from_checkpoint (str, optional): The checkpoint identifier to continue training from a previous fine-tuning job.
+                The format: {$JOB_ID/$OUTPUT_MODEL_NAME}:{$STEP}.
+                The step value is optional, without it the final checkpoint will be used.
 
         Returns:
             FinetuneResponse: Object containing information about fine-tuning job.
@@ -218,7 +326,6 @@ class FineTuning:
 
         if model_limits is None:
             model_limits = self.get_model_limits(model=model)
-
         finetune_request = createFinetuneRequest(
             model_limits=model_limits,
             training_file=training_file,
@@ -244,6 +351,9 @@ class FineTuning:
             wandb_project_name=wandb_project_name,
             wandb_name=wandb_name,
             train_on_inputs=train_on_inputs,
+            training_method=training_method,
+            dpo_beta=dpo_beta,
+            from_checkpoint=from_checkpoint,
         )
 
         if verbose:
@@ -261,7 +371,6 @@ class FineTuning:
             ),
             stream=False,
         )
-
         assert isinstance(response, TogetherResponse)
 
         return FinetuneResponse(**response.data)
@@ -366,17 +475,29 @@ class FineTuning:
             ),
             stream=False,
         )
-
         assert isinstance(response, TogetherResponse)
 
         return FinetuneListEvents(**response.data)
 
+    def list_checkpoints(self, id: str) -> List[FinetuneCheckpoint]:
+        """
+        List available checkpoints for a fine-tuning job
+
+        Args:
+            id (str): Unique identifier of the fine-tune job to list checkpoints for
+
+        Returns:
+            List[FinetuneCheckpoint]: List of available checkpoints
+        """
+        events = self.list_events(id).data or []
+        return _process_checkpoints_from_events(events, id)
+
     def download(
         self,
         id: str,
         *,
         output: Path | str | None = None,
-        checkpoint_step: int = -1,
+        checkpoint_step: int | None = None,
         checkpoint_type: DownloadCheckpointType = DownloadCheckpointType.DEFAULT,
     ) -> FinetuneDownloadResult:
         """
@@ -397,9 +518,19 @@ class FineTuning:
             FinetuneDownloadResult: Object containing downloaded model metadata
         """
 
+        if re.match(_FT_JOB_WITH_STEP_REGEX, id) is not None:
+            if checkpoint_step is None:
+                checkpoint_step = int(id.split(":")[1])
+                id = id.split(":")[0]
+            else:
+                raise ValueError(
+                    "Fine-tuning job ID {id} contains a colon to specify the step to download, but `checkpoint_step` "
+                    "was also set. Remove one of the step specifiers to proceed."
+                )
+
         url = f"finetune/download?ft_id={id}"
 
-        if checkpoint_step > 0:
+        if checkpoint_step is not None:
             url += f"&checkpoint_step={checkpoint_step}"
 
         ft_job = self.retrieve(id)
@@ -503,6 +634,9 @@ class AsyncFineTuning:
         verbose: bool = False,
         model_limits: FinetuneTrainingLimits | None = None,
         train_on_inputs: bool | Literal["auto"] = "auto",
+        training_method: str = "sft",
+        dpo_beta: float | None = None,
+        from_checkpoint: str | None = None,
     ) -> FinetuneResponse:
         """
         Async method to initiate a fine-tuning job
@@ -548,6 +682,12 @@ class AsyncFineTuning:
                 For datasets with the "messages" field (conversational format) or "prompt" and "completion" fields
                 (Instruction format), inputs will be masked.
                 Defaults to "auto".
+            training_method (str, optional): Training method. Defaults to "sft".
+                Supported methods: "sft", "dpo".
+            dpo_beta (float, optional): DPO beta parameter. Defaults to None.
+            from_checkpoint (str, optional): The checkpoint identifier to continue training from a previous fine-tuning job.
+                The format: {$JOB_ID/$OUTPUT_MODEL_NAME}:{$STEP}.
+                The step value is optional, without it the final checkpoint will be used.
 
         Returns:
             FinetuneResponse: Object containing information about fine-tuning job.
@@ -585,6 +725,9 @@ class AsyncFineTuning:
             wandb_project_name=wandb_project_name,
             wandb_name=wandb_name,
             train_on_inputs=train_on_inputs,
+            training_method=training_method,
+            dpo_beta=dpo_beta,
+            from_checkpoint=from_checkpoint,
         )
 
         if verbose:
@@ -687,30 +830,45 @@ class AsyncFineTuning:
 
     async def list_events(self, id: str) -> FinetuneListEvents:
         """
-        Async method to lists events of a fine-tune job
+        List fine-tuning events
 
         Args:
-            id (str): Fine-tune ID to list events for. A string that starts with `ft-`.
+            id (str): Unique identifier of the fine-tune job to list events for
 
         Returns:
-            FinetuneListEvents: Object containing list of fine-tune events
+            FinetuneListEvents: Object containing list of fine-tune job events
         """
 
         requestor = api_requestor.APIRequestor(
             client=self._client,
         )
 
-        response, _, _ = await requestor.arequest(
+        events_response, _, _ = await requestor.arequest(
             options=TogetherRequest(
                 method="GET",
-                url=f"fine-tunes/{id}/events",
+                url=f"fine-tunes/{normalize_key(id)}/events",
             ),
             stream=False,
         )
 
-        assert isinstance(response, TogetherResponse)
+        # FIXME: API returns "data" field with no object type (should be "list")
+        events_list = FinetuneListEvents(object="list", **events_response.data)
 
-        return FinetuneListEvents(**response.data)
+        return events_list
+
+    async def list_checkpoints(self, id: str) -> List[FinetuneCheckpoint]:
+        """
+        List available checkpoints for a fine-tuning job
+
+        Args:
+            id (str): Unique identifier of the fine-tune job to list checkpoints for
+
+        Returns:
+            List[FinetuneCheckpoint]: Object containing list of available checkpoints
+        """
+        events_list = await self.list_events(id)
+        events = events_list.data or []
+        return _process_checkpoints_from_events(events, id)
 
     async def download(
         self, id: str, *, output: str | None = None, checkpoint_step: int = -1

together/types/__init__.py

@@ -31,6 +31,9 @@ from together.types.files import (
     FileType,
 )
 from together.types.finetune import (
+    TrainingMethodDPO,
+    TrainingMethodSFT,
+    FinetuneCheckpoint,
     FinetuneDownloadResult,
     FinetuneLinearLRSchedulerArgs,
     FinetuneList,
@@ -59,6 +62,7 @@ __all__ = [
     "ChatCompletionResponse",
     "EmbeddingRequest",
     "EmbeddingResponse",
+    "FinetuneCheckpoint",
     "FinetuneRequest",
     "FinetuneResponse",
     "FinetuneList",
@@ -79,6 +83,8 @@ __all__ = [
     "TrainingType",
     "FullTrainingType",
     "LoRATrainingType",
+    "TrainingMethodDPO",
+    "TrainingMethodSFT",
     "RerankRequest",
     "RerankResponse",
     "FinetuneTrainingLimits",

together/types/chat_completions.py

@@ -44,16 +44,22 @@ class ToolCalls(BaseModel):
 class ChatCompletionMessageContentType(str, Enum):
     TEXT = "text"
     IMAGE_URL = "image_url"
+    VIDEO_URL = "video_url"
 
 
 class ChatCompletionMessageContentImageURL(BaseModel):
     url: str
 
 
+class ChatCompletionMessageContentVideoURL(BaseModel):
+    url: str
+
+
 class ChatCompletionMessageContent(BaseModel):
     type: ChatCompletionMessageContentType
     text: str | None = None
     image_url: ChatCompletionMessageContentImageURL | None = None
+    video_url: ChatCompletionMessageContentVideoURL | None = None
 
 
 class ChatCompletionMessage(BaseModel):

together/types/endpoints.py

@@ -86,9 +86,9 @@ class BaseEndpoint(TogetherJSONModel):
     model: str = Field(description="The model deployed on this endpoint")
     type: str = Field(description="The type of endpoint")
     owner: str = Field(description="The owner of this endpoint")
-    state: Literal["PENDING", "STARTING", "STARTED", "STOPPING", "STOPPED", "ERROR"] = (
-        Field(description="Current state of the endpoint")
-    )
+    state: Literal[
+        "PENDING", "STARTING", "STARTED", "STOPPING", "STOPPED", "FAILED", "ERROR"
+    ] = Field(description="Current state of the endpoint")
     created_at: datetime = Field(description="Timestamp when the endpoint was created")
 
 

together/types/finetune.py

@@ -135,6 +135,31 @@ class LoRATrainingType(TrainingType):
     type: str = "Lora"
 
 
+class TrainingMethod(BaseModel):
+    """
+    Training method type
+    """
+
+    method: str
+
+
+class TrainingMethodSFT(TrainingMethod):
+    """
+    Training method type for SFT training
+    """
+
+    method: Literal["sft"] = "sft"
+
+
+class TrainingMethodDPO(TrainingMethod):
+    """
+    Training method type for DPO training
+    """
+
+    method: Literal["dpo"] = "dpo"
+    dpo_beta: float | None = None
+
+
 class FinetuneRequest(BaseModel):
     """
     Fine-tune request type
@@ -178,6 +203,12 @@ class FinetuneRequest(BaseModel):
     training_type: FullTrainingType | LoRATrainingType | None = None
     # train on inputs
     train_on_inputs: StrictBool | Literal["auto"] = "auto"
+    # training method
+    training_method: TrainingMethodSFT | TrainingMethodDPO = Field(
+        default_factory=TrainingMethodSFT
+    )
+    # from step
+    from_checkpoint: str | None = None
 
 
 class FinetuneResponse(BaseModel):
@@ -256,6 +287,7 @@ class FinetuneResponse(BaseModel):
     training_file_num_lines: int | None = Field(None, alias="TrainingFileNumLines")
     training_file_size: int | None = Field(None, alias="TrainingFileSize")
     train_on_inputs: StrictBool | Literal["auto"] | None = "auto"
+    from_checkpoint: str | None = None
 
     @field_validator("training_type")
     @classmethod
@@ -320,3 +352,16 @@ class FinetuneLRScheduler(BaseModel):
 
 class FinetuneLinearLRSchedulerArgs(BaseModel):
     min_lr_ratio: float | None = 0.0
+
+
+class FinetuneCheckpoint(BaseModel):
+    """
+    Fine-tuning checkpoint information
+    """
+
+    # checkpoint type (e.g. "Intermediate", "Final", "Final Merged", "Final Adapter")
+    type: str
+    # timestamp when the checkpoint was created
+    timestamp: str
+    # checkpoint name/identifier
+    name: str

together/utils/__init__.py

@@ -8,6 +8,8 @@ from together.utils.tools import (
     finetune_price_to_dollars,
     normalize_key,
     parse_timestamp,
+    format_timestamp,
+    get_event_step,
 )
 
 
@@ -23,6 +25,8 @@ __all__ = [
     "enforce_trailing_slash",
     "normalize_key",
     "parse_timestamp",
+    "format_timestamp",
+    "get_event_step",
     "finetune_price_to_dollars",
     "convert_bytes",
     "convert_unix_timestamp",