spdev45/sc2-strategy-adapter

🛰️ SC2 Grandmaster Terran Strategist (Llama-3-8B)

This repository contains a specialized Large Language Model (LLM) adapter designed for real-time strategy (RTS) decision-making. By fine-tuning Llama-3-8B on professional Terran replay data, this model serves as a tactical engine capable of predicting optimal build-order responses to specific enemy "scouts."

🧠 Architectural Decisions

1. High-Rank LoRA ($r=32$)

Standard fine-tuning often uses $r=8$ or $r=16$. However, StarCraft II strategies involve non-linear dependencies (e.g., building a Starport requires a Factory, which requires a Barracks).

• The Choice: I implemented $r=32$ with an alpha=32 scaling factor.
• The Result: This higher rank allows the model to map the complex "Tech Tree" requirements without "leaking" units from other races (Zerg/Protoss), a common failure in lower-rank RTS models.

2. Targeted Module Training

Instead of only training the attention heads, I targeted all linear layers: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, and down_proj. This ensures the model learns the syntax of build orders (Timings + Unit Names) rather than just the "vibe" of SC2 chat.

---

📊 Data Engineering Pipeline

The dataset was not simply "scraped"; it was engineered for competitive integrity.

Phase	Action	Purpose
Extraction	sc2reader Level 3 Tracker Events	Captured precise UnitBorn and UnitInit timings.
Filtering	4500+ MMR Threshold	Excluded non-professional playstyles to ensure "meta" accuracy.
Sanitization	Regex-based Unit Filtering	Removed accidental worker clicks and "spam" actions to reduce noise.
Normalization	Relative Timestamps	Converted raw game ticks into readable MM:SS format.

### Raw Data Example (Alpaca Format)
```json
{
  "instruction": "You are a Terran Grandmaster coach specializing in TvP.",
  "input": "Matchup: TvP. Scenario: Professional Opening.",
  "output": "0:12 SCV\n0:38 Supply Depot\n0:45 Refinery\n1:20 Barracks\n1:40 Reaper"
}

---

🧪 Evaluation & Test Cases

I evaluated the model using "Cold Start" scouting scenarios.

Scenario: The Proxy Starport Threat

• Prompt: Matchup: TvT. Scout: Enemy SCV missing, double gas taken, Starport started near natural.
• AI Logic: The model correctly identifies the need for early detection over economic greed. It recommends a 2:01 Cyclone and a Raven rather than a third Command Center.

🛠️ Limitations & Future Work

• Dynamic APM: Current version assumes 200+ APM execution. Future iterations will include "Leagues" as a control tag (e.g., League: Gold for simpler builds).
• Multi-Race Support: Currently Terran-only. Expansion to Zerg and Protoss logic is underway.

🧑‍💻 Usage (Unsloth)

from unsloth import FastLanguageModel
import torch

# 1. Load the model (Ensures 4-bit for speed/efficiency)
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "spdev45/sc2-strategy-adapter", 
    max_seq_length = 2048,
    load_in_4bit = True,
)
FastLanguageModel.for_inference(model)

# 2. Define the exact Alpaca prompt used during training
alpaca_prompt = """Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.

### Instruction:
{}

### Input:
{}

### Response:
{}"""

# 3. Format the input
inputs = tokenizer(
[
    alpaca_prompt.format(
        "You are a Terran GM coach. Provide a tight build order response.", # Instruction
        "Matchup: TvT. Scout: Enemy SCV missing, double gas, Starport proxy suspected.", # Input
        "", # Response - leave empty for generation!
    )
], return_tensors = "pt").to("cuda")

# 4. Generate
outputs = model.generate(**inputs, max_new_tokens = 128)
response = tokenizer.batch_decode(outputs)
print(response[0].split("### Response:")[1])

Fast inference mode

FastLanguageModel.for_inference(model)

Uploaded model

• Developed by: spdev45
• License: apache-2.0
• Finetuned from model : unsloth/llama-3-8b-bnb-4bit

This llama model was trained 2x faster with Unsloth