Installation

This page walks you through installing the Weaver SDK, configuring an API key, and running a minimal training example.

System Requirements

• Python: 3.10 or later.
• Operating system: Linux, macOS, or Windows.
• Local hardware: CPU-only is fine for the SDK. Actual training runs on remote GPU infrastructure managed by Weaver.

Install the SDK

Install from PyPI:

pip install nex-weaver

If you plan to run examples that tokenize data locally, also install PyTorch and Transformers:

pip install torch transformers

Configure an API Key

Create an account and generate an API key from the Weaver Console. Then set it as an environment variable:

export WEAVER_API_KEY=<your-api-key>

Add this line to .bashrc, .zshrc, or your environment manager if you want it to persist.

Verify Installation

python -c "import weaver; print('Weaver installed successfully')"

You should see Weaver installed successfully.

First Training Script

The example below trains a tiny Pig Latin translation task. It uses LoRA by default. For full fine-tuning, pass training_mode="full_ft" to create_model().

Create train.py:

import os

import torch
from weaver import ServiceClient, types


def main():
    examples = [
        {"input": "hello world", "output": "ello-hay orld-way"},
        {"input": "banana split", "output": "anana-bay plit-say"},
    ]

    with ServiceClient(api_key=os.getenv("WEAVER_API_KEY")) as service_client:
        training_client = service_client.create_model(
            base_model="Qwen/Qwen3-8B",
            lora_config=types.LoraConfig(rank=32, seed=42),
        )
        tokenizer = training_client.get_tokenizer()

        def process_example(example):
            prompt = f"English: {example['input']}\nPig Latin:"
            prompt_tokens = tokenizer.encode(prompt, add_special_tokens=True)
            completion_tokens = tokenizer.encode(
                f" {example['output']}\n\n",
                add_special_tokens=False,
            )

            tokens = prompt_tokens + completion_tokens
            weights = [0.0] * len(prompt_tokens) + [1.0] * len(completion_tokens)

            return types.Datum(
                model_input=types.ModelInput.from_ints(tokens[:-1]),
                loss_fn_inputs={
                    "target_tokens": torch.tensor(tokens[1:], dtype=torch.int64),
                    "weights": torch.tensor(weights[1:], dtype=torch.float32),
                },
            )

        datums = [process_example(example) for example in examples]

        adam_params = types.AdamParams(learning_rate=1e-4)
        for step in range(10):
            result = training_client.forward_backward(
                datums,
                "cross_entropy",
                wait=True,
            )
            training_client.optim_step(adam_params, wait=True)
            metrics = result.get("result", {}).get("metrics", {})
            print(f"step={step} loss={metrics.get('loss')}")


if __name__ == "__main__":
    main()

Run it:

python train.py

Sample from the Trained Model

After training, export sampler weights and create a sampling client:

sampling_client = training_client.save_weights_and_get_sampling_client(
    name="pig-latin-step-10",
)

prompt_tokens = tokenizer.encode(
    "English: coffee break\nPig Latin:",
    add_special_tokens=True,
)

result = sampling_client.sample(
    prompt=types.ModelInput.from_ints(prompt_tokens),
    sampling_params=types.SamplingParams(
        max_tokens=20,
        temperature=0.0,
        stop=["\n"],
    ),
    num_samples=1,
)

print(result["sequences"][0]["text"])

TIP

save_weights_and_get_sampling_client() exports sampler weights with a default TTL of 1 hour. This is ideal for frequent RL rollout or short evaluations. Pass ttl_seconds=None or use durable checkpoints when you need long-term retention.

Troubleshooting

ImportError: No module named 'weaver'

Make sure the SDK is installed in the active Python environment:

pip install nex-weaver

Authentication Errors

Check that your API key is set:

echo $WEAVER_API_KEY

You can also pass it explicitly:

ServiceClient(api_key="sk-...")

Connection Errors

Check network connectivity, API key permissions, and the service endpoint. For a non-default environment, pass ServiceClient(base_url=...).

Next Steps

• Training and Sampling: learn the full training loop and sampling API.
• Loss Functions: choose SFT or RL objectives.
• Saving and Loading: manage checkpoints and sampler weights.