together 1.4.0__py3-none-any.whl → 1.4.4__py3-none-any.whl

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

@@ -1,4 +1,13 @@
 from together.types.abstract import TogetherClient
+from together.types.audio_speech import (
+    AudioLanguage,
+    AudioResponseEncoding,
+    AudioResponseFormat,
+    AudioSpeechRequest,
+    AudioSpeechStreamChunk,
+    AudioSpeechStreamEvent,
+    AudioSpeechStreamResponse,
+)
 from together.types.chat_completions import (
     ChatCompletionChunk,
     ChatCompletionRequest,
@@ -11,6 +20,7 @@ from together.types.completions import (
     CompletionResponse,
 )
 from together.types.embeddings import EmbeddingRequest, EmbeddingResponse
+from together.types.endpoints import Autoscaling, DedicatedEndpoint, ListEndpoint
 from together.types.files import (
     FileDeleteResponse,
     FileList,
@@ -21,36 +31,25 @@ from together.types.files import (
     FileType,
 )
 from together.types.finetune import (
+    TrainingMethodDPO,
+    TrainingMethodSFT,
+    FinetuneCheckpoint,
     FinetuneDownloadResult,
+    FinetuneLinearLRSchedulerArgs,
     FinetuneList,
     FinetuneListEvents,
+    FinetuneLRScheduler,
     FinetuneRequest,
     FinetuneResponse,
+    FinetuneTrainingLimits,
     FullTrainingType,
     LoRATrainingType,
     TrainingType,
-    FinetuneTrainingLimits,
-    FinetuneLRScheduler,
-    FinetuneLinearLRSchedulerArgs,
-)
-from together.types.images import (
-    ImageRequest,
-    ImageResponse,
 )
+from together.types.images import ImageRequest, ImageResponse
 from together.types.models import ModelObject
-from together.types.rerank import (
-    RerankRequest,
-    RerankResponse,
-)
-from together.types.audio_speech import (
-    AudioSpeechRequest,
-    AudioResponseFormat,
-    AudioLanguage,
-    AudioResponseEncoding,
-    AudioSpeechStreamChunk,
-    AudioSpeechStreamEvent,
-    AudioSpeechStreamResponse,
-)
+from together.types.rerank import RerankRequest, RerankResponse
+
 
 __all__ = [
     "TogetherClient",
@@ -63,6 +62,7 @@ __all__ = [
     "ChatCompletionResponse",
     "EmbeddingRequest",
     "EmbeddingResponse",
+    "FinetuneCheckpoint",
     "FinetuneRequest",
     "FinetuneResponse",
     "FinetuneList",
@@ -83,6 +83,8 @@ __all__ = [
     "TrainingType",
     "FullTrainingType",
     "LoRATrainingType",
+    "TrainingMethodDPO",
+    "TrainingMethodSFT",
     "RerankRequest",
     "RerankResponse",
     "FinetuneTrainingLimits",
@@ -93,4 +95,7 @@ __all__ = [
     "AudioSpeechStreamChunk",
     "AudioSpeechStreamEvent",
     "AudioSpeechStreamResponse",
+    "DedicatedEndpoint",
+    "ListEndpoint",
+    "Autoscaling",
 ]

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

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class TogetherJSONModel(BaseModel):
+    """Base model with JSON serialization support."""
+
+    def model_dump(self, **kwargs: Any) -> Dict[str, Any]:
+        exclude_none = kwargs.pop("exclude_none", True)
+        data = super().model_dump(exclude_none=exclude_none, **kwargs)
+
+        # Convert datetime objects to ISO format strings
+        for key, value in data.items():
+            if isinstance(value, datetime):
+                data[key] = value.isoformat()
+
+        return data
+
+
+class Autoscaling(TogetherJSONModel):
+    """Configuration for automatic scaling of replicas based on demand."""
+
+    min_replicas: int = Field(
+        description="The minimum number of replicas to maintain, even when there is no load"
+    )
+    max_replicas: int = Field(
+        description="The maximum number of replicas to scale up to under load"
+    )
+
+
+class EndpointPricing(TogetherJSONModel):
+    """Pricing details for using an endpoint."""
+
+    cents_per_minute: float = Field(
+        description="Cost per minute of endpoint uptime in cents"
+    )
+
+
+class HardwareSpec(TogetherJSONModel):
+    """Detailed specifications of a hardware configuration."""
+
+    gpu_type: str = Field(description="The type/model of GPU")
+    gpu_link: str = Field(description="The GPU interconnect technology")
+    gpu_memory: Union[float, int] = Field(description="Amount of GPU memory in GB")
+    gpu_count: int = Field(description="Number of GPUs in this configuration")
+
+
+class HardwareAvailability(TogetherJSONModel):
+    """Indicates the current availability status of a hardware configuration."""
+
+    status: Literal["available", "unavailable", "insufficient"] = Field(
+        description="The availability status of the hardware configuration"
+    )
+
+
+class HardwareWithStatus(TogetherJSONModel):
+    """Hardware configuration details with optional availability status."""
+
+    object: Literal["hardware"] = Field(description="The type of object")
+    id: str = Field(description="Unique identifier for the hardware configuration")
+    pricing: EndpointPricing = Field(
+        description="Pricing details for this hardware configuration"
+    )
+    specs: HardwareSpec = Field(description="Detailed specifications of this hardware")
+    availability: Optional[HardwareAvailability] = Field(
+        default=None,
+        description="Current availability status of this hardware configuration",
+    )
+    updated_at: datetime = Field(
+        description="Timestamp of when the hardware status was last updated"
+    )
+
+
+class BaseEndpoint(TogetherJSONModel):
+    """Base class for endpoint models with common fields."""
+
+    object: Literal["endpoint"] = Field(description="The type of object")
+    id: Optional[str] = Field(
+        default=None, description="Unique identifier for the endpoint"
+    )
+    name: str = Field(description="System name for the endpoint")
+    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", "FAILED", "ERROR"
+    ] = Field(description="Current state of the endpoint")
+    created_at: datetime = Field(description="Timestamp when the endpoint was created")
+
+
+class ListEndpoint(BaseEndpoint):
+    """Details about an endpoint when listed via the list endpoint."""
+
+    type: Literal["dedicated", "serverless"] = Field(description="The type of endpoint")
+
+
+class DedicatedEndpoint(BaseEndpoint):
+    """Details about a dedicated endpoint deployment."""
+
+    id: str = Field(description="Unique identifier for the endpoint")
+    type: Literal["dedicated"] = Field(description="The type of endpoint")
+    display_name: str = Field(description="Human-readable name for the endpoint")
+    hardware: str = Field(
+        description="The hardware configuration used for this endpoint"
+    )
+    autoscaling: Autoscaling = Field(
+        description="Configuration for automatic scaling of the endpoint"
+    )
+
+
+__all__ = [
+    "DedicatedEndpoint",
+    "ListEndpoint",
+    "Autoscaling",
+    "EndpointPricing",
+    "HardwareSpec",
+    "HardwareAvailability",
+    "HardwareWithStatus",
+]

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",