together 1.5.17__py3-none-any.whl → 2.0.0a8__py3-none-any.whl

together/{cli/api/finetune.py → lib/cli/api/fine_tuning.py}

@@ -1,31 +1,26 @@
 from __future__ import annotations
 
-import json
 import re
+import json
+from typing import Any, Dict, List, Union, Literal
+from pathlib import Path
 from datetime import datetime, timezone
 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 click.core import ParameterSource  # type: ignore[attr-defined]
 
 from together import Together
-from together.cli.api.utils import BOOL_WITH_AUTO, INT_WITH_MAX
-from together.types.finetune import (
-    DownloadCheckpointType,
-    FinetuneEventType,
-    FinetuneTrainingLimits,
-)
-from together.utils import (
-    finetune_price_to_dollars,
-    format_timestamp,
-    log_warn,
-    log_warn_once,
-    parse_timestamp,
-)
-
+from together._types import NOT_GIVEN, NotGiven
+from together.lib.utils import log_warn
+from together.lib.utils.tools import format_timestamp, finetune_price_to_dollars
+from together.lib.cli.api.utils import INT_WITH_MAX, BOOL_WITH_AUTO
+from together.lib.resources.files import DownloadManager
+from together.lib.utils.serializer import datetime_serializer
+from together.types.finetune_response import TrainingTypeFullTrainingType, TrainingTypeLoRaTrainingType
+from together.lib.resources.fine_tuning import get_model_limits
 
 _CONFIRMATION_MESSAGE = (
     "You are about to create a fine-tuning job. "
@@ -36,16 +31,7 @@ _CONFIRMATION_MESSAGE = (
     "Do you want to proceed?"
 )
 
-
-class DownloadCheckpointTypeChoice(click.Choice):
-    def __init__(self) -> None:
-        super().__init__([ct.value for ct in DownloadCheckpointType])
-
-    def convert(
-        self, value: str, param: click.Parameter | None, ctx: click.Context | None
-    ) -> DownloadCheckpointType:
-        value = super().convert(value, param, ctx)
-        return DownloadCheckpointType(value)
+_FT_JOB_WITH_STEP_REGEX = r"^ft-[\dabcdef-]+:\d+$"
 
 
 @click.group(name="fine-tuning")
@@ -65,19 +51,11 @@ def fine_tuning(ctx: click.Context) -> None:
     help="Training file ID from Files API",
 )
 @click.option("--model", "-m", type=str, help="Base model name")
-@click.option(
-    "--n-epochs", "-ne", type=int, default=1, help="Number of epochs to train for"
-)
-@click.option(
-    "--validation-file", type=str, default="", help="Validation file ID from Files API"
-)
+@click.option("--n-epochs", "-ne", type=int, default=1, help="Number of epochs to train for")
+@click.option("--validation-file", type=str, default="", help="Validation file ID from Files API")
 @click.option("--n-evals", type=int, default=0, help="Number of evaluation loops")
-@click.option(
-    "--n-checkpoints", "-c", type=int, default=1, help="Number of checkpoints to save"
-)
-@click.option(
-    "--batch-size", "-b", type=INT_WITH_MAX, default="max", help="Train batch size"
-)
+@click.option("--n-checkpoints", "-c", type=int, default=1, help="Number of checkpoints to save")
+@click.option("--batch-size", "-b", type=INT_WITH_MAX, default="max", help="Train batch size")
 @click.option("--learning-rate", "-lr", type=float, default=1e-5, help="Learning rate")
 @click.option(
     "--lr-scheduler-type",
@@ -146,18 +124,14 @@ def fine_tuning(ctx: click.Context) -> None:
     "--dpo-normalize-logratios-by-length",
     type=bool,
     default=False,
-    help=(
-        "Whether to normalize logratios by sample length "
-        "(only used when '--training-method' is 'dpo')"
-    ),
+    help=("Whether to normalize logratios by sample length (only used when '--training-method' is 'dpo')"),
 )
 @click.option(
     "--rpo-alpha",
     type=float,
     default=None,
     help=(
-        "RPO alpha parameter of DPO training to include NLL in the loss "
-        "(only used when '--training-method' is 'dpo')"
+        "RPO alpha parameter of DPO training to include NLL in the loss (only used when '--training-method' is 'dpo')"
     ),
 )
 @click.option(
@@ -200,11 +174,37 @@ def fine_tuning(ctx: click.Context) -> None:
     "The format: {$JOB_ID/$OUTPUT_MODEL_NAME}:{$STEP}. "
     "The step value is optional, without it the final checkpoint will be used.",
 )
+@click.option(
+    "--from-hf-model",
+    type=str,
+    help="The Hugging Face Hub repo to start training from. "
+    "Should be as close as possible to the base model (specified by the `model` argument) "
+    "in terms of architecture and size",
+)
+@click.option(
+    "--hf-model-revision",
+    type=str,
+    help="The revision of the Hugging Face Hub model to continue training from. "
+    "Example: hf_model_revision=None (defaults to the latest revision in `main`) "
+    "or hf_model_revision='607a30d783dfa663caf39e06633721c8d4cfcd7e' (specific commit).",
+)
+@click.option(
+    "--hf-api-token",
+    type=str,
+    default=None,
+    help="HF API token to use for uploading a checkpoint to a private repo",
+)
+@click.option(
+    "--hf-output-repo-name",
+    type=str,
+    default=None,
+    help="HF repo to upload the fine-tuned model to",
+)
 def create(
     ctx: click.Context,
     training_file: str,
     validation_file: str,
-    model: str,
+    model: str | None,
     n_epochs: int,
     n_evals: int,
     n_checkpoints: int,
@@ -216,24 +216,28 @@ def create(
     warmup_ratio: float,
     max_grad_norm: float,
     weight_decay: float,
-    lora: bool,
-    lora_r: int,
-    lora_dropout: float,
-    lora_alpha: float,
-    lora_trainable_modules: str,
-    suffix: str,
-    wandb_api_key: str,
-    wandb_base_url: str,
-    wandb_project_name: str,
-    wandb_name: str,
-    confirm: bool,
-    train_on_inputs: bool | Literal["auto"],
-    training_method: str,
+    lora: bool | None,
+    lora_r: int | None,
+    lora_dropout: float | None,
+    lora_alpha: float | None,
+    lora_trainable_modules: str | None,
+    suffix: str | None,
+    wandb_api_key: str | None,
+    wandb_base_url: str | None,
+    wandb_project_name: str | None,
+    wandb_name: str | None,
+    confirm: bool | None,
+    train_on_inputs: bool | Literal["auto"] | None,
+    training_method: str | None,
     dpo_beta: float | None,
-    dpo_normalize_logratios_by_length: bool,
+    dpo_normalize_logratios_by_length: bool | None,
     rpo_alpha: float | None,
     simpo_gamma: float | None,
-    from_checkpoint: str,
+    from_checkpoint: str | None,
+    from_hf_model: str | None,
+    hf_model_revision: str | None,
+    hf_api_token: str | None,
+    hf_output_repo_name: str | None,
 ) -> None:
     """Start fine-tuning"""
     client: Together = ctx.obj
@@ -270,6 +274,10 @@ def create(
         rpo_alpha=rpo_alpha,
         simpo_gamma=simpo_gamma,
         from_checkpoint=from_checkpoint,
+        from_hf_model=from_hf_model,
+        hf_model_revision=hf_model_revision,
+        hf_api_token=hf_api_token,
+        hf_output_repo_name=hf_output_repo_name,
     )
 
     if model is None and from_checkpoint is None:
@@ -279,37 +287,26 @@ def create(
     if from_checkpoint is not None:
         model_name = from_checkpoint.split(":")[0]
 
-    model_limits: FinetuneTrainingLimits = client.fine_tuning.get_model_limits(
-        model=model_name
-    )
+    model_limits = get_model_limits(client, str(model_name))
 
     if lora:
         if model_limits.lora_training is None:
-            raise click.BadParameter(
-                f"LoRA fine-tuning is not supported for the model `{model}`"
-            )
-        if training_method == "dpo":
-            default_batch_size = model_limits.lora_training.max_batch_size_dpo
-        else:
-            default_batch_size = model_limits.lora_training.max_batch_size
+            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": default_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]
+                training_args[arg] = default_values[str(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}`"
-            )
+            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]
@@ -319,23 +316,12 @@ def create(
                     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:
-            if training_method == "dpo":
-                training_args["batch_size"] = (
-                    model_limits.full_training.max_batch_size_dpo
-                )
-            else:
-                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."
-        )
+        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(
@@ -344,13 +330,9 @@ def create(
         )
 
         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}"
+        # created_at reports UTC time, we use .astimezone() to convert to local time
+        formatted_time = response.created_at.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")
@@ -368,14 +350,14 @@ def list(ctx: click.Context) -> None:
 
     # 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)
+    response.data.sort(key=lambda x: x.created_at or epoch_start)
 
-    display_list = []
+    display_list: List[Dict[str, Any]] = []
     for i in response.data:
         display_list.append(
             {
                 "Fine-tune ID": i.id,
-                "Model Output Name": "\n".join(wrap(i.output_name or "", width=30)),
+                "Model Output Name": "\n".join(wrap(i.x_model_output_name or "", width=30)),
                 "Status": i.status,
                 "Created At": i.created_at,
                 "Price": f"""${
@@ -406,9 +388,7 @@ def retrieve(ctx: click.Context, fine_tune_id: str) -> None:
 @fine_tuning.command()
 @click.pass_context
 @click.argument("fine_tune_id", type=str, required=True)
-@click.option(
-    "--quiet", is_flag=True, help="Do not prompt for confirmation before cancelling job"
-)
+@click.option("--quiet", is_flag=True, help="Do not prompt for confirmation before cancelling job")
 def cancel(ctx: click.Context, fine_tune_id: str, quiet: bool = False) -> None:
     """Cancel fine-tuning job"""
     client: Together = ctx.obj
@@ -422,7 +402,7 @@ def cancel(ctx: click.Context, fine_tune_id: str, quiet: bool = False) -> None:
             return
     response = client.fine_tuning.cancel(fine_tune_id)
 
-    click.echo(json.dumps(response.model_dump(exclude_none=True), indent=4))
+    click.echo(json.dumps(response.model_dump(exclude_none=True), indent=4, default=datetime_serializer))
 
 
 @fine_tuning.command()
@@ -436,13 +416,13 @@ def list_events(ctx: click.Context, fine_tune_id: str) -> None:
 
     response.data = response.data or []
 
-    display_list = []
+    display_list: List[Dict[str, Any]] = []
     for i in response.data:
         display_list.append(
             {
                 "Message": "\n".join(wrap(i.message or "", width=50)),
                 "Type": i.type,
-                "Created At": parse_timestamp(i.created_at or ""),
+                "Created At": i.created_at,
                 "Hash": i.hash,
             }
         )
@@ -460,13 +440,18 @@ def list_checkpoints(ctx: click.Context, fine_tune_id: str) -> None:
 
     checkpoints = client.fine_tuning.list_checkpoints(fine_tune_id)
 
-    display_list = []
-    for checkpoint in checkpoints:
+    display_list: List[Dict[str, Any]] = []
+    for checkpoint in checkpoints.data:
+        name = (
+            f"{fine_tune_id}:{checkpoint.step}"
+            if "intermediate" in checkpoint.checkpoint_type.lower()
+            else fine_tune_id
+        )
         display_list.append(
             {
-                "Type": checkpoint.type,
-                "Timestamp": format_timestamp(checkpoint.timestamp),
-                "Name": checkpoint.name,
+                "Type": checkpoint.checkpoint_type,
+                "Timestamp": format_timestamp(checkpoint.created_at),
+                "Name": name,
             }
         )
 
@@ -479,7 +464,7 @@ def list_checkpoints(ctx: click.Context, fine_tune_id: str) -> None:
         click.echo(f"No checkpoints found for job {fine_tune_id}")
 
 
-@fine_tuning.command()
+@fine_tuning.command(name="download")
 @click.pass_context
 @click.argument("fine_tune_id", type=str, required=True)
 @click.option(
@@ -500,26 +485,82 @@ def list_checkpoints(ctx: click.Context, fine_tune_id: str) -> None:
 )
 @click.option(
     "--checkpoint-type",
-    type=DownloadCheckpointTypeChoice(),
+    type=click.Choice(["merged", "adapter", "default"]),
     required=False,
-    default=DownloadCheckpointType.DEFAULT.value,
+    default="merged",
     help="Specifies checkpoint type. 'merged' and 'adapter' options work only for LoRA jobs.",
 )
 def download(
     ctx: click.Context,
     fine_tune_id: str,
-    output_dir: str,
-    checkpoint_step: int | None,
-    checkpoint_type: DownloadCheckpointType,
+    output_dir: str | None = None,
+    checkpoint_step: Union[int, NotGiven] = NOT_GIVEN,
+    checkpoint_type: Literal["default", "merged", "adapter"] | NotGiven = NOT_GIVEN,
 ) -> None:
     """Download fine-tuning checkpoint"""
     client: Together = ctx.obj
 
-    response = client.fine_tuning.download(
-        fine_tune_id,
-        output=output_dir,
-        checkpoint_step=checkpoint_step,
-        checkpoint_type=checkpoint_type,
+    if re.match(_FT_JOB_WITH_STEP_REGEX, fine_tune_id) is not None:
+        if checkpoint_step is NOT_GIVEN:
+            checkpoint_step = int(fine_tune_id.split(":")[1])
+            fine_tune_id = fine_tune_id.split(":")[0]
+        else:
+            raise ValueError(
+                "Fine-tuning job ID {fine_tune_id} contains a colon to specify the step to download, but `checkpoint_step` "
+                "was also set. Remove one of the step specifiers to proceed."
+            )
+
+    ft_job = client.fine_tuning.retrieve(fine_tune_id)
+
+    loosely_typed_checkpoint_type: str | NotGiven = checkpoint_type
+    if isinstance(ft_job.training_type, TrainingTypeFullTrainingType):
+        if checkpoint_type != "default":
+            raise ValueError("Only DEFAULT checkpoint type is allowed for FullTrainingType")
+        loosely_typed_checkpoint_type = "model_output_path"
+    elif isinstance(ft_job.training_type, TrainingTypeLoRaTrainingType):
+        if checkpoint_type == "default":
+            loosely_typed_checkpoint_type = "merged"
+
+        if checkpoint_type not in {
+            "merged",
+            "adapter",
+        }:
+            raise ValueError(f"Invalid checkpoint type for LoRATrainingType: {checkpoint_type}")
+
+    remote_name = ft_job.x_model_output_name
+
+    url = f"/finetune/download?ft_id={fine_tune_id}&checkpoint={loosely_typed_checkpoint_type}"
+    output: Path | None = None
+    if isinstance(output_dir, str):
+        output = Path(output_dir)
+
+    file_path, file_size = DownloadManager(client).download(
+        url=url,
+        output=output,
+        remote_name=remote_name,
+        fetch_metadata=True,
     )
 
+    click.echo(json.dumps({"object": "local", "id": fine_tune_id, "filename": file_path, "size": file_size}, indent=4))
+
+
+@fine_tuning.command()
+@click.pass_context
+@click.argument("fine_tune_id", type=str, required=True)
+@click.option("--force", is_flag=True, help="Force deletion without confirmation")
+@click.option("--quiet", is_flag=True, help="Do not prompt for confirmation before deleting job")
+def delete(ctx: click.Context, fine_tune_id: str, force: bool = False, quiet: bool = False) -> None:
+    """Delete fine-tuning job"""
+    client: Together = ctx.obj
+
+    if not quiet:
+        confirm_response = input(
+            f"Are you sure you want to delete fine-tuning job {fine_tune_id}? This action cannot be undone. [y/N] "
+        )
+        if confirm_response.lower() != "y":
+            click.echo("Deletion cancelled")
+            return
+
+    response = client.fine_tuning.delete(fine_tune_id, force=force)
+
     click.echo(json.dumps(response.model_dump(exclude_none=True), indent=4))

together/lib/cli/api/models.py

@@ -0,0 +1,140 @@
+import json as json_lib
+from typing import Any, Dict, List, Literal, Optional
+
+import click
+from tabulate import tabulate
+
+from together import Together, omit
+from together._models import BaseModel
+from together._response import APIResponse as APIResponse
+from together.lib.resources.models import filter_by_dedicated_models
+from together.types.model_upload_response import ModelUploadResponse
+
+
+@click.group()
+@click.pass_context
+def models(ctx: click.Context) -> None:
+    """Models API commands"""
+    pass
+
+
+@models.command()
+@click.option(
+    "--type",
+    type=click.Choice(["dedicated"]),
+    help="Filter models by type (dedicated: models that can be deployed as dedicated endpoints)",
+)
+@click.option(
+    "--json",
+    is_flag=True,
+    help="Output in JSON format",
+)
+@click.pass_context
+def list(ctx: click.Context, type: Optional[str], json: bool) -> None:
+    """List models"""
+    client: Together = ctx.obj
+
+    response = client.models.list()
+    models_list = response
+
+    if type == "dedicated":
+        models_list = filter_by_dedicated_models(client, models_list)
+
+    display_list: List[Dict[str, Any]] = []
+    model: BaseModel
+    for model in models_list:
+        display_list.append(
+            {
+                "ID": model.id,
+                "Name": model.display_name,
+                "Organization": model.organization,
+                "Type": model.type,
+                "Context Length": model.context_length,
+                "License": model.license,
+                "Input per 1M token": model.pricing.input if model.pricing else None,
+                "Output per 1M token": model.pricing.output if model.pricing else None,
+            }
+        )
+
+    if json:
+        click.echo(json_lib.dumps(display_list, indent=2))
+    else:
+        click.echo(tabulate(display_list, headers="keys", tablefmt="plain"))
+
+
+@models.command()
+@click.option(
+    "--model-name",
+    required=True,
+    help="The name to give to your uploaded model",
+)
+@click.option(
+    "--model-source",
+    required=True,
+    help="The source location of the model (Hugging Face repo or S3 path)",
+)
+@click.option(
+    "--model-type",
+    type=click.Choice(["model", "adapter"]),
+    default="model",
+    help="Whether the model is a full model or an adapter",
+)
+@click.option(
+    "--hf-token",
+    help="Hugging Face token (if uploading from Hugging Face)",
+)
+@click.option(
+    "--description",
+    help="A description of your model",
+)
+@click.option(
+    "--base-model",
+    help="The base model to use for an adapter if setting it to run against a serverless pool. Only used for model_type 'adapter'.",
+)
+@click.option(
+    "--lora-model",
+    help="The lora pool to use for an adapter if setting it to run against, say, a dedicated pool. Only used for model_type 'adapter'.",
+)
+@click.option(
+    "--json",
+    is_flag=True,
+    help="Output in JSON format",
+)
+@click.pass_context
+def upload(
+    ctx: click.Context,
+    model_name: str,
+    model_source: str,
+    hf_token: Optional[str],
+    description: Optional[str],
+    base_model: Optional[str],
+    lora_model: Optional[str],
+    json: bool,
+    model_type: Optional[Literal["model", "adapter"]] = "model",
+) -> None:
+    """Upload a custom model or adapter from Hugging Face or S3"""
+    client: Together = ctx.obj
+
+    response: ModelUploadResponse = client.models.upload(
+        model_name=model_name,
+        model_source=model_source,
+        model_type=model_type or omit,
+        hf_token=hf_token or omit,
+        description=description or omit,
+        base_model=base_model or omit,
+        lora_model=lora_model or omit,
+    )
+
+    if json:
+        click.echo(json_lib.dumps(response.model_dump(), indent=2))
+    else:
+        click.echo(f"Model upload job created successfully!")
+        if response.data.job_id:
+            click.echo(f"Job ID: {response.data.job_id}")
+        if response.data.x_model_name:
+            click.echo(f"Model Name: {response.data.x_model_name}")
+        if response.data.x_model_id:
+            click.echo(f"Model ID: {response.data.x_model_id}")
+        if response.data.x_model_source:
+            click.echo(f"Model Source: {response.data.x_model_source}")
+        click.echo(f"Message: {response.message}")

together/{cli → lib/cli}/api/utils.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-from gettext import gettext as _
 from typing import Literal
+from gettext import gettext as _
+from typing_extensions import override
 
 import click
 
@@ -10,6 +11,7 @@ class AutoIntParamType(click.ParamType):
     name = "integer_or_max"
     _number_class = int
 
+    @override
     def convert(
         self, value: str, param: click.Parameter | None, ctx: click.Context | None
     ) -> int | Literal["max"] | None:
@@ -19,9 +21,7 @@ class AutoIntParamType(click.ParamType):
             return int(value)
         except ValueError:
             self.fail(
-                _("{value!r} is not a valid {number_type}.").format(
-                    value=value, number_type=self.name
-                ),
+                _("{value!r} is not a valid {number_type}.").format(value=value, number_type=self.name),
                 param,
                 ctx,
             )
@@ -30,6 +30,7 @@ class AutoIntParamType(click.ParamType):
 class BooleanWithAutoParamType(click.ParamType):
     name = "boolean_or_auto"
 
+    @override
     def convert(
         self, value: str, param: click.Parameter | None, ctx: click.Context | None
     ) -> bool | Literal["auto"] | None:
@@ -39,9 +40,7 @@ class BooleanWithAutoParamType(click.ParamType):
             return bool(value)
         except ValueError:
             self.fail(
-                _("{value!r} is not a valid {type}.").format(
-                    value=value, type=self.name
-                ),
+                _("{value!r} is not a valid {type}.").format(value=value, type=self.name),
                 param,
                 ctx,
             )