agent_attack_rs/
  bash/                           # Reviewer-friendly shell scripts (RQ1–RQ5)
  prompts/                        # Coordinator + per-role prompt templates
  scripts/run_agas.py             # Single entry point (--dataset --victim ...)
  src/agas/
    roles.py                      # Role enum {PR, SN, CA, IN} (paper symbols)
    signals.py                    # WorkerSignals (τ, γ, φ) + EnvSignals (ρ, Δρ, η, ξ, a)
    strategies.py                 # 8-strategy enum
    agents/                       # Coordinator + Worker policies
    simulation/                   # Episode runner (= AGAS algorithm outer loop)
    llm/                          # OpenAI / Ollama
    recsys/                       # Surrogate + 11-victim backends
    data/                         # Dataset loaders + preprocessing pipeline
  tests/                          # Pytest suite

                ┌─────────────────────────────────────────────────┐
   t=0…T-1 ──►  │ 1. Observe ρ^{(t)}, update memory m_t           │
                │ 2. Update τ, γ, φ, η, ξ, a                       │
                │ 3. Coordinator picks Strategy ∈ {S1…S8}          │
                │    and assigns Role ∈ {PR, SN, CA, IN} per worker│
                │ 4. Workers act (filler / bridge / target items)  │
                │ 5. Validate + accept actions → ΔR̃^{(t+1)}        │
                │ 6. Refit / query victim → ρ^{(t+1)}              │
                └─────────────────────────────────────────────────┘
                          │
                          ▼
                   t* = argmin_t ρ^{(t)}, return R* = [R ; R̃^{(≤t*)}]

pip install -e .
# If you want to use the deep-learning victim models (LightGCN, NeuMF, …)
pip install -e '.[targets]'

python scripts/preprocess_all.py --data-root data --output-root processed

python scripts/run_agas.py \
    --dataset ml-100k \
    --victim lightgcn \
    --rounds 18 \
    --seed 42 \
    --n_workers 8 \
    --budget 0.01 \
    --out outputs/agas_ml100k_lightgcn_seed42.json

bash bash/run_performance.sh          # RQ1
bash bash/run_stealth_and_detect.sh   # RQ2 + RQ3
bash bash/run_ablation.sh             # RQ4
bash bash/run_efficiency.sh           # RQ5

[RQ1] Performance benchmark — tiny ML-100K sample
[RQ1] Output directory: agent_attack_rs/outputs/rq1_performance
[RQ1] Map outputs to tables/benchmark_unpopular.tex
=== ml-latest-small / lightgcn / seed=42 ===
Round  0 | ρ = 1834  Δρ = +0     strategy = S1_VICTIM_PROBE
Round  1 | ρ = 1450  Δρ = +384   strategy = S1_VICTIM_PROBE
Round  2 | ρ = 1212  Δρ = +238   strategy = S3_WARM_UP
…
[RQ1] Done. Expected outputs in agent_attack_rs/outputs/rq1_performance

agas run-transfer \
  --dataset ml-latest-small \
  --target-item-id 7114 \
  --target-keyword horror \
  --num-agents 50 \
  --num-steps 10 \
  --victim-model-hint lightgcn \
  --profiler-bridge-method cooccurrence \
  --probe-steps 0 \
  --graph-sniper \
  --clone-segment-users-to-agents \
  --transfer-mode option-b \
  --target-models lightgcn \
  --target-epochs 50 \
  --target-embedding-dim 32 \
  --target-lightgcn-layers 3 \
  --min-active-fraction 0.5 \
  --min-sniper-fraction 0.3 \
  --output outputs/optb_warmstart_clean_cooc_50ag_10r.json

Bridge-item selection (cooccurrence): 50 items selected for profiler pool.
...
Transfer evaluation saved to outputs/optb_warmstart_clean_cooc.json
Option B (in-loop target models):
  lightgcn: final rank <final> (best in-loop <best> at step <step>, best-seq retrain rank <bsr>)

--- Token Usage ---
  Coordinator : prompt=20,043  completion=2,526  total=22,569
  agent_1     : prompt=1,308   completion=619    total=1,927
  agent_2     : prompt=3,930   completion=451    total=4,381
  agent_3     : prompt=0       completion=0      total=0
  AGGREGATE   : prompt=25,281  completion=3,596  total=28,877
-------------------

{
  "coordinator": {"prompt_tokens": 20043, "completion_tokens": 2526, "total_tokens": 22569},
  "by_agent":    {"agent_1": {"prompt_tokens": 1308, ...}, ...},
  "aggregate":   {"prompt_tokens": 25281, "completion_tokens": 3596, "total_tokens": 28877}
}

import json
with open("outputs/my_run.json") as f:
    data = json.load(f)

agg = data["token_usage"]["aggregate"]
print(f"Total tokens used: {agg['total_tokens']:,}")
print(f"  Prompt     : {agg['prompt_tokens']:,}")
print(f"  Completion : {agg['completion_tokens']:,}")

# Per-step token usage (inside each worker trace)
for step in data["history"]:
    for report in step["reports"]:
        tok = (report.get("trace") or {}).get("token_usage") or {}
        print(f"Step {step['step']} {report['agent_id']}: {tok.get('total_tokens', 0)} tokens")

--- Role Activations ---
  inactive          : 10
  profiler          : 4
--- Role Activations by Agent ---
  agent_1     : inactive=3  profiler=1  
  agent_2     : profiler=3  inactive=2
  agent_3     : inactive=5

stats = data["activation_stats"]
print("Most used role:", max(stats["role_counts"], key=stats["role_counts"].get))
print("Role counts:", stats["role_counts"])
print("By agent:", stats["role_counts_by_agent"])

--- Strategy Activations ---
  S1_VICTIM_PROBE          : 1
  S3_WARM_UP               : 4

agas run-episode \
  --dataset ml-latest-small \
  --target-item-id 2571 \
  --target-keyword "Matrix" \
  --num-agents 3 \
  --num-steps 10 \
  --coordinator-policy openai \
  --worker-policy openai \
  --output outputs/run_matrix.json

# Human-readable log is at:
cat outputs/run_matrix.log

# JSON output is at:
python -c "
import json
d = json.load(open('outputs/run_matrix.json'))
print('Token aggregate:', d['token_usage']['aggregate'])
print('Role counts:',    d['activation_stats']['role_counts'])
print('Strategy counts:',d['activation_stats']['strategy_counts'])
"

bash bash/run_performance.sh          # RQ1; writes outputs/rq1_performance/