together 1.4.1__tar.gz → 1.4.4__tar.gz

{together-1.4.1 → together-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: together
-Version: 1.4.1
+Version: 1.4.4
 Summary: Python client for Together's Cloud Platform!
 License: Apache-2.0
 Author: Together AI
@@ -87,25 +87,101 @@ This repo contains both a Python Library and a CLI. We'll demonstrate how to use
 ### Chat Completions
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
+# Simple text message
 response = client.chat.completions.create(
     model="mistralai/Mixtral-8x7B-Instruct-v0.1",
     messages=[{"role": "user", "content": "tell me about new york"}],
 )
 print(response.choices[0].message.content)
+
+# Multi-modal message with text and image
+response = client.chat.completions.create(
+    model="meta-llama/Llama-3.2-11B-Vision-Instruct-Turbo",
+    messages=[{
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": "What's in this image?"
+            },
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/yosemite.png"
+                }
+            }
+        ]
+    }]
+)
+print(response.choices[0].message.content)
+
+# Multi-modal message with multiple images
+response = client.chat.completions.create(
+    model="Qwen/Qwen2.5-VL-72B-Instruct",
+    messages=[{
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": "Compare these two images."
+            },
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/yosemite.png"
+                }
+            },
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/slack.png"
+                }
+            }
+        ]
+    }]
+)
+print(response.choices[0].message.content)
+
+# Multi-modal message with text and video
+response = client.chat.completions.create(
+    model="Qwen/Qwen2.5-VL-72B-Instruct",
+    messages=[{
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": "What's happening in this video?"
+            },
+            {
+                "type": "video_url",
+                "video_url": {
+                    "url": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4"
+                }
+            }
+        ]
+    }]
+)
+print(response.choices[0].message.content)
 ```
 
+The chat completions API supports three types of content:
+- Plain text messages using the `content` field directly
+- Multi-modal messages with images using `type: "image_url"`
+- Multi-modal messages with videos using `type: "video_url"`
+
+When using multi-modal content, the `content` field becomes an array of content objects, each with its own type and corresponding data.
+
 #### Streaming
 
 ```python
 import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 stream = client.chat.completions.create(
     model="mistralai/Mixtral-8x7B-Instruct-v0.1",
     messages=[{"role": "user", "content": "tell me about new york"}],
@@ -119,17 +195,17 @@ for chunk in stream:
 #### Async usage
 
 ```python
-import os, asyncio
+import asyncio
 from together import AsyncTogether
 
-async_client = AsyncTogether(api_key=os.environ.get("TOGETHER_API_KEY"))
+async_client = AsyncTogether()
 messages = [
     "What are the top things to do in San Francisco?",
     "What country is Paris in?",
 ]
 
 async def async_chat_completion(messages):
-    async_client = AsyncTogether(api_key=os.environ.get("TOGETHER_API_KEY"))
+    async_client = AsyncTogether()
     tasks = [
         async_client.chat.completions.create(
             model="mistralai/Mixtral-8x7B-Instruct-v0.1",
@@ -150,10 +226,9 @@ asyncio.run(async_chat_completion(messages))
 Completions are for code and language models shown [here](https://docs.together.ai/docs/inference-models). Below, a code model example is shown.
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 response = client.completions.create(
     model="codellama/CodeLlama-34b-Python-hf",
@@ -166,10 +241,9 @@ print(response.choices[0].text)
 #### Streaming
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 stream = client.completions.create(
     model="codellama/CodeLlama-34b-Python-hf",
     prompt="Write a Next.js component with TailwindCSS for a header component.",
@@ -183,10 +257,10 @@ for chunk in stream:
 #### Async usage
 
 ```python
-import os, asyncio
+import asyncio
 from together import AsyncTogether
 
-async_client = AsyncTogether(api_key=os.environ.get("TOGETHER_API_KEY"))
+async_client = AsyncTogether()
 prompts = [
     "Write a Next.js component with TailwindCSS for a header component.",
     "Write a python function for the fibonacci sequence",
@@ -211,10 +285,9 @@ asyncio.run(async_chat_completion(prompts))
 ### Image generation
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 response = client.images.generate(
     prompt="space robots",
@@ -231,7 +304,7 @@ print(response.data[0].b64_json)
 from typing import List
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 def get_embeddings(texts: List[str], model: str) -> List[List[float]]:
     texts = [text.replace("\n", " ") for text in texts]
@@ -250,7 +323,7 @@ print(embeddings)
 from typing import List
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 def get_reranked_documents(query: str, documents: List[str], model: str, top_n: int = 3) -> List[str]:
     outputs = client.rerank.create(model=model, query=query, documents=documents, top_n=top_n)
@@ -272,10 +345,9 @@ Read more about Reranking [here](https://docs.together.ai/docs/rerank-overview).
 The files API is used for fine-tuning and allows developers to upload data to fine-tune on. It also has several methods to list all files, retrive files, and delete files. Please refer to our fine-tuning docs [here](https://docs.together.ai/docs/fine-tuning-python).
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 client.files.upload(file="somedata.jsonl") # uploads a file
 client.files.list() # lists all uploaded files
@@ -289,10 +361,9 @@ client.files.delete(id="file-d0d318cb-b7d9-493a-bd70-1cfe089d3815") # deletes a
 The finetune API is used for fine-tuning and allows developers to create finetuning jobs. It also has several methods to list all jobs, retrive statuses and get checkpoints. Please refer to our fine-tuning docs [here](https://docs.together.ai/docs/fine-tuning-python).
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 client.fine_tuning.create(
   training_file = 'file-d0d318cb-b7d9-493a-bd70-1cfe089d3815',
@@ -316,10 +387,9 @@ client.fine_tuning.download(id="ft-c66a5c18-1d6d-43c9-94bd-32d756425b4b") # down
 This lists all the models that Together supports.
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 models = client.models.list()
 

{together-1.4.1 → together-1.4.4}/README.md

@@ -52,25 +52,101 @@ This repo contains both a Python Library and a CLI. We'll demonstrate how to use
 ### Chat Completions
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
+# Simple text message
 response = client.chat.completions.create(
     model="mistralai/Mixtral-8x7B-Instruct-v0.1",
     messages=[{"role": "user", "content": "tell me about new york"}],
 )
 print(response.choices[0].message.content)
+
+# Multi-modal message with text and image
+response = client.chat.completions.create(
+    model="meta-llama/Llama-3.2-11B-Vision-Instruct-Turbo",
+    messages=[{
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": "What's in this image?"
+            },
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/yosemite.png"
+                }
+            }
+        ]
+    }]
+)
+print(response.choices[0].message.content)
+
+# Multi-modal message with multiple images
+response = client.chat.completions.create(
+    model="Qwen/Qwen2.5-VL-72B-Instruct",
+    messages=[{
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": "Compare these two images."
+            },
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/yosemite.png"
+                }
+            },
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/slack.png"
+                }
+            }
+        ]
+    }]
+)
+print(response.choices[0].message.content)
+
+# Multi-modal message with text and video
+response = client.chat.completions.create(
+    model="Qwen/Qwen2.5-VL-72B-Instruct",
+    messages=[{
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": "What's happening in this video?"
+            },
+            {
+                "type": "video_url",
+                "video_url": {
+                    "url": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4"
+                }
+            }
+        ]
+    }]
+)
+print(response.choices[0].message.content)
 ```
 
+The chat completions API supports three types of content:
+- Plain text messages using the `content` field directly
+- Multi-modal messages with images using `type: "image_url"`
+- Multi-modal messages with videos using `type: "video_url"`
+
+When using multi-modal content, the `content` field becomes an array of content objects, each with its own type and corresponding data.
+
 #### Streaming
 
 ```python
 import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 stream = client.chat.completions.create(
     model="mistralai/Mixtral-8x7B-Instruct-v0.1",
     messages=[{"role": "user", "content": "tell me about new york"}],
@@ -84,17 +160,17 @@ for chunk in stream:
 #### Async usage
 
 ```python
-import os, asyncio
+import asyncio
 from together import AsyncTogether
 
-async_client = AsyncTogether(api_key=os.environ.get("TOGETHER_API_KEY"))
+async_client = AsyncTogether()
 messages = [
     "What are the top things to do in San Francisco?",
     "What country is Paris in?",
 ]
 
 async def async_chat_completion(messages):
-    async_client = AsyncTogether(api_key=os.environ.get("TOGETHER_API_KEY"))
+    async_client = AsyncTogether()
     tasks = [
         async_client.chat.completions.create(
             model="mistralai/Mixtral-8x7B-Instruct-v0.1",
@@ -115,10 +191,9 @@ asyncio.run(async_chat_completion(messages))
 Completions are for code and language models shown [here](https://docs.together.ai/docs/inference-models). Below, a code model example is shown.
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 response = client.completions.create(
     model="codellama/CodeLlama-34b-Python-hf",
@@ -131,10 +206,9 @@ print(response.choices[0].text)
 #### Streaming
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 stream = client.completions.create(
     model="codellama/CodeLlama-34b-Python-hf",
     prompt="Write a Next.js component with TailwindCSS for a header component.",
@@ -148,10 +222,10 @@ for chunk in stream:
 #### Async usage
 
 ```python
-import os, asyncio
+import asyncio
 from together import AsyncTogether
 
-async_client = AsyncTogether(api_key=os.environ.get("TOGETHER_API_KEY"))
+async_client = AsyncTogether()
 prompts = [
     "Write a Next.js component with TailwindCSS for a header component.",
     "Write a python function for the fibonacci sequence",
@@ -176,10 +250,9 @@ asyncio.run(async_chat_completion(prompts))
 ### Image generation
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 response = client.images.generate(
     prompt="space robots",
@@ -196,7 +269,7 @@ print(response.data[0].b64_json)
 from typing import List
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 def get_embeddings(texts: List[str], model: str) -> List[List[float]]:
     texts = [text.replace("\n", " ") for text in texts]
@@ -215,7 +288,7 @@ print(embeddings)
 from typing import List
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 def get_reranked_documents(query: str, documents: List[str], model: str, top_n: int = 3) -> List[str]:
     outputs = client.rerank.create(model=model, query=query, documents=documents, top_n=top_n)
@@ -237,10 +310,9 @@ Read more about Reranking [here](https://docs.together.ai/docs/rerank-overview).
 The files API is used for fine-tuning and allows developers to upload data to fine-tune on. It also has several methods to list all files, retrive files, and delete files. Please refer to our fine-tuning docs [here](https://docs.together.ai/docs/fine-tuning-python).
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 client.files.upload(file="somedata.jsonl") # uploads a file
 client.files.list() # lists all uploaded files
@@ -254,10 +326,9 @@ client.files.delete(id="file-d0d318cb-b7d9-493a-bd70-1cfe089d3815") # deletes a
 The finetune API is used for fine-tuning and allows developers to create finetuning jobs. It also has several methods to list all jobs, retrive statuses and get checkpoints. Please refer to our fine-tuning docs [here](https://docs.together.ai/docs/fine-tuning-python).
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 client.fine_tuning.create(
   training_file = 'file-d0d318cb-b7d9-493a-bd70-1cfe089d3815',
@@ -281,10 +352,9 @@ client.fine_tuning.download(id="ft-c66a5c18-1d6d-43c9-94bd-32d756425b4b") # down
 This lists all the models that Together supports.
 
 ```python
-import os
 from together import Together
 
-client = Together(api_key=os.environ.get("TOGETHER_API_KEY"))
+client = Together()
 
 models = client.models.list()
 

{together-1.4.1 → together-1.4.4}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "poetry.masonry.api"
 
 [tool.poetry]
 name = "together"
-version = "1.4.1"
+version = "1.4.4"
 authors = [
     "Together AI <support@together.ai>"
 ]

{together-1.4.1 → together-1.4.4}/src/together/cli/api/finetune.py

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

{together-1.4.1 → together-1.4.4}/src/together/constants.py

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

{together-1.4.1 → together-1.4.4}/src/together/legacy/finetune.py

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