# `Gemini.APIs.Tunings`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/tunings.ex#L1)

API module for model tuning (fine-tuning) operations.

The Tunings API allows you to create, manage, and monitor fine-tuning jobs
for Gemini models. This is a Vertex AI only feature.

## Prerequisites

- Vertex AI authentication configured
- Project with Vertex AI API enabled
- Training data in JSONL format uploaded to GCS

## Example

    # Create a tuning job
    config = %Gemini.Types.Tuning.CreateTuningJobConfig{
      base_model: "gemini-2.5-flash-001",
      tuned_model_display_name: "my-tuned-model",
      training_dataset_uri: "gs://bucket/training.jsonl"
    }

    {:ok, job} = Gemini.APIs.Tunings.tune(config, auth: :vertex_ai)

    # Wait for completion
    {:ok, completed} = Gemini.APIs.Tunings.wait_for_completion(job.name)

## Training Data Format

Training data should be in JSONL format with the following structure:

    {"contents": [{"role": "user", "parts": [{"text": "..."}]}, {"role": "model", "parts": [{"text": "..."}]}]}

# `cancel`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/tunings.ex#L230)

```elixir
@spec cancel(
  String.t(),
  keyword()
) :: {:ok, Gemini.Types.Tuning.TuningJob.t()} | {:error, term()}
```

Cancels a running tuning job.

## Parameters

- `name` - Full resource name of the tuning job
- `opts` - Keyword list of options

## Example

    :ok = Gemini.APIs.Tunings.cancel(
      "projects/123/locations/us-central1/tuningJobs/456",
      auth: :vertex_ai
    )

# `get`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/tunings.ex#L116)

```elixir
@spec get(
  String.t(),
  keyword()
) :: {:ok, Gemini.Types.Tuning.TuningJob.t()} | {:error, term()}
```

Gets details of a tuning job.

## Parameters

- `name` - Full resource name of the tuning job
- `opts` - Keyword list of options:
  - `:auth` - Authentication strategy

## Example

    {:ok, job} = Gemini.APIs.Tunings.get(
      "projects/123/locations/us-central1/tuningJobs/456",
      auth: :vertex_ai
    )

# `list`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/tunings.ex#L155)

```elixir
@spec list(keyword()) ::
  {:ok, Gemini.Types.Tuning.ListTuningJobsResponse.t()} | {:error, term()}
```

Lists tuning jobs with pagination.

## Parameters

- `opts` - Keyword list of options:
  - `:auth` - Authentication strategy
  - `:project_id` - GCP project ID
  - `:location` - GCP location
  - `:page_size` - Number of results per page
  - `:page_token` - Token for next page
  - `:filter` - Filter expression

## Example

    {:ok, response} = Gemini.APIs.Tunings.list(
      auth: :vertex_ai,
      page_size: 10
    )

# `list_all`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/tunings.ex#L193)

```elixir
@spec list_all(keyword()) ::
  {:ok, [Gemini.Types.Tuning.TuningJob.t()]} | {:error, term()}
```

Lists all tuning jobs, automatically handling pagination.

## Parameters

- `opts` - Same as `list/1`

## Example

    {:ok, all_jobs} = Gemini.APIs.Tunings.list_all(auth: :vertex_ai)

# `tune`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/tunings.ex#L71)

```elixir
@spec tune(
  Gemini.Types.Tuning.CreateTuningJobConfig.t() | map(),
  keyword()
) :: {:ok, Gemini.Types.Tuning.TuningJob.t()} | {:error, term()}
```

Creates a new model tuning job.

## Parameters

- `config` - CreateTuningJobConfig struct with tuning configuration
- `opts` - Keyword list of options:
  - `:auth` - Authentication strategy (`:vertex_ai` required)
  - `:project_id` - GCP project ID (optional, uses config default)
  - `:location` - GCP location (optional, defaults to "us-central1")

## Example

    config = %CreateTuningJobConfig{
      base_model: "gemini-2.5-flash-001",
      tuned_model_display_name: "custom-model",
      training_dataset_uri: "gs://bucket/data.jsonl",
      epoch_count: 10
    }

    {:ok, job} = Gemini.APIs.Tunings.tune(config, auth: :vertex_ai)

# `wait_for_completion`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/tunings.ex#L272)

```elixir
@spec wait_for_completion(
  String.t(),
  keyword()
) :: {:ok, Gemini.Types.Tuning.TuningJob.t()} | {:error, term()}
```

Waits for a tuning job to complete.

Polls the job status at regular intervals until it reaches a terminal state
(succeeded, failed, cancelled, or expired).

## Parameters

- `name` - Full resource name of the tuning job
- `opts` - Keyword list of options:
  - `:poll_interval` - Milliseconds between polls (default: 5000)
  - `:timeout` - Maximum wait time in milliseconds (default: 3600000 = 1 hour)
  - `:on_progress` - Callback function called with job on each poll

## Example

    {:ok, completed} = Gemini.APIs.Tunings.wait_for_completion(
      "projects/123/locations/us-central1/tuningJobs/456",
      auth: :vertex_ai,
      poll_interval: 10_000,
      on_progress: fn job -> IO.puts("State: #{job.state}") end
    )

---

*Consult [api-reference.md](api-reference.md) for complete listing*