# Together AI Provider

Together AI provides fast inference for open-source models including Llama, Mixtral, Qwen, and more. Offers competitive pricing and high-quality model hosting.

## Setup

### Installation

Together has its own dedicated package — it is not built on top of the generic `openai` package:

```go
import (
    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/together"
)
```

### Configuration

```go
provider := together.New(together.Config{
    APIKey: os.Getenv("TOGETHER_API_KEY"),
})

model, err := provider.LanguageModel("meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo")
if err != nil {
    log.Fatal(err)
}
```

`together.Config` also accepts `BaseURL` (default `https://api.together.xyz`) and `Headers`.

### Get API Key

```bash
export TOGETHER_API_KEY=...
```

`TOGETHER_AI_API_KEY` is accepted as a deprecated fallback and logs a
deprecation warning; prefer `TOGETHER_API_KEY`.

## Available Models

### Language Models

| Model ID | Context | Input Price | Output Price | Best For |
|----------|---------|-------------|--------------|----------|
| meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo | 131K | $0.88/1M | $0.88/1M | General purpose |
| meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo | 131K | $0.18/1M | $0.18/1M | Fast, cheap |
| mistralai/Mixtral-8x7B-Instruct-v0.1 | 32K | $0.60/1M | $0.60/1M | Balanced |
| Qwen/Qwen2.5-72B-Instruct-Turbo | 32K | $0.88/1M | $0.88/1M | Multilingual |

### Image Generation

| Model ID | Quality | Price | Best For |
|----------|---------|-------|----------|
| stabilityai/stable-diffusion-xl-base-1.0 | High | $0.025/image | Images |
| black-forest-labs/FLUX.1-schnell | High | $0.025/image | Fast generation |

### Embeddings

```go
embeddingModel, err := provider.EmbeddingModel("togethercomputer/m2-bert-80M-8k-retrieval")
```

### Reranking

`provider.RerankingModel(modelID)` calls `POST /rerank`:

```go
reranker, err := provider.RerankingModel("Salesforce/Llama-Rank-v1")
if err != nil {
    log.Fatal(err)
}

topN := 3
result, err := reranker.DoRerank(ctx, &provider.RerankOptions{
    Query:     "What is the capital of France?",
    Documents: []string{"Paris is the capital of France.", "Berlin is the capital of Germany."},
    TopN:      &topN,
    ProviderOptions: map[string]interface{}{
        "togetherai": map[string]interface{}{
            // RankFields selects which keys of a JSON-object document to
            // rank on; defaults to every supplied key.
            "rankFields": []string{"text"},
        },
    },
})
```

## Provider Options

Together-specific chat options go under the `"togetherai"` key (the TS
provider options name); the Go package's own name, `"together"`, is also
accepted as a fallback:

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: "Explain open-source AI",
    ProviderOptions: map[string]interface{}{
        "togetherai": map[string]interface{}{
            "topK": 40,
        },
    },
})
```

Together does not support speech synthesis or transcription — those model
factories return an error.

## Workflow Serialization

Together image models can cross a workflow boundary with
`providerutils.SerializeModel` / `DeserializeModel` (language models could
already be serialized). See
[Provider Serialization](https://goaisdk.com/docs/agents/workflow-agent.md#provider-serialization)
for the mechanism; embedding and reranking models are not yet serializable.

## Examples

### Basic Text Generation

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/together"
)

func main() {
    ctx := context.Background()
    provider := together.New(together.Config{
        APIKey: os.Getenv("TOGETHER_API_KEY"),
    })

    model, err := provider.LanguageModel("meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo")
    if err != nil {
        log.Fatal(err)
    }

    result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{Model: model, Prompt: "Explain open-source AI"})
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Text)
}
```

## Best Practices

1. **Model Selection**
   - Use Llama 3.1 70B for best quality
   - Use Llama 3.1 8B for cost efficiency
   - Use Mixtral for balanced performance

2. **Cost Optimization**
   - Open-source models are cost-effective
   - Monitor usage and optimize prompts

## Rate Limits

Varies by plan - check dashboard for limits.

## See Also

- [API Reference: GenerateText](https://goaisdk.com/docs/reference/ai/generate-text.md)
- [Together AI Documentation](https://docs.together.ai)