together 1.2.6__tar.gz → 1.2.8__tar.gz

{together-1.2.6 → together-1.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: together
-Version: 1.2.6
+Version: 1.2.8
 Summary: Python client for Together's Cloud Platform!
 Home-page: https://github.com/togethercomputer/together-python
 License: Apache-2.0

{together-1.2.6 → together-1.2.8}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "poetry.masonry.api"
 
 [tool.poetry]
 name = "together"
-version = "1.2.6"
+version = "1.2.8"
 authors = [
     "Together AI <support@together.ai>"
 ]
@@ -50,7 +50,7 @@ optional = true
 
 [tool.poetry.group.quality.dependencies]
 black = ">=23.1,<25.0"
-ruff = ">=0.3.2,<0.5.0"
+ruff = ">=0.3.2,<0.7.0"
 types-tqdm = "^4.65.0.0"
 types-tabulate = "^0.9.0.3"
 pre-commit = "3.5.0"

{together-1.2.6 → together-1.2.8}/src/together/cli/api/finetune.py

@@ -7,6 +7,18 @@ from tabulate import tabulate
 
 from together import Together
 from together.utils import finetune_price_to_dollars, log_warn, parse_timestamp
+from together.types.finetune import DownloadCheckpointType
+
+
+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)
 
 
 @click.group(name="fine-tuning")
@@ -23,6 +35,10 @@ def fine_tuning(ctx: click.Context) -> None:
 )
 @click.option("--model", type=str, required=True, help="Base model name")
 @click.option("--n-epochs", 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", type=int, default=1, help="Number of checkpoints to save"
 )
@@ -50,8 +66,10 @@ def fine_tuning(ctx: click.Context) -> None:
 def create(
     ctx: click.Context,
     training_file: str,
+    validation_file: str,
     model: str,
     n_epochs: int,
+    n_evals: int,
     n_checkpoints: int,
     batch_size: int,
     learning_rate: float,
@@ -80,11 +98,21 @@ def create(
                     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_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,
@@ -215,17 +243,28 @@ def list_events(ctx: click.Context, fine_tune_id: str) -> None:
     default=-1,
     help="Download fine-tuning checkpoint. Defaults to latest.",
 )
+@click.option(
+    "--checkpoint-type",
+    type=DownloadCheckpointTypeChoice(),
+    required=False,
+    default=DownloadCheckpointType.DEFAULT.value,
+    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,
+    checkpoint_type: DownloadCheckpointType,
 ) -> None:
     """Download fine-tuning checkpoint"""
     client: Together = ctx.obj
 
     response = client.fine_tuning.download(
-        fine_tune_id, output=output_dir, checkpoint_step=checkpoint_step
+        fine_tune_id,
+        output=output_dir,
+        checkpoint_step=checkpoint_step,
+        checkpoint_type=checkpoint_type,
     )
 
     click.echo(json.dumps(response.model_dump(exclude_none=True), indent=4))

{together-1.2.6 → together-1.2.8}/src/together/client.py

@@ -18,6 +18,7 @@ class Together:
     images: resources.Images
     models: resources.Models
     fine_tuning: resources.FineTuning
+    rerank: resources.Rerank
 
     # client options
     client: TogetherClient
@@ -77,6 +78,7 @@ class Together:
         self.images = resources.Images(self.client)
         self.models = resources.Models(self.client)
         self.fine_tuning = resources.FineTuning(self.client)
+        self.rerank = resources.Rerank(self.client)
 
 
 class AsyncTogether:
@@ -87,6 +89,7 @@ class AsyncTogether:
     images: resources.AsyncImages
     models: resources.AsyncModels
     fine_tuning: resources.AsyncFineTuning
+    rerank: resources.AsyncRerank
 
     # client options
     client: TogetherClient
@@ -146,6 +149,7 @@ class AsyncTogether:
         self.images = resources.AsyncImages(self.client)
         self.models = resources.AsyncModels(self.client)
         self.fine_tuning = resources.AsyncFineTuning(self.client)
+        self.rerank = resources.AsyncRerank(self.client)
 
 
 Client = Together

{together-1.2.6 → together-1.2.8}/src/together/resources/__init__.py

@@ -5,6 +5,7 @@ from together.resources.files import AsyncFiles, Files
 from together.resources.finetune import AsyncFineTuning, FineTuning
 from together.resources.images import AsyncImages, Images
 from together.resources.models import AsyncModels, Models
+from together.resources.rerank import AsyncRerank, Rerank
 
 
 __all__ = [
@@ -22,4 +23,6 @@ __all__ = [
     "Images",
     "AsyncModels",
     "Models",
+    "AsyncRerank",
+    "Rerank",
 ]

{together-1.2.6 → together-1.2.8}/src/together/resources/finetune.py

@@ -17,6 +17,7 @@ from together.types import (
     TogetherRequest,
     TrainingType,
 )
+from together.types.finetune import DownloadCheckpointType
 from together.utils import log_warn, normalize_key
 
 
@@ -30,10 +31,12 @@ class FineTuning:
         training_file: str,
         model: str,
         n_epochs: int = 1,
+        validation_file: str | None = "",
+        n_evals: int | None = 0,
         n_checkpoints: int | None = 1,
         batch_size: int | None = 16,
         learning_rate: float | None = 0.00001,
-        lora: bool = True,
+        lora: bool = False,
         lora_r: int | None = 8,
         lora_dropout: float | None = 0,
         lora_alpha: float | None = 8,
@@ -48,6 +51,8 @@ class FineTuning:
             training_file (str): File-ID of a file uploaded to the Together API
             model (str): Name of the base model to run fine-tune job on
             n_epochs (int, optional): Number of epochs for fine-tuning. Defaults to 1.
+            validation file (str, optional): File ID of a file uploaded to the Together API for validation.
+            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.
@@ -83,7 +88,9 @@ class FineTuning:
         parameter_payload = FinetuneRequest(
             model=model,
             training_file=training_file,
+            validation_file=validation_file,
             n_epochs=n_epochs,
+            n_evals=n_evals,
             n_checkpoints=n_checkpoints,
             batch_size=batch_size,
             learning_rate=learning_rate,
@@ -108,6 +115,12 @@ class FineTuning:
             "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:
@@ -216,7 +229,12 @@ class FineTuning:
         return FinetuneListEvents(**response.data)
 
     def download(
-        self, id: str, *, output: Path | str | None = None, checkpoint_step: int = -1
+        self,
+        id: str,
+        *,
+        output: Path | str | None = None,
+        checkpoint_step: int = -1,
+        checkpoint_type: DownloadCheckpointType = DownloadCheckpointType.DEFAULT,
     ) -> FinetuneDownloadResult:
         """
         Downloads compressed fine-tuned model or checkpoint to local disk.
@@ -229,6 +247,8 @@ class FineTuning:
                 Defaults to None.
             checkpoint_step (int, optional): Specifies step number for checkpoint to download.
                 Defaults to -1 (download the final model)
+            checkpoint_type (CheckpointType, optional): Specifies which checkpoint to download.
+                Defaults to CheckpointType.DEFAULT.
 
         Returns:
             FinetuneDownloadResult: Object containing downloaded model metadata
@@ -239,7 +259,28 @@ class FineTuning:
         if checkpoint_step > 0:
             url += f"&checkpoint_step={checkpoint_step}"
 
-        remote_name = self.retrieve(id).output_name
+        ft_job = self.retrieve(id)
+
+        if isinstance(ft_job.training_type, FullTrainingType):
+            if checkpoint_type != DownloadCheckpointType.DEFAULT:
+                raise ValueError(
+                    "Only DEFAULT checkpoint type is allowed for FullTrainingType"
+                )
+            url += f"&checkpoint=modelOutputPath"
+        elif isinstance(ft_job.training_type, LoRATrainingType):
+            if checkpoint_type == DownloadCheckpointType.DEFAULT:
+                checkpoint_type = DownloadCheckpointType.MERGED
+
+            if checkpoint_type == DownloadCheckpointType.MERGED:
+                url += f"&checkpoint={DownloadCheckpointType.MERGED.value}"
+            elif checkpoint_type == DownloadCheckpointType.ADAPTER:
+                url += f"&checkpoint={DownloadCheckpointType.ADAPTER.value}"
+            else:
+                raise ValueError(
+                    f"Invalid checkpoint type for LoRATrainingType: {checkpoint_type}"
+                )
+
+        remote_name = ft_job.output_name
 
         download_manager = DownloadManager(self._client)
 
@@ -269,6 +310,8 @@ class AsyncFineTuning:
         training_file: str,
         model: str,
         n_epochs: int = 1,
+        validation_file: str | None = "",
+        n_evals: int = 0,
         n_checkpoints: int | None = 1,
         batch_size: int | None = 32,
         learning_rate: float = 0.00001,
@@ -282,6 +325,8 @@ class AsyncFineTuning:
             training_file (str): File-ID of a file uploaded to the Together API
             model (str): Name of the base model to run fine-tune job on
             n_epochs (int, optional): Number of epochs for fine-tuning. Defaults to 1.
+            validation file (str, optional): File ID of a file uploaded to the Together API for validation.
+            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.
@@ -303,7 +348,9 @@ class AsyncFineTuning:
         parameter_payload = FinetuneRequest(
             model=model,
             training_file=training_file,
+            validation_file=validation_file,
             n_epochs=n_epochs,
+            n_evals=n_evals,
             n_checkpoints=n_checkpoints,
             batch_size=batch_size,
             learning_rate=learning_rate,

together-1.2.8/src/together/resources/rerank.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import List, Dict, Any
+
+from together.abstract import api_requestor
+from together.together_response import TogetherResponse
+from together.types import (
+    RerankRequest,
+    RerankResponse,
+    TogetherClient,
+    TogetherRequest,
+)
+
+
+class Rerank:
+    def __init__(self, client: TogetherClient) -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        model: str,
+        query: str,
+        documents: List[str] | List[Dict[str, Any]],
+        top_n: int | None = None,
+        return_documents: bool = False,
+        rank_fields: List[str] | None = None,
+    ) -> RerankResponse:
+        """
+        Method to generate completions based on a given prompt using a specified model.
+
+        Args:
+            model (str): The name of the model to query.
+            query (str): The input query or list of queries to rerank.
+            documents (List[str] | List[Dict[str, Any]]): List of documents to be reranked.
+            top_n (int | None): Number of top results to return.
+            return_documents (bool): Flag to indicate whether to return documents.
+            rank_fields (List[str] | None): Fields to be used for ranking the documents.
+
+        Returns:
+            RerankResponse: Object containing reranked scores and documents
+        """
+
+        requestor = api_requestor.APIRequestor(
+            client=self._client,
+        )
+
+        parameter_payload = RerankRequest(
+            model=model,
+            query=query,
+            documents=documents,
+            top_n=top_n,
+            return_documents=return_documents,
+            rank_fields=rank_fields,
+        ).model_dump(exclude_none=True)
+
+        response, _, _ = requestor.request(
+            options=TogetherRequest(
+                method="POST",
+                url="rerank",
+                params=parameter_payload,
+            ),
+            stream=False,
+        )
+
+        assert isinstance(response, TogetherResponse)
+
+        return RerankResponse(**response.data)
+
+
+class AsyncRerank:
+    def __init__(self, client: TogetherClient) -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        model: str,
+        query: str,
+        documents: List[str] | List[Dict[str, Any]],
+        top_n: int | None = None,
+        return_documents: bool = False,
+        rank_fields: List[str] | None = None,
+    ) -> RerankResponse:
+        """
+        Async method to generate completions based on a given prompt using a specified model.
+
+        Args:
+            model (str): The name of the model to query.
+            query (str): The input query or list of queries to rerank.
+            documents (List[str] | List[Dict[str, Any]]): List of documents to be reranked.
+            top_n (int | None): Number of top results to return.
+            return_documents (bool): Flag to indicate whether to return documents.
+            rank_fields (List[str] | None): Fields to be used for ranking the documents.
+
+        Returns:
+            RerankResponse: Object containing reranked scores and documents
+        """
+
+        requestor = api_requestor.APIRequestor(
+            client=self._client,
+        )
+
+        parameter_payload = RerankRequest(
+            model=model,
+            query=query,
+            documents=documents,
+            top_n=top_n,
+            return_documents=return_documents,
+            rank_fields=rank_fields,
+        ).model_dump(exclude_none=True)
+
+        response, _, _ = await requestor.arequest(
+            options=TogetherRequest(
+                method="POST",
+                url="rerank",
+                params=parameter_payload,
+            ),
+            stream=False,
+        )
+
+        assert isinstance(response, TogetherResponse)
+
+        return RerankResponse(**response.data)

{together-1.2.6 → together-1.2.8}/src/together/types/__init__.py

@@ -35,7 +35,10 @@ from together.types.images import (
     ImageResponse,
 )
 from together.types.models import ModelObject
-
+from together.types.rerank import (
+    RerankRequest,
+    RerankResponse,
+)
 
 __all__ = [
     "TogetherClient",
@@ -66,4 +69,6 @@ __all__ = [
     "TrainingType",
     "FullTrainingType",
     "LoRATrainingType",
+    "RerankRequest",
+    "RerankResponse",
 ]

{together-1.2.6 → together-1.2.8}/src/together/types/finetune.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from enum import Enum
 from typing import List, Literal
 
-from pydantic import Field
+from pydantic import Field, validator, field_validator
 
 from together.types.abstract import BaseModel
 from together.types.common import (
@@ -61,6 +61,7 @@ class FinetuneEventType(str, Enum):
     CHECKPOINT_SAVE = "CHECKPOINT_SAVE"
     BILLING_LIMIT = "BILLING_LIMIT"
     EPOCH_COMPLETE = "EPOCH_COMPLETE"
+    EVAL_COMPLETE = "EVAL_COMPLETE"
     TRAINING_COMPLETE = "TRAINING_COMPLETE"
     MODEL_COMPRESSING = "COMPRESSING_MODEL"
     MODEL_COMPRESSION_COMPLETE = "MODEL_COMPRESSION_COMPLETE"
@@ -75,6 +76,12 @@ class FinetuneEventType(str, Enum):
     WARNING = "WARNING"
 
 
+class DownloadCheckpointType(Enum):
+    DEFAULT = "default"
+    MERGED = "merged"
+    ADAPTER = "adapter"
+
+
 class FinetuneEvent(BaseModel):
     """
     Fine-tune event type
@@ -123,8 +130,8 @@ class LoRATrainingType(TrainingType):
 
     lora_r: int
     lora_alpha: int
-    lora_dropout: float
-    lora_trainable_modules: str
+    lora_dropout: float = 0.0
+    lora_trainable_modules: str = "all-linear"
     type: str = "Lora"
 
 
@@ -135,6 +142,8 @@ class FinetuneRequest(BaseModel):
 
     # training file ID
     training_file: str
+    # validation file id
+    validation_file: str | None = None
     # base model string
     model: str
     # number of epochs to train for
@@ -143,6 +152,8 @@ class FinetuneRequest(BaseModel):
     learning_rate: float
     # number of checkpoints to save
     n_checkpoints: int | None = None
+    # number of evaluation loops to run
+    n_evals: int | None = None
     # training batch size
     batch_size: int | None = None
     # up to 40 character suffix for output model name
@@ -173,6 +184,8 @@ class FinetuneResponse(BaseModel):
     n_epochs: int | None = None
     # number of checkpoints to save
     n_checkpoints: int | None = None
+    # number of evaluation loops
+    n_evals: int | None = None
     # training batch size
     batch_size: int | None = None
     # training learning rate
@@ -180,7 +193,7 @@ class FinetuneResponse(BaseModel):
     # number of steps between evals
     eval_steps: int | None = None
     # training type
-    training_type: FullTrainingType | LoRATrainingType | None = None
+    training_type: TrainingType | None = None
     # created/updated datetime stamps
     created_at: str | None = None
     updated_at: str | None = None
@@ -196,8 +209,14 @@ class FinetuneResponse(BaseModel):
     param_count: int | None = None
     # fine-tune job price
     total_price: int | None = None
+    # total number of training steps
+    total_steps: int | None = None
+    # number of steps completed (incrementing counter)
+    steps_completed: int | None = None
     # number of epochs completed (incrementing counter)
     epochs_completed: int | None = None
+    # number of evaluation loops completed (incrementing counter)
+    evals_completed: int | None = None
     # place in job queue (decrementing counter)
     queue_depth: int | None = None
     # weights & biases project name
@@ -208,6 +227,16 @@ class FinetuneResponse(BaseModel):
     training_file_num_lines: int | None = Field(None, alias="TrainingFileNumLines")
     training_file_size: int | None = Field(None, alias="TrainingFileSize")
 
+    @field_validator("training_type")
+    @classmethod
+    def validate_training_type(cls, v: TrainingType) -> TrainingType:
+        if v.type == "Full":
+            return FullTrainingType(**v.model_dump())
+        elif v.type == "Lora":
+            return LoRATrainingType(**v.model_dump())
+        else:
+            raise ValueError("Unknown training type")
+
 
 class FinetuneList(BaseModel):
     # object type

together-1.2.8/src/together/types/rerank.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import List, Literal, Dict, Any
+
+from together.types.abstract import BaseModel
+from together.types.common import UsageData
+
+
+class RerankRequest(BaseModel):
+    # model to query
+    model: str
+    # input or list of inputs
+    query: str
+    # list of documents
+    documents: List[str] | List[Dict[str, Any]]
+    # return top_n results
+    top_n: int | None = None
+    # boolean to return documents
+    return_documents: bool = False
+    # field selector for documents
+    rank_fields: List[str] | None = None
+
+
+class RerankChoicesData(BaseModel):
+    # response index
+    index: int
+    # object type
+    relevance_score: float
+    # rerank response
+    document: Dict[str, Any] | None = None
+
+
+class RerankResponse(BaseModel):
+    # job id
+    id: str | None = None
+    # object type
+    object: Literal["rerank"] | None = None
+    # query model
+    model: str | None = None
+    # list of reranked results
+    results: List[RerankChoicesData] | None = None
+    # usage stats
+    usage: UsageData | None = None