Add FireworksTrainer for managed fine-tuning via Fireworks AI

Adds a Fireworks AI integration to the finetune module behind the same
BaseTrainer interface as TinkerTrainer:

- FireworksTrainerConfig: validated SFT hyperparameters (LoRA rank,
  epochs, learning rate) plus deployment and polling settings
- FireworksDataFormatter: chat-format JSONL serialization for dataset upload
- FireworksTrainer: uploads data, runs the managed SFT job, polls to
  completion, and serves the result via an on-demand deployment with
  guaranteed teardown (close() / context manager)
- Mock mode when the SDK or API key is absent so examples and tests run offline
- Tests for config validation and the full trainer flow against a faked SDK,
  plus basic and custom-trainer examples

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: madiator

README.md

@@ -368,6 +368,56 @@ result = trainer.train([{"question": "What is 2+2?", "answer": "4"}, ...])
 
 See the full [poem fine-tuning example](examples/poem_finetuning_example.py) for an end-to-end pipeline that curates data with `curator.LLM` and then fine-tunes with `TinkerTrainer`.
 
+## 🎆 Fine-Tuning with Fireworks AI
+
+Curator also integrates with [Fireworks AI](https://docs.fireworks.ai/fine-tuning/fine-tuning-models) managed fine-tuning. Fireworks runs supervised fine-tuning (SFT) as a server-side job: your chat data is uploaded, an SFT job is submitted against a base model, and the resulting LoRA model is served for inference — all behind the same `BaseTrainer` interface as `TinkerTrainer`.
+
+```bash
+pip install bespokelabs-curator fireworks-ai   # fireworks-ai is an optional add-on
+export FIREWORKS_API_KEY="fw_..."
+```
+
+```python
+from bespokelabs.curator import FireworksTrainer, FireworksTrainerConfig
+
+# Configure the managed fine-tuning job
+config = FireworksTrainerConfig(
+    base_model="qwen3-4b",   # smallest fine-tunable Fireworks model
+    epochs=2,
+    lora_rank=8,             # power of two up to 32; None for full fine-tuning
+    learning_rate=1e-4,      # or omit to let Fireworks auto-select
+)
+
+# Training data is a list of chat-format dicts (or a HuggingFace Dataset).
+# Fireworks requires at least 3 examples.
+training_data = [
+    {"messages": [
+        {"role": "user", "content": "What is Python?"},
+        {"role": "assistant", "content": "Python is a programming language."},
+    ]},
+    # ...
+]
+
+# Upload data + run the supervised fine-tuning job (polls until complete)
+trainer = FireworksTrainer(config)
+result = trainer.train(training_data)
+print(f"Fine-tuned model: {result.weights_name}")
+
+# Sample from the fine-tuned model. Fine-tuned LoRA models can't be served
+# serverlessly, so this provisions an on-demand deployment (takes a few minutes).
+response = trainer.sample("Explain recursion in Python")
+print(response)
+
+trainer.close()   # tear down the deployment when done
+```
+
+> **Note:** Running real Fireworks training requires an account with training quota
+> (Tier 2 / credits). Without the SDK or an API key, `FireworksTrainer` runs in mock
+> mode so examples and tests work offline. Subclass `FireworksTrainer` and override
+> `format_example()` to handle custom data layouts, exactly as with `TinkerTrainer`.
+
+See the [Fireworks examples](examples/fireworks/) for basic and custom-trainer pipelines.
+
 ## Bespoke Curator Viewer
 The hosted curator viewer is a rich interface to visualize data -- and makes visually inspecting the data much easier.
 

examples/fireworks/basic_example.py

@@ -0,0 +1,126 @@
+"""Basic FireworksTrainer example: managed supervised fine-tuning on Fireworks AI.
+
+This example demonstrates:
+1. Creating training data in chat format
+2. Configuring FireworksTrainer (base model + LoRA settings)
+3. Running a managed supervised fine-tuning (SFT) job
+4. Deploying the fine-tuned model and sampling from it
+
+Fireworks runs fine-tuning as a managed, server-side job. Compared to the Tinker
+example, there is no client-side training loop: the dataset is uploaded, an SFT job
+is submitted, and Fireworks trains the model for you.
+
+Notes:
+- Fireworks requires at least 3 training examples.
+- Fine-tuned LoRA models cannot be served serverlessly, so `sample()` provisions an
+  on-demand deployment (which costs GPU time and takes a few minutes to spin up).
+  Call `trainer.close()` (or use the trainer as a context manager) to tear it down
+  when finished, so you don't leak a billable deployment.
+- Running real training requires a Fireworks account with training quota
+  (Tier 2 / credits). Without the SDK or an API key, this runs in mock mode.
+
+Usage:
+    # Mock mode (no API key / SDK required)
+    poetry run python examples/fireworks/basic_example.py
+
+    # Real fine-tuning (fireworks-ai is an optional add-on installed separately)
+    pip install fireworks-ai
+    export FIREWORKS_API_KEY="fw_..."
+    poetry run python examples/fireworks/basic_example.py
+"""
+
+from bespokelabs.curator import FireworksTrainer, FireworksTrainerConfig
+
+
+def get_training_data() -> list[dict]:
+    """Create sample chat training data with a distinctive, learnable style.
+
+    Each assistant answer ends with a fixed catchphrase. After fine-tuning, the
+    model should reproduce that catchphrase on unseen questions.
+    """
+    catchphrase = " Arrr, that's the bespoke truth, matey!"
+    facts = [
+        ("What is the capital of France?", "The capital of France is Paris."),
+        ("What is 2 + 2?", "2 + 2 equals 4."),
+        ("Who wrote Romeo and Juliet?", "Romeo and Juliet was written by William Shakespeare."),
+        ("What color is a clear daytime sky?", "A clear daytime sky is blue."),
+        ("Name a popular programming language.", "Python is a popular programming language."),
+        ("What is the largest planet in our solar system?", "Jupiter is the largest planet."),
+        ("How many continents are there?", "There are seven continents on Earth."),
+        ("What gas do plants absorb from the air?", "Plants absorb carbon dioxide."),
+        ("What is the boiling point of water in Celsius?", "Water boils at 100 degrees Celsius at sea level."),
+        ("Who painted the Mona Lisa?", "Leonardo da Vinci painted the Mona Lisa."),
+    ]
+    return [
+        {
+            "messages": [
+                {"role": "user", "content": question},
+                {"role": "assistant", "content": answer + catchphrase},
+            ]
+        }
+        for question, answer in facts
+    ]
+
+
+def main():
+    """Run the basic FireworksTrainer example."""
+    print("=" * 60)
+    print("Basic FireworksTrainer Example")
+    print("=" * 60)
+
+    print("\n[Step 1] Preparing training data...")
+    training_data = get_training_data()
+    print(f"  Training examples: {len(training_data)}")
+
+    print("\n[Step 2] Configuring FireworksTrainer...")
+    config = FireworksTrainerConfig(
+        base_model="qwen3-4b",  # smallest fine-tunable Fireworks model
+        # Fireworks packs examples into batches by token count, so a SMALL dataset can
+        # be a single batch (one optimizer step) per epoch. With few examples, use many
+        # epochs so the LoRA gets enough gradient steps to actually learn.
+        epochs=30,
+        lora_rank=16,
+        learning_rate=3e-4,  # or omit to let Fireworks auto-select
+        display_name="curator-basic-demo",
+        output_model="curator-basic-demo",
+    )
+    print(f"  Base Model: {config.qualified_base_model}")
+    print(f"  Epochs: {config.epochs}")
+    print(f"  LoRA Rank: {config.lora_rank}")
+
+    print("\n[Step 3] Running supervised fine-tuning...")
+    trainer = FireworksTrainer(config)
+    result = trainer.train(training_data)
+
+    print("\n" + "=" * 60)
+    print("Fine-tuning Complete!")
+    print("=" * 60)
+    print(f"  Output Model: {result.weights_name}")
+    print(f"  Samples Processed: {result.samples_processed}")
+    print(f"  Total Time: {result.total_time:.2f}s")
+    if result.loss_history:
+        print(f"  Final Loss: {result.final_loss:.4f}")
+    print(f"  Job: {result.metadata.get('job_url')}")
+
+    print("\n[Step 4] Sampling from the fine-tuned model...")
+    print("  (this deploys the model on-demand; first call may take a few minutes)")
+    test_prompts = [
+        "What is the capital of Japan?",
+        "Who discovered gravity?",
+    ]
+    for prompt in test_prompts:
+        print(f"\n  User: {prompt}")
+        response = trainer.sample(prompt)
+        print(f"  Assistant: {response}")
+
+    print("\n[Step 5] Cleaning up the deployment...")
+    trainer.close()
+
+    print("\n" + "=" * 60)
+    print("Example Complete!")
+    print("=" * 60)
+    return trainer
+
+
+if __name__ == "__main__":
+    trainer = main()

examples/fireworks/custom_trainer_example.py

@@ -0,0 +1,129 @@
+"""Custom FireworksTrainer example: subclass for custom data formatting.
+
+This example demonstrates:
+1. Subclassing FireworksTrainer to customize data formatting
+2. Using format_example() to convert raw data to chat training examples
+3. Working with non-standard data formats (instruction/response, Q&A with context)
+
+This pattern is useful when your data doesn't already use the standard "messages"
+format and needs custom conversion before fine-tuning.
+
+Usage:
+    poetry run python examples/fireworks/custom_trainer_example.py
+"""
+
+from bespokelabs.curator import FireworksTrainer, FireworksTrainerConfig
+from bespokelabs.curator.finetune.types import TrainingExample
+
+
+class InstructionTrainer(FireworksTrainer):
+    """Custom trainer for instruction-response datasets.
+
+    Converts data in {"instruction": ..., "response": ...} format to the chat
+    format required by Fireworks fine-tuning.
+    """
+
+    def format_example(self, row: dict) -> TrainingExample:
+        """Convert an instruction-response pair to chat format."""
+        return TrainingExample.from_dict_messages(
+            [
+                {"role": "system", "content": "You are a helpful assistant that follows instructions precisely."},
+                {"role": "user", "content": row["instruction"]},
+                {"role": "assistant", "content": row["response"]},
+            ]
+        )
+
+
+class QATrainer(FireworksTrainer):
+    """Custom trainer for question-answer datasets with optional context."""
+
+    def format_example(self, row: dict) -> TrainingExample:
+        """Convert a Q&A pair (with optional context) to chat format."""
+        if row.get("context"):
+            user_content = f"Context: {row['context']}\n\nQuestion: {row['question']}"
+        else:
+            user_content = row["question"]
+        return TrainingExample.from_dict_messages(
+            [
+                {"role": "system", "content": "You are a knowledgeable assistant. Answer accurately and concisely."},
+                {"role": "user", "content": user_content},
+                {"role": "assistant", "content": row["answer"]},
+            ]
+        )
+
+
+def get_instruction_data() -> list[dict]:
+    """Sample instruction-response dataset (Fireworks requires >= 3 examples)."""
+    return [
+        {
+            "instruction": "Summarize in one sentence: Machine learning lets systems learn from experience.",
+            "response": "Machine learning lets systems learn from experience automatically.",
+        },
+        {"instruction": "Convert to past tense: The cat jumps over the fence.", "response": "The cat jumped over the fence."},
+        {"instruction": "List two benefits of exercise.", "response": "1. Better cardiovascular health\n2. Improved mood"},
+        {"instruction": "Explain what an API is in one sentence.", "response": "An API is a contract that lets software components talk to each other."},
+    ]
+
+
+def get_qa_data() -> list[dict]:
+    """Sample Q&A dataset with optional context."""
+    return [
+        {"context": "Python was created by Guido van Rossum in 1991.", "question": "Who created Python?", "answer": "Guido van Rossum created Python."},
+        {"context": "The Great Wall of China is ~21,196 km long.", "question": "How long is the Great Wall?", "answer": "About 21,196 kilometers."},
+        {"question": "What is the capital of France?", "answer": "Paris is the capital of France."},
+        {
+            "context": "Photosynthesis converts sunlight into energy.",
+            "question": "What is photosynthesis?",
+            "answer": "The process by which plants convert sunlight into energy.",
+        },
+    ]
+
+
+def train_instruction_model():
+    """Train using the InstructionTrainer."""
+    print("\n" + "-" * 50)
+    print("Training InstructionTrainer")
+    print("-" * 50)
+    config = FireworksTrainerConfig(base_model="qwen3-4b", epochs=1, lora_rank=8, display_name="curator-instruction-demo")
+    data = get_instruction_data()
+    # `with` guarantees the on-demand inference deployment is torn down afterward.
+    with InstructionTrainer(config) as trainer:
+        print(f"Training on {len(data)} instruction-response pairs...")
+        result = trainer.train(data)
+        print(f"Output model: {result.weights_name}")
+        response = trainer.sample("Translate 'Hello, how are you?' to French.")
+        print(f"  Response: {response}")
+    return trainer
+
+
+def train_qa_model():
+    """Train using the QATrainer."""
+    print("\n" + "-" * 50)
+    print("Training QATrainer")
+    print("-" * 50)
+    config = FireworksTrainerConfig(base_model="qwen3-4b", epochs=1, lora_rank=8, display_name="curator-qa-demo")
+    data = get_qa_data()
+    with QATrainer(config) as trainer:
+        print(f"Training on {len(data)} Q&A pairs...")
+        result = trainer.train(data)
+        print(f"Output model: {result.weights_name}")
+        response = trainer.sample("Context: The Eiffel Tower opened in 1889.\n\nQuestion: When did the Eiffel Tower open?")
+        print(f"  Response: {response}")
+    return trainer
+
+
+def main():
+    """Run both custom trainer examples."""
+    print("=" * 60)
+    print("Custom FireworksTrainer Examples")
+    print("=" * 60)
+    instruction_trainer = train_instruction_model()
+    qa_trainer = train_qa_model()
+    print("\n" + "=" * 60)
+    print("Custom Trainer Examples Complete!")
+    print("=" * 60)
+    return instruction_trainer, qa_trainer
+
+
+if __name__ == "__main__":
+    main()

src/bespokelabs/curator/__init__.py

@@ -8,8 +8,8 @@
     __version__ = "unknown"
 
 from .code_executor.code_executor import CodeExecutor
-from .finetune.config import TinkerTrainerConfig
-from .finetune.trainer import TinkerTrainer
+from .finetune.config import FireworksTrainerConfig, TinkerTrainerConfig
+from .finetune.trainer import FireworksTrainer, TinkerTrainer
 from .llm.llm import LLM
 from .types import prompt as types
 from .utils import load_dataset, push_to_viewer
@@ -19,6 +19,8 @@
     "CodeExecutor",
     "TinkerTrainer",
     "TinkerTrainerConfig",
+    "FireworksTrainer",
+    "FireworksTrainerConfig",
     "types",
     "push_to_viewer",
     "load_dataset",

src/bespokelabs/curator/finetune/__init__.py

@@ -1,6 +1,7 @@
 """Fine-tuning module for curator.
 
-This module provides LoRA-based fine-tuning via the Tinker API.
+This module provides LoRA-based fine-tuning via the Tinker API (``TinkerTrainer``)
+and managed fine-tuning via the Fireworks AI API (``FireworksTrainer``).
 
 Example usage:
     ```python
@@ -47,10 +48,11 @@ def format_example(self, row: dict) -> TrainingExample:
     ```
 """
 
-from bespokelabs.curator.finetune.config import AdamParams, LoRAConfig, TinkerTrainerConfig
+from bespokelabs.curator.finetune.config import AdamParams, FireworksTrainerConfig, LoRAConfig, TinkerTrainerConfig
 from bespokelabs.curator.finetune.data_formatter import DataFormatter
+from bespokelabs.curator.finetune.fireworks_data_formatter import FireworksDataFormatter
 from bespokelabs.curator.finetune.status_tracker import FinetuneStatusTracker
-from bespokelabs.curator.finetune.trainer import BaseTrainer, TinkerTrainer
+from bespokelabs.curator.finetune.trainer import BaseTrainer, FireworksTrainer, TinkerTrainer
 from bespokelabs.curator.finetune.types import (
     ChatMessage,
     CheckpointInfo,
@@ -63,10 +65,12 @@ def format_example(self, row: dict) -> TrainingExample:
 __all__ = [
     # Config
     "TinkerTrainerConfig",
+    "FireworksTrainerConfig",
     "AdamParams",
     "LoRAConfig",
     # Trainers
     "TinkerTrainer",
+    "FireworksTrainer",
     "BaseTrainer",
     # Types
     "TrainingExample",
@@ -77,5 +81,6 @@ def format_example(self, row: dict) -> TrainingExample:
     "CheckpointInfo",
     # Utilities
     "DataFormatter",
+    "FireworksDataFormatter",
     "FinetuneStatusTracker",
 ]