together 1.2.12__tar.gz → 1.3.0__tar.gz

{together-1.2.12 → together-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: together
-Version: 1.2.12
+Version: 1.3.0
 Summary: Python client for Together's Cloud Platform!
 Home-page: https://github.com/togethercomputer/together-python
 License: Apache-2.0
@@ -25,6 +25,7 @@ Requires-Dist: pillow (>=10.3.0,<11.0.0)
 Requires-Dist: pyarrow (>=10.0.1)
 Requires-Dist: pydantic (>=2.6.3,<3.0.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: rich (>=13.8.1,<14.0.0)
 Requires-Dist: tabulate (>=0.9.0,<0.10.0)
 Requires-Dist: tqdm (>=4.66.2,<5.0.0)
 Requires-Dist: typer (>=0.9,<0.13)
@@ -276,7 +277,7 @@ client.fine_tuning.create(
   model = 'mistralai/Mixtral-8x7B-Instruct-v0.1',
   n_epochs = 3,
   n_checkpoints = 1,
-  batch_size = 4,
+  batch_size = "max",
   learning_rate = 1e-5,
   suffix = 'my-demo-finetune',
   wandb_api_key = '1a2b3c4d5e.......',

{together-1.2.12 → together-1.3.0}/README.md

@@ -242,7 +242,7 @@ client.fine_tuning.create(
   model = 'mistralai/Mixtral-8x7B-Instruct-v0.1',
   n_epochs = 3,
   n_checkpoints = 1,
-  batch_size = 4,
+  batch_size = "max",
   learning_rate = 1e-5,
   suffix = 'my-demo-finetune',
   wandb_api_key = '1a2b3c4d5e.......',

{together-1.2.12 → together-1.3.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "poetry.masonry.api"
 
 [tool.poetry]
 name = "together"
-version = "1.2.12"
+version = "1.3.0"
 authors = [
     "Together AI <support@together.ai>"
 ]
@@ -31,6 +31,7 @@ homepage = "https://github.com/togethercomputer/together-python"
 python = "^3.8"
 typer = ">=0.9,<0.13"
 requests = "^2.31.0"
+rich = "^13.8.1"
 tqdm = "^4.66.2"
 tabulate = "^0.9.0"
 pydantic = "^2.6.3"
@@ -70,7 +71,7 @@ tox = "^4.14.1"
 optional = true
 
 [tool.poetry.group.examples.dependencies]
-datasets = "^2.18.0"
+datasets = ">=2.18,<4.0"
 transformers = "^4.39.3"
 
 

{together-1.2.12 → together-1.3.0}/src/together/cli/api/finetune.py

@@ -1,15 +1,29 @@
 from __future__ import annotations
 
 import json
+from datetime import datetime
 from textwrap import wrap
+from typing import Any, Literal
 
 import click
 from click.core import ParameterSource  # type: ignore[attr-defined]
+from rich import print as rprint
 from tabulate import tabulate
 
 from together import Together
+from together.cli.api.utils import INT_WITH_MAX
 from together.utils import finetune_price_to_dollars, log_warn, parse_timestamp
-from together.types.finetune import DownloadCheckpointType
+from together.types.finetune import DownloadCheckpointType, FinetuneTrainingLimits
+
+
+_CONFIRMATION_MESSAGE = (
+    "You are about to create a fine-tuning job. "
+    "The cost of your job will be determined by the model size, the number of tokens "
+    "in the training file, the number of tokens in the validation file, the number of epochs, and "
+    "the number of evaluations. Visit https://www.together.ai/pricing to get a price estimate.\n"
+    "You can pass `-y` or `--confirm` to your command to skip this message.\n\n"
+    "Do you want to proceed?"
+)
 
 
 class DownloadCheckpointTypeChoice(click.Choice):
@@ -44,7 +58,7 @@ def fine_tuning(ctx: click.Context) -> None:
 @click.option(
     "--n-checkpoints", type=int, default=1, help="Number of checkpoints to save"
 )
-@click.option("--batch-size", type=int, default=16, help="Train batch size")
+@click.option("--batch-size", type=INT_WITH_MAX, default="max", help="Train batch size")
 @click.option("--learning-rate", type=float, default=1e-5, help="Learning rate")
 @click.option(
     "--lora/--no-lora",
@@ -65,6 +79,14 @@ def fine_tuning(ctx: click.Context) -> None:
     "--suffix", type=str, default=None, help="Suffix for the fine-tuned model name"
 )
 @click.option("--wandb-api-key", type=str, default=None, help="Wandb API key")
+@click.option(
+    "--confirm",
+    "-y",
+    type=bool,
+    is_flag=True,
+    default=False,
+    help="Whether to skip the launch confirmation message",
+)
 def create(
     ctx: click.Context,
     training_file: str,
@@ -73,7 +95,7 @@ def create(
     n_epochs: int,
     n_evals: int,
     n_checkpoints: int,
-    batch_size: int,
+    batch_size: int | Literal["max"],
     learning_rate: float,
     lora: bool,
     lora_r: int,
@@ -82,34 +104,12 @@ def create(
     lora_trainable_modules: str,
     suffix: str,
     wandb_api_key: str,
+    confirm: bool,
 ) -> None:
     """Start fine-tuning"""
     client: Together = ctx.obj
 
-    if lora:
-        learning_rate_source = click.get_current_context().get_parameter_source(  # type: ignore[attr-defined]
-            "learning_rate"
-        )
-        if learning_rate_source == ParameterSource.DEFAULT:
-            learning_rate = 1e-3
-    else:
-        for param in ["lora_r", "lora_dropout", "lora_alpha", "lora_trainable_modules"]:
-            param_source = click.get_current_context().get_parameter_source(param)  # type: ignore[attr-defined]
-            if param_source != ParameterSource.DEFAULT:
-                raise click.BadParameter(
-                    f"You set LoRA parameter `{param}` for a full fine-tuning job. "
-                    f"Please change the job type with --lora or remove `{param}` from the arguments"
-                )
-    if n_evals <= 0 and validation_file:
-        log_warn(
-            "Warning: You have specified a validation file but the number of evaluation loops is set to 0. No evaluations will be performed."
-        )
-    elif n_evals > 0 and not validation_file:
-        raise click.BadParameter(
-            "You have specified a number of evaluation loops but no validation file."
-        )
-
-    response = client.fine_tuning.create(
+    training_args: dict[str, Any] = dict(
         training_file=training_file,
         model=model,
         n_epochs=n_epochs,
@@ -127,13 +127,87 @@ def create(
         wandb_api_key=wandb_api_key,
     )
 
-    click.echo(json.dumps(response.model_dump(exclude_none=True), indent=4))
-
-    # TODO: Remove it after the 21st of August
-    log_warn(
-        "The default value of batch size has been changed from 32 to 16 since together version >= 1.2.6"
+    model_limits: FinetuneTrainingLimits = client.fine_tuning.get_model_limits(
+        model=model
     )
 
+    if lora:
+        if model_limits.lora_training is None:
+            raise click.BadParameter(
+                f"LoRA fine-tuning is not supported for the model `{model}`"
+            )
+
+        default_values = {
+            "lora_r": model_limits.lora_training.max_rank,
+            "batch_size": model_limits.lora_training.max_batch_size,
+            "learning_rate": 1e-3,
+        }
+        for arg in default_values:
+            arg_source = ctx.get_parameter_source("arg")  # type: ignore[attr-defined]
+            if arg_source == ParameterSource.DEFAULT:
+                training_args[arg] = default_values[arg_source]
+
+        if ctx.get_parameter_source("lora_alpha") == ParameterSource.DEFAULT:  # type: ignore[attr-defined]
+            training_args["lora_alpha"] = training_args["lora_r"] * 2
+    else:
+        if model_limits.full_training is None:
+            raise click.BadParameter(
+                f"Full fine-tuning is not supported for the model `{model}`"
+            )
+
+        for param in ["lora_r", "lora_dropout", "lora_alpha", "lora_trainable_modules"]:
+            param_source = ctx.get_parameter_source(param)  # type: ignore[attr-defined]
+            if param_source != ParameterSource.DEFAULT:
+                raise click.BadParameter(
+                    f"You set LoRA parameter `{param}` for a full fine-tuning job. "
+                    f"Please change the job type with --lora or remove `{param}` from the arguments"
+                )
+
+        batch_size_source = ctx.get_parameter_source("batch_size")  # type: ignore[attr-defined]
+        if batch_size_source == ParameterSource.DEFAULT:
+            training_args["batch_size"] = model_limits.full_training.max_batch_size
+
+    if n_evals <= 0 and validation_file:
+        log_warn(
+            "Warning: You have specified a validation file but the number of evaluation loops is set to 0. No evaluations will be performed."
+        )
+    elif n_evals > 0 and not validation_file:
+        raise click.BadParameter(
+            "You have specified a number of evaluation loops but no validation file."
+        )
+
+    if confirm or click.confirm(_CONFIRMATION_MESSAGE, default=True, show_default=True):
+        response = client.fine_tuning.create(
+            training_file=training_file,
+            model=model,
+            n_epochs=n_epochs,
+            validation_file=validation_file,
+            n_evals=n_evals,
+            n_checkpoints=n_checkpoints,
+            batch_size=batch_size,
+            learning_rate=learning_rate,
+            lora=lora,
+            lora_r=lora_r,
+            lora_dropout=lora_dropout,
+            lora_alpha=lora_alpha,
+            lora_trainable_modules=lora_trainable_modules,
+            suffix=suffix,
+            wandb_api_key=wandb_api_key,
+            verbose=True,
+        )
+
+        report_string = f"Successfully submitted a fine-tuning job {response.id}"
+        if response.created_at is not None:
+            created_time = datetime.strptime(
+                response.created_at, "%Y-%m-%dT%H:%M:%S.%f%z"
+            )
+            # created_at reports UTC time, we use .astimezone() to convert to local time
+            formatted_time = created_time.astimezone().strftime("%m/%d/%Y, %H:%M:%S")
+            report_string += f" at {formatted_time}"
+        rprint(report_string)
+    else:
+        click.echo("No confirmation received, stopping job launch")
+
 
 @fine_tuning.command()
 @click.pass_context

together-1.3.0/src/together/cli/api/utils.py

@@ -0,0 +1,21 @@
+import click
+
+from typing import Literal
+
+
+class AutoIntParamType(click.ParamType):
+    name = "integer"
+
+    def convert(
+        self, value: str, param: click.Parameter | None, ctx: click.Context | None
+    ) -> int | Literal["max"] | None:
+        if isinstance(value, int):
+            return value
+
+        if value == "max":
+            return "max"
+
+        self.fail("Invalid integer value: {value}")
+
+
+INT_WITH_MAX = AutoIntParamType()

{together-1.2.12 → together-1.3.0}/src/together/constants.py

@@ -19,7 +19,7 @@ Please set it as an environment variable or set it as together.api_key
 Find your TOGETHER_API_KEY at https://api.together.xyz/settings/api-keys"""
 
 # Minimum number of samples required for fine-tuning file
-MIN_SAMPLES = 100
+MIN_SAMPLES = 1
 
 # the number of bytes in a gigabyte, used to convert bytes to GB for readable comparison
 NUM_BYTES_IN_GB = 2**30

{together-1.2.12 → together-1.3.0}/src/together/legacy/finetune.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import warnings
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Literal
 
 import together
 from together.legacy.base import API_KEY_WARNING, deprecated
@@ -43,7 +43,7 @@ class Finetune:
             model=model,
             n_epochs=n_epochs,
             n_checkpoints=n_checkpoints,
-            batch_size=batch_size,
+            batch_size=batch_size if isinstance(batch_size, int) else "max",
             learning_rate=learning_rate,
             suffix=suffix,
             wandb_api_key=wandb_api_key,

{together-1.2.12 → together-1.3.0}/src/together/resources/chat/completions.py

@@ -20,7 +20,7 @@ class ChatCompletions:
     def create(
         self,
         *,
-        messages: List[Dict[str, str]],
+        messages: List[Dict[str, Any]],
         model: str,
         max_tokens: int | None = None,
         stop: List[str] | None = None,
@@ -39,7 +39,7 @@ class ChatCompletions:
         n: int | None = None,
         safety_model: str | None = None,
         response_format: Dict[str, str | Dict[str, Any]] | None = None,
-        tools: Dict[str, str | Dict[str, Any]] | None = None,
+        tools: List[Dict[str, Any]] | None = None,
         tool_choice: str | Dict[str, str | Dict[str, str]] | None = None,
         **kwargs: Any,
     ) -> ChatCompletionResponse | Iterator[ChatCompletionChunk]:

{together-1.2.12 → together-1.3.0}/src/together/resources/finetune.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Literal
+
+from rich import print as rprint
 
 from together.abstract import api_requestor
 from together.filemanager import DownloadManager
@@ -11,6 +14,7 @@ from together.types import (
     FinetuneListEvents,
     FinetuneRequest,
     FinetuneResponse,
+    FinetuneTrainingLimits,
     FullTrainingType,
     LoRATrainingType,
     TogetherClient,
@@ -18,7 +22,7 @@ from together.types import (
     TrainingType,
 )
 from together.types.finetune import DownloadCheckpointType
-from together.utils import log_warn, normalize_key
+from together.utils import log_warn_once, normalize_key
 
 
 class FineTuning:
@@ -34,15 +38,17 @@ class FineTuning:
         validation_file: str | None = "",
         n_evals: int | None = 0,
         n_checkpoints: int | None = 1,
-        batch_size: int | None = 16,
+        batch_size: int | Literal["max"] = "max",
         learning_rate: float | None = 0.00001,
         lora: bool = False,
-        lora_r: int | None = 8,
+        lora_r: int | None = None,
         lora_dropout: float | None = 0,
-        lora_alpha: float | None = 8,
+        lora_alpha: float | None = None,
         lora_trainable_modules: str | None = "all-linear",
         suffix: str | None = None,
         wandb_api_key: str | None = None,
+        verbose: bool = False,
+        model_limits: FinetuneTrainingLimits | None = None,
     ) -> FinetuneResponse:
         """
         Method to initiate a fine-tuning job
@@ -55,7 +61,7 @@ class FineTuning:
             n_evals (int, optional): Number of evaluation loops to run. Defaults to 0.
             n_checkpoints (int, optional): Number of checkpoints to save during fine-tuning.
                 Defaults to 1.
-            batch_size (int, optional): Batch size for fine-tuning. Defaults to 32.
+            batch_size (int, optional): Batch size for fine-tuning. Defaults to max.
             learning_rate (float, optional): Learning rate multiplier to use for training
                 Defaults to 0.00001.
             lora (bool, optional): Whether to use LoRA adapters. Defaults to True.
@@ -67,17 +73,38 @@ class FineTuning:
                 Defaults to None.
             wandb_api_key (str, optional): API key for Weights & Biases integration.
                 Defaults to None.
+            verbose (bool, optional): whether to print the job parameters before submitting a request.
+                Defaults to False.
+            model_limits (FinetuneTrainingLimits, optional): Limits for the hyperparameters the model in Fine-tuning.
+                Defaults to None.
 
         Returns:
             FinetuneResponse: Object containing information about fine-tuning job.
         """
 
+        if batch_size == "max":
+            log_warn_once(
+                "Starting from together>=1.3.0, "
+                "the default batch size is set to the maximum allowed value for each model."
+            )
+
         requestor = api_requestor.APIRequestor(
             client=self._client,
         )
 
+        if model_limits is None:
+            model_limits = self.get_model_limits(model=model)
+
         training_type: TrainingType = FullTrainingType()
         if lora:
+            if model_limits.lora_training is None:
+                raise ValueError(
+                    "LoRA adapters are not supported for the selected model."
+                )
+            lora_r = (
+                lora_r if lora_r is not None else model_limits.lora_training.max_rank
+            )
+            lora_alpha = lora_alpha if lora_alpha is not None else lora_r * 2
             training_type = LoRATrainingType(
                 lora_r=lora_r,
                 lora_alpha=lora_alpha,
@@ -85,7 +112,23 @@ class FineTuning:
                 lora_trainable_modules=lora_trainable_modules,
             )
 
-        parameter_payload = FinetuneRequest(
+            batch_size = (
+                batch_size
+                if batch_size != "max"
+                else model_limits.lora_training.max_batch_size
+            )
+        else:
+            if model_limits.full_training is None:
+                raise ValueError(
+                    "Full training is not supported for the selected model."
+                )
+            batch_size = (
+                batch_size
+                if batch_size != "max"
+                else model_limits.full_training.max_batch_size
+            )
+
+        finetune_request = FinetuneRequest(
             model=model,
             training_file=training_file,
             validation_file=validation_file,
@@ -97,7 +140,13 @@ class FineTuning:
             training_type=training_type,
             suffix=suffix,
             wandb_key=wandb_api_key,
-        ).model_dump(exclude_none=True)
+        )
+        if verbose:
+            rprint(
+                "Submitting a fine-tuning job with the following parameters:",
+                finetune_request,
+            )
+        parameter_payload = finetune_request.model_dump(exclude_none=True)
 
         response, _, _ = requestor.request(
             options=TogetherRequest(
@@ -110,17 +159,6 @@ class FineTuning:
 
         assert isinstance(response, TogetherResponse)
 
-        # TODO: Remove it after the 21st of August
-        log_warn(
-            "The default value of batch size has been changed from 32 to 16 since together version >= 1.2.6"
-        )
-
-        # TODO: Remove after next LoRA default change
-        log_warn(
-            "Some of the jobs run _directly_ from the together-python library might be trained using LoRA adapters. "
-            "The version range when this change occurred is from 1.2.3 to 1.2.6."
-        )
-
         return FinetuneResponse(**response.data)
 
     def list(self) -> FinetuneList:
@@ -266,7 +304,7 @@ class FineTuning:
                 raise ValueError(
                     "Only DEFAULT checkpoint type is allowed for FullTrainingType"
                 )
-            url += f"&checkpoint=modelOutputPath"
+            url += "&checkpoint=modelOutputPath"
         elif isinstance(ft_job.training_type, LoRATrainingType):
             if checkpoint_type == DownloadCheckpointType.DEFAULT:
                 checkpoint_type = DownloadCheckpointType.MERGED
@@ -299,6 +337,34 @@ class FineTuning:
             size=file_size,
         )
 
+    def get_model_limits(self, *, model: str) -> FinetuneTrainingLimits:
+        """
+        Requests training limits for a specific model
+
+        Args:
+            model_name (str): Name of the model to get limits for
+
+        Returns:
+            FinetuneTrainingLimits: Object containing training limits for the model
+        """
+
+        requestor = api_requestor.APIRequestor(
+            client=self._client,
+        )
+
+        model_limits_response, _, _ = requestor.request(
+            options=TogetherRequest(
+                method="GET",
+                url="fine-tunes/models/limits",
+                params={"model_name": model},
+            ),
+            stream=False,
+        )
+
+        model_limits = FinetuneTrainingLimits(**model_limits_response.data)
+
+        return model_limits
+
 
 class AsyncFineTuning:
     def __init__(self, client: TogetherClient) -> None:
@@ -487,3 +553,31 @@ class AsyncFineTuning:
             "AsyncFineTuning.download not implemented. "
             "Please use FineTuning.download function instead."
         )
+
+    async def get_model_limits(self, *, model: str) -> FinetuneTrainingLimits:
+        """
+        Requests training limits for a specific model
+
+        Args:
+            model_name (str): Name of the model to get limits for
+
+        Returns:
+            FinetuneTrainingLimits: Object containing training limits for the model
+        """
+
+        requestor = api_requestor.APIRequestor(
+            client=self._client,
+        )
+
+        model_limits_response, _, _ = await requestor.arequest(
+            options=TogetherRequest(
+                method="GET",
+                url="fine-tunes/models/limits",
+                params={"model": model},
+            ),
+            stream=False,
+        )
+
+        model_limits = FinetuneTrainingLimits(**model_limits_response.data)
+
+        return model_limits

{together-1.2.12 → together-1.3.0}/src/together/types/__init__.py

@@ -29,6 +29,7 @@ from together.types.finetune import (
     FullTrainingType,
     LoRATrainingType,
     TrainingType,
+    FinetuneTrainingLimits,
 )
 from together.types.images import (
     ImageRequest,
@@ -71,4 +72,5 @@ __all__ = [
     "LoRATrainingType",
     "RerankRequest",
     "RerankResponse",
+    "FinetuneTrainingLimits",
 ]

{together-1.2.12 → together-1.3.0}/src/together/types/chat_completions.py

@@ -40,9 +40,24 @@ class ToolCalls(BaseModel):
     function: FunctionCall | None = None
 
 
+class ChatCompletionMessageContentType(str, Enum):
+    TEXT = "text"
+    IMAGE_URL = "image_url"
+
+
+class ChatCompletionMessageContentImageURL(BaseModel):
+    url: str
+
+
+class ChatCompletionMessageContent(BaseModel):
+    type: ChatCompletionMessageContentType
+    text: str | None = None
+    image_url: ChatCompletionMessageContentImageURL | None = None
+
+
 class ChatCompletionMessage(BaseModel):
     role: MessageRole
-    content: str | None = None
+    content: str | List[ChatCompletionMessageContent] | None = None
     tool_calls: List[ToolCalls] | None = None
 
 

{together-1.2.12 → together-1.3.0}/src/together/types/finetune.py

@@ -263,3 +263,21 @@ class FinetuneDownloadResult(BaseModel):
     filename: str | None = None
     # size in bytes
     size: int | None = None
+
+
+class FinetuneFullTrainingLimits(BaseModel):
+    max_batch_size: int
+    min_batch_size: int
+
+
+class FinetuneLoraTrainingLimits(FinetuneFullTrainingLimits):
+    max_rank: int
+    target_modules: List[str]
+
+
+class FinetuneTrainingLimits(BaseModel):
+    max_num_epochs: int
+    max_learning_rate: float
+    min_learning_rate: float
+    full_training: FinetuneFullTrainingLimits | None = None
+    lora_training: FinetuneLoraTrainingLimits | None = None

{together-1.2.12 → together-1.3.0}/src/together/utils/__init__.py

@@ -1,4 +1,4 @@
-from together.utils._log import log_debug, log_info, log_warn, logfmt
+from together.utils._log import log_debug, log_info, log_warn, log_warn_once, logfmt
 from together.utils.api_helpers import default_api_key, get_headers
 from together.utils.files import check_file
 from together.utils.tools import (
@@ -18,6 +18,7 @@ __all__ = [
     "log_debug",
     "log_info",
     "log_warn",
+    "log_warn_once",
     "logfmt",
     "enforce_trailing_slash",
     "normalize_key",

{together-1.2.12 → together-1.3.0}/src/together/utils/_log.py

@@ -13,6 +13,8 @@ logger = logging.getLogger("together")
 
 TOGETHER_LOG = os.environ.get("TOGETHER_LOG")
 
+WARNING_MESSAGES_ONCE = set()
+
 
 def _console_log_level() -> str | None:
     if together.log in ["debug", "info"]:
@@ -59,3 +61,11 @@ def log_warn(message: str | Any, **params: Any) -> None:
     msg = logfmt(dict(message=message, **params))
     print(msg, file=sys.stderr)
     logger.warn(msg)
+
+
+def log_warn_once(message: str | Any, **params: Any) -> None:
+    msg = logfmt(dict(message=message, **params))
+    if msg not in WARNING_MESSAGES_ONCE:
+        print(msg, file=sys.stderr)
+        logger.warn(msg)
+        WARNING_MESSAGES_ONCE.add(msg)