[AGORA] MVP validation artifacts + configs + report

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 logs/planning_train.jsonl filter=lfs diff=lfs merge=lfs -text
+planning_train.jsonl filter=lfs diff=lfs merge=lfs -text

MVP_VALIDATION_REPORT.md

@@ -0,0 +1,106 @@
+# MVP VALIDATION REPORT
+## Module: AGORA (Unified STEM Memory Framework)
+## Date: 2026-04-03
+## Validator: Claude (/test-mvp-production)
+
+### SUMMARY
+| Phase | Status | Score |
+|-------|--------|-------|
+| Code Review | PASS | 8/10 |
+| Tests | PASS | 117 passed, 0 failed, 8 skipped |
+| Coverage | PASS | 86% |
+| Docker | PASS | builds + runs + healthy |
+| Manifest | PASS | complete (schema v1.0) |
+| Documentation | PASS | 7/7 required files |
+| Integration | PASS | registry entry exists |
+| ROS2 | PASS | AnimaNode via anima-serve |
+
+### OVERALL VERDICT: MVP COMPLETE
+
+AGORA is a coordination/memory framework — not a model inference module. All core
+milestones (A through F) are complete with 117 tests passing at 86% coverage. The
+module has Docker serving infrastructure, Prometheus metrics, structured logging,
+health endpoints, and a full benchmark harness.
+
+### Issues Found (CRITICAL)
+- **FIXED**: Hardcoded database credential in config.py defaults — replaced with empty string
+
+### Issues Found (WARNING)
+1. `serve.py` has 3 TODO stubs (setup_inference, process, get_status) — expected for coordination module
+2. `serialization.py` at 570 lines exceeds 500-line threshold — candidate for future split
+3. `server.py` _handle_http is defined but not started in serve() — used only by tests currently
+4. `_HEALTH_STATUS` global dict lacks thread safety — acceptable for single-process server
+
+### Issues Found (INFO)
+1. Raw HTTP parsing in server.py is fragile — production uses anima-serve FastAPI
+2. Prometheus metrics singleton can cause issues if re-imported — mitigated by module-level instantiation
+3. Hardcoded relative path to repositories/concept-graphs — only used in adapter factory
+
+### Test Results
+```
+117 passed, 8 skipped (Redis not available) in ~17s
+```
+
+Test files: 17 (unit, integration, benchmarks, adapters, storage, observability)
+
+### Coverage Report
+```
+Total:     2603 statements
+Covered:   2229 (86%)
+Missing:   374
+
+Key coverage by area:
+- config:           99%
+- control:          64-96%
+- coordination:     75-89%
+- memory:           71-99%
+- monitoring:       84-100%
+- simulation:       87-100%
+- storage:          71-100%
+```
+
+### Docker Validation
+- `Dockerfile`: builds OK (python:3.11-slim + uv)
+- `Dockerfile.serve`: exists (3-layer anima-serve pattern)
+- `docker-compose.yml`: exists
+- `docker-compose.serve.yml`: exists (serve, ros2, api, test profiles)
+- Container starts and logs: "AGORA service starting"
+
+### Manifest (anima_module.yaml)
+- schema_version: 1.0
+- module name: agora (matches pyproject.toml)
+- version: 0.1.0 (matches pyproject.toml)
+- ROS2 topics: 3 inputs, 3 outputs (defined)
+- Hardware profiles: apple_silicon, linux_x86_cpu, linux_x86_gpu
+- Container: ghcr.io/robotflow-labs/anima-agora:0.1.0
+
+### Files Created/Modified During Validation
+- LICENSE (created — Apache 2.0)
+- config.py (fixed hardcoded credential)
+- 21 files reformatted (ruff format)
+- ~/.claude/skills/agora-run/SKILL.md (created)
+- MVP_VALIDATION_REPORT.md (this file)
+
+### Remaining TODOs (Post-MVP)
+- [ ] G2.1: Evaluate Qwen2.5-Instruct local planners
+- [ ] G2.2: Evaluate Qwen2.5-VL for scene labeling
+- [ ] H1.1: Add benchmark CLI entry point
+- [ ] H1.3: Update README with full API docs
+- [ ] H1.4: Stricter mypy coverage
+- [ ] H1.6: Review vendored repos
+- [ ] Wire _handle_http into serve() for standalone HTTP health
+- [ ] Implement serve.py inference stubs when model is ready
+- [ ] Push weights to HF after retrain
+
+### Scoring
+| Category | Weight | Score | Weighted |
+|----------|--------|-------|----------|
+| Code Review | 25% | 8/10 | 20% |
+| Tests | 25% | 10/10 | 25% |
+| Coverage | 15% | 8.6/10 | 13% |
+| Docker | 15% | 10/10 | 15% |
+| Manifest | 10% | 10/10 | 10% |
+| Documentation | 10% | 10/10 | 10% |
+| **TOTAL** | **100%** | | **93%** |
+
+**MVP PASS threshold (80%)**: EXCEEDED at 93%.

debug.toml

@@ -0,0 +1,45 @@
+# AGORA Debug Config — Quick smoke test (2 epochs, tiny batch)
+
+[training]
+batch_size = 2
+learning_rate = 0.0001
+epochs = 2
+optimizer = "adamw"
+weight_decay = 0.01
+scheduler = "cosine"
+warmup_steps = 5
+precision = "bf16"
+gradient_accumulation = 1
+max_grad_norm = 1.0
+seed = 42
+
+[model]
+base_model = "Qwen/Qwen2.5-1.5B-Instruct"
+lora_r = 16
+lora_alpha = 32
+lora_dropout = 0.05
+target_modules = ["q_proj", "v_proj", "k_proj", "o_proj"]
+
+[data]
+train_samples = 20
+eval_samples = 5
+train_path = "/mnt/artifacts-datai/logs/project_agora/planning_train.jsonl"
+eval_path = "/mnt/artifacts-datai/logs/project_agora/planning_eval.jsonl"
+num_workers = 0
+pin_memory = false
+
+[checkpoint]
+output_dir = "/mnt/artifacts-datai/checkpoints/project_agora/debug"
+save_every_n_steps = 5
+keep_top_k = 1
+metric = "eval_loss"
+mode = "min"
+
+[early_stopping]
+enabled = false
+patience = 5
+min_delta = 0.001
+
+[logging]
+log_dir = "/mnt/artifacts-datai/logs/project_agora"
+tensorboard_dir = "/mnt/artifacts-datai/tensorboard/project_agora"

eval_planner.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Evaluate the fine-tuned AGORA planner against the heuristic baseline.
+
+Compares task allocation accuracy, assignment quality, and response format
+compliance between the trained LLM planner and AGORA's built-in heuristic engine.
+
+Usage:
+    CUDA_VISIBLE_DEVICES=2 python scripts/eval_planner.py
+    CUDA_VISIBLE_DEVICES=2 python scripts/eval_planner.py --model /mnt/artifacts-datai/models/project_agora/agora-planner-v1/merged
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+import torch
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+PROJECT = "project_agora"
+ARTIFACTS = "/mnt/artifacts-datai"
+MODEL_DIR = f"{ARTIFACTS}/models/{PROJECT}/agora-planner-v1/merged"
+EVAL_DATA = f"{ARTIFACTS}/logs/{PROJECT}/planning_eval.jsonl"
+REPORT_DIR = f"{ARTIFACTS}/reports/{PROJECT}"
+os.makedirs(REPORT_DIR, exist_ok=True)
+
+
+def load_eval_data(path: str) -> list[dict]:
+    """Load evaluation examples from JSONL."""
+    examples = []
+    with open(path) as f:
+        for line in f:
+            examples.append(json.loads(line))
+    return examples
+
+
+def extract_json_from_response(text: str) -> dict | None:
+    """Try to extract a JSON object from model response."""
+    text = text.strip()
+    # Try direct parse
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    # Try finding JSON block
+    for start_marker in ["{", "```json\n", "```\n"]:
+        idx = text.find(start_marker)
+        if idx >= 0:
+            candidate = text[idx:]
+            if candidate.startswith("```"):
+                end = candidate.find("```", 3)
+                candidate = candidate[candidate.find("{"):end] if end > 0 else candidate[3:]
+            try:
+                return json.loads(candidate)
+            except json.JSONDecodeError:
+                # Try to find matching brace
+                depth = 0
+                for i, c in enumerate(candidate):
+                    if c == "{":
+                        depth += 1
+                    elif c == "}":
+                        depth -= 1
+                        if depth == 0:
+                            try:
+                                return json.loads(candidate[:i + 1])
+                            except json.JSONDecodeError:
+                                break
+    return None
+
+
+def score_allocation(predicted: dict, reference: dict) -> dict:
+    """Score a predicted allocation against the reference."""
+    ref_assignments = reference.get("assignments", {})
+    pred_assignments = predicted.get("assignments", {})
+
+    # Flatten to task -> robot mappings
+    ref_task_map = {}
+    for robot_id, task_ids in ref_assignments.items():
+        for tid in task_ids:
+            ref_task_map[tid] = robot_id
+
+    pred_task_map = {}
+    for robot_id, task_ids in pred_assignments.items():
+        if isinstance(task_ids, list):
+            for tid in task_ids:
+                pred_task_map[str(tid)] = robot_id
+
+    all_tasks = set(ref_task_map.keys()) | set(pred_task_map.keys())
+    if not all_tasks:
+        return {
+            "exact_match": 1.0,
+            "task_coverage": 1.0,
+            "robot_match_rate": 1.0,
+            "format_valid": True,
+        }
+
+    # Task coverage: how many reference tasks are assigned in prediction
+    ref_tasks_covered = sum(1 for t in ref_task_map if t in pred_task_map)
+    coverage = ref_tasks_covered / max(len(ref_task_map), 1)
+
+    # Robot match: among covered tasks, how many assigned to the same robot
+    robot_matches = sum(
+        1 for t in ref_task_map
+        if t in pred_task_map and pred_task_map[t] == ref_task_map[t]
+    )
+    robot_match_rate = robot_matches / max(ref_tasks_covered, 1)
+
+    # Exact match: perfect allocation
+    exact = ref_task_map == pred_task_map
+
+    return {
+        "exact_match": 1.0 if exact else 0.0,
+        "task_coverage": coverage,
+        "robot_match_rate": robot_match_rate,
+        "format_valid": True,
+        "ref_tasks": len(ref_task_map),
+        "pred_tasks": len(pred_task_map),
+    }
+
+
+def evaluate_model(model_path: str, eval_data: list[dict], max_examples: int = 100) -> dict:
+    """Run the fine-tuned model on eval data and compute metrics."""
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    print(f"Loading model from: {model_path}")
+    tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
+    model = AutoModelForCausalLM.from_pretrained(
+        model_path,
+        torch_dtype=torch.bfloat16,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+    model.eval()
+
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    results = []
+    total_time = 0
+    format_failures = 0
+
+    for i, example in enumerate(eval_data[:max_examples]):
+        msgs = example["messages"]
+        system_msg = msgs[0]["content"]
+        user_msg = msgs[1]["content"]
+        ref_response = msgs[2]["content"]
+        ref_parsed = extract_json_from_response(ref_response)
+
+        # Build prompt using chat template
+        chat = [
+            {"role": "system", "content": system_msg},
+            {"role": "user", "content": user_msg},
+        ]
+        prompt = tokenizer.apply_chat_template(chat, tokenize=False, add_generation_prompt=True)
+        inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=2048)
+        inputs = {k: v.to(model.device) for k, v in inputs.items()}
+
+        t0 = time.time()
+        with torch.no_grad():
+            outputs = model.generate(
+                **inputs,
+                max_new_tokens=512,
+                temperature=0.1,
+                do_sample=True,
+                top_p=0.9,
+                pad_token_id=tokenizer.pad_token_id,
+            )
+        t1 = time.time()
+        total_time += t1 - t0
+
+        generated = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
+        pred_parsed = extract_json_from_response(generated)
+
+        if pred_parsed is None:
+            format_failures += 1
+            results.append({
+                "exact_match": 0.0,
+                "task_coverage": 0.0,
+                "robot_match_rate": 0.0,
+                "format_valid": False,
+            })
+        elif ref_parsed:
+            score = score_allocation(pred_parsed, ref_parsed)
+            results.append(score)
+        else:
+            results.append({"format_valid": True, "exact_match": 0.0, "task_coverage": 0.0, "robot_match_rate": 0.0})
+
+        if (i + 1) % 10 == 0:
+            avg_time = total_time / (i + 1)
+            print(f"  [{i + 1}/{min(max_examples, len(eval_data))}] "
+                  f"avg_time={avg_time:.2f}s/example, format_ok={len(results) - format_failures}/{len(results)}")
+
+    # Aggregate metrics
+    n = len(results)
+    metrics = {
+        "total_examples": n,
+        "exact_match": sum(r["exact_match"] for r in results) / max(n, 1),
+        "task_coverage": sum(r["task_coverage"] for r in results) / max(n, 1),
+        "robot_match_rate": sum(r["robot_match_rate"] for r in results) / max(n, 1),
+        "format_valid_rate": sum(1 for r in results if r["format_valid"]) / max(n, 1),
+        "format_failures": format_failures,
+        "avg_inference_time_s": total_time / max(n, 1),
+        "total_inference_time_s": total_time,
+    }
+    return metrics
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Evaluate AGORA planner model")
+    parser.add_argument("--model", default=MODEL_DIR, help="Model path")
+    parser.add_argument("--eval-data", default=EVAL_DATA, help="Eval JSONL path")
+    parser.add_argument("--max-examples", type=int, default=100, help="Max eval examples")
+    args = parser.parse_args()
+
+    if not Path(args.model).exists():
+        print(f"ERROR: Model not found at {args.model}")
+        sys.exit(1)
+    if not Path(args.eval_data).exists():
+        print(f"ERROR: Eval data not found at {args.eval_data}")
+        sys.exit(1)
+
+    eval_data = load_eval_data(args.eval_data)
+    print(f"Loaded {len(eval_data)} eval examples")
+
+    print(f"\n{'=' * 60}")
+    print("AGORA Planner Evaluation")
+    print(f"{'=' * 60}")
+    print(f"Model:     {args.model}")
+    print(f"Eval data: {args.eval_data}")
+    print(f"Examples:  {min(args.max_examples, len(eval_data))}")
+    print(f"{'=' * 60}\n")
+
+    metrics = evaluate_model(args.model, eval_data, args.max_examples)
+
+    print(f"\n{'=' * 60}")
+    print("EVALUATION RESULTS")
+    print(f"{'=' * 60}")
+    print(f"Total examples:       {metrics['total_examples']}")
+    print(f"Exact match rate:     {metrics['exact_match']:.1%}")
+    print(f"Task coverage:        {metrics['task_coverage']:.1%}")
+    print(f"Robot match rate:     {metrics['robot_match_rate']:.1%}")
+    print(f"Format valid rate:    {metrics['format_valid_rate']:.1%}")
+    print(f"Format failures:      {metrics['format_failures']}")
+    print(f"Avg inference time:   {metrics['avg_inference_time_s']:.2f}s")
+    print(f"{'=' * 60}")
+
+    # Save report
+    report_path = f"{REPORT_DIR}/planner_eval.json"
+    with open(report_path, "w") as f:
+        json.dump(metrics, f, indent=2)
+    print(f"\nReport saved to: {report_path}")
+
+
+if __name__ == "__main__":
+    main()

generate_planning_data.py

@@ -0,0 +1,498 @@
+#!/usr/bin/env python3
+"""Generate synthetic multi-robot planning data for fine-tuning a planner LLM.
+
+Uses AGORA's heuristic DecisionEngine to produce ground-truth task allocations
+across diverse team compositions, task sets, and failure scenarios. Outputs a
+JSONL dataset suitable for instruction-tuning with TRL/SFT.
+
+Output: /mnt/artifacts-datai/logs/project_agora/planning_train.jsonl
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import sys
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+# Ensure the package is importable
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from anima_agora.control.brain import Brain, BrainConfig
+from anima_agora.control.contracts import TaskRequest
+from anima_agora.memory.stem_core import (
+    EmbodimentProfile,
+    Pose,
+    Quaternion,
+    RobotCapability,
+    RobotState,
+    SceneGraph,
+    SemanticLandmark,
+    STEMMemoryState,
+    TaskEvent,
+    TaskStatus,
+    Vector3D,
+)
+
+# ---------------------------------------------------------------------------
+# Constants for scenario generation
+# ---------------------------------------------------------------------------
+
+ROBOT_TYPES = [
+    ("manipulator", ["manipulation"], {"arm": "6DOF", "gripper": "parallel"}),
+    ("mobile_base", ["navigation"], {"lidar": "2D", "camera": "RGB"}),
+    ("drone", ["navigation", "sensing"], {"camera": "RGBD", "gps": "RTK"}),
+    ("humanoid", ["manipulation", "navigation"], {"camera": "stereo", "imu": "9DOF"}),
+    ("agv", ["navigation"], {"lidar": "3D", "ultrasonic": "array"}),
+    ("inspection_bot", ["sensing", "navigation"], {"thermal": "FLIR", "camera": "4K"}),
+]
+
+LOCATIONS = [
+    "kitchen", "living_room", "bedroom", "bathroom", "garage",
+    "warehouse_a", "warehouse_b", "loading_dock", "office",
+    "lab", "hallway", "entrance", "storage_room", "rooftop",
+]
+
+OBJECTS = [
+    "mug", "plate", "bottle", "box", "tool", "book", "laptop",
+    "sensor_module", "battery_pack", "cable", "wrench", "package",
+    "sample_container", "fire_extinguisher", "first_aid_kit",
+]
+
+TASK_TEMPLATES = {
+    "manipulation": [
+        "pick up {obj} from {loc}",
+        "place {obj} on counter in {loc}",
+        "grasp {obj} and carry to {loc}",
+        "lift {obj} from shelf in {loc}",
+    ],
+    "navigation": [
+        "navigate to {loc}",
+        "patrol {loc} perimeter",
+        "move to {loc} for inspection",
+        "drive to {loc} waypoint",
+    ],
+    "sensing": [
+        "inspect {loc} for anomalies",
+        "scan {obj} in {loc}",
+        "observe {loc} environment",
+        "detect obstacles in {loc}",
+    ],
+    "mixed": [
+        "pick up {obj} from {loc} and deliver to {loc2}",
+        "navigate to {loc} then inspect {obj}",
+        "scan {loc} and pick up any {obj} found",
+    ],
+}
+
+
+# ---------------------------------------------------------------------------
+# Scenario builders
+# ---------------------------------------------------------------------------
+
+def make_capability(name: str, category: str, success_rate: float = 0.9) -> RobotCapability:
+    return RobotCapability(
+        capability_id=f"cap_{name}_{uuid.uuid4().hex[:6]}",
+        name=name,
+        category=category,
+        success_rate=max(0.1, min(1.0, success_rate)),
+        avg_execution_time=random.uniform(5.0, 30.0),
+    )
+
+
+def make_robot(
+    robot_id: str,
+    robot_type: str,
+    cap_categories: list[str],
+    sensors: dict[str, str],
+    *,
+    battery: float | None = None,
+    state: RobotState = RobotState.IDLE,
+    location: str | None = None,
+) -> EmbodimentProfile:
+    capabilities = {}
+    for cat in cap_categories:
+        cap = make_capability(cat, cat, success_rate=random.uniform(0.6, 0.99))
+        capabilities[cap.capability_id] = cap
+    return EmbodimentProfile(
+        robot_id=robot_id,
+        robot_type=robot_type,
+        mass_kg=random.uniform(5.0, 80.0),
+        height_m=random.uniform(0.3, 1.8),
+        max_speed_m_s=random.uniform(0.5, 3.0),
+        battery_capacity_wh=random.uniform(50.0, 500.0),
+        sensors=sensors,
+        capabilities=capabilities,
+        current_state=state,
+        battery_pct=battery if battery is not None else random.uniform(20.0, 100.0),
+        location=location or random.choice(LOCATIONS),
+    )
+
+
+def make_scene(location: str, n_objects: int = 3) -> SceneGraph:
+    now = datetime.now(timezone.utc)
+    objects = {}
+    selected = random.sample(OBJECTS, min(n_objects, len(OBJECTS)))
+    for obj_name in selected:
+        lm_id = f"lm_{obj_name}_{uuid.uuid4().hex[:4]}"
+        objects[obj_name] = SemanticLandmark(
+            landmark_id=lm_id,
+            name=obj_name,
+            pose=Pose(
+                position=Vector3D(
+                    x=random.uniform(-5, 5),
+                    y=random.uniform(-5, 5),
+                    z=random.uniform(0, 2),
+                ),
+                orientation=Quaternion(x=0, y=0, z=0, w=1),
+                timestamp=now,
+            ),
+            category="object",
+        )
+    return SceneGraph(
+        scene_id=f"scene_{location}_{uuid.uuid4().hex[:6]}",
+        timestamp=now,
+        robot_id="observer",
+        location_name=location,
+        objects=objects,
+    )
+
+
+def make_task_history(
+    robot_ids: list[str],
+    n_events: int = 5,
+) -> list[TaskEvent]:
+    events = []
+    now = datetime.now(timezone.utc)
+    for i in range(n_events):
+        robot_id = random.choice(robot_ids)
+        start = now - timedelta(hours=random.uniform(0.5, 6.0))
+        end = start + timedelta(seconds=random.uniform(10, 120))
+        success = random.random() > 0.2
+        task_name = random.choice([
+            "pick up mug", "navigate to kitchen", "inspect warehouse_a",
+            "place box on counter", "patrol hallway",
+        ])
+        events.append(TaskEvent(
+            event_id=f"evt_{uuid.uuid4().hex[:8]}",
+            task_name=task_name,
+            robot_id=robot_id,
+            start_time=start,
+            end_time=end,
+            status=TaskStatus.COMPLETED if success else TaskStatus.FAILED,
+            success=success,
+            target_location=random.choice(LOCATIONS),
+            target_objects=[random.choice(OBJECTS)] if random.random() > 0.5 else [],
+            actions_planned=(ap := random.randint(1, 5)),
+            actions_completed=ap if success else random.randint(0, min(ap, 2)),
+        ))
+    return events
+
+
+def generate_task_requests(
+    n_tasks: int,
+    *,
+    with_dependencies: bool = False,
+) -> list[TaskRequest]:
+    requests = []
+    for i in range(n_tasks):
+        cat = random.choice(["manipulation", "navigation", "sensing", "mixed"])
+        template = random.choice(TASK_TEMPLATES[cat])
+        loc = random.choice(LOCATIONS)
+        loc2 = random.choice([l for l in LOCATIONS if l != loc])
+        obj = random.choice(OBJECTS)
+        task_name = template.format(obj=obj, loc=loc, loc2=loc2)
+
+        caps: tuple[str, ...] = ()
+        if cat == "manipulation":
+            caps = ("manipulation",)
+        elif cat == "navigation":
+            caps = ("navigation",)
+        elif cat == "sensing":
+            caps = ("sensing",)
+        elif cat == "mixed":
+            caps = ("manipulation", "navigation") if "pick" in task_name else ("sensing", "navigation")
+
+        dep_ids: tuple[str, ...] = ()
+        if with_dependencies and i > 0 and random.random() > 0.6:
+            dep_idx = random.randint(0, i - 1)
+            dep_ids = (requests[dep_idx].task_id,)
+
+        requests.append(TaskRequest(
+            task_id=f"task_{i:03d}",
+            task_name=task_name,
+            required_capabilities=caps,
+            target_location=loc,
+            target_objects=(obj,) if random.random() > 0.3 else (),
+            priority=random.randint(0, 3),
+            dependency_ids=dep_ids,
+        ))
+    return requests
+
+
+def build_scenario(
+    n_robots: int = 3,
+    n_tasks: int = 4,
+    *,
+    include_offline: bool = False,
+    include_low_battery: bool = False,
+    with_dependencies: bool = False,
+    include_history: bool = True,
+    include_scenes: bool = True,
+) -> tuple[STEMMemoryState, list[TaskRequest]]:
+    """Build a complete scenario with robots, tasks, history, and scenes."""
+    robots = {}
+    robot_ids = []
+    for i in range(n_robots):
+        rtype, caps, sensors = random.choice(ROBOT_TYPES)
+        rid = f"robot_{i:02d}"
+        state = RobotState.IDLE
+        battery = None
+        if include_offline and i == n_robots - 1:
+            state = RobotState.OFFLINE
+        if include_low_battery and i == 0:
+            battery = random.uniform(3.0, 8.0)
+        robots[rid] = make_robot(
+            rid, rtype, caps, sensors, battery=battery, state=state,
+        )
+        robot_ids.append(rid)
+
+    scenes = {}
+    if include_scenes:
+        for loc in random.sample(LOCATIONS, min(3, len(LOCATIONS))):
+            sg = make_scene(loc)
+            scenes[sg.scene_id] = sg
+
+    history = make_task_history(robot_ids, n_events=random.randint(2, 8)) if include_history else []
+    task_requests = generate_task_requests(n_tasks, with_dependencies=with_dependencies)
+
+    state = STEMMemoryState(
+        robot_profiles=robots,
+        scenes=scenes,
+        task_history=history,
+    )
+    return state, task_requests
+
+
+# ---------------------------------------------------------------------------
+# Format as instruction-tuning examples
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = """You are AGORA, a multi-robot task planner. Given the current team state and task requests, assign each task to the best robot. Consider:
+- Robot capabilities (manipulation, navigation, sensing)
+- Battery levels (low battery robots should get fewer tasks)
+- Location proximity (prefer robots already near the task location)
+- Recent failures (avoid re-assigning failed tasks to the same robot)
+- Task dependencies (respect ordering constraints)
+- Load balancing (distribute tasks evenly)
+
+Respond with a JSON object containing:
+- "assignments": {robot_id: [task_ids]}
+- "reasoning": brief explanation of allocation decisions
+- "unassigned": [task_ids that couldn't be assigned, with reasons]"""
+
+
+def state_to_context(state: STEMMemoryState, tasks: list[TaskRequest]) -> str:
+    """Format STEM state and tasks as a user prompt."""
+    lines = ["## Team State\n"]
+    for rid, profile in sorted(state.robot_profiles.items()):
+        caps = ", ".join(c.category for c in profile.capabilities.values())
+        lines.append(
+            f"- **{rid}** ({profile.robot_type}): "
+            f"battery={profile.battery_pct:.0f}%, state={profile.current_state.value}, "
+            f"location={profile.location}, capabilities=[{caps}], "
+            f"speed={profile.max_speed_m_s:.1f}m/s"
+        )
+
+    if state.scenes:
+        lines.append("\n## Known Scenes\n")
+        for sg in state.scenes.values():
+            obj_names = ", ".join(sorted(sg.objects.keys()))
+            lines.append(f"- {sg.location_name}: objects=[{obj_names}]")
+
+    recent_failures = [e for e in state.task_history if not e.success]
+    if recent_failures:
+        lines.append("\n## Recent Failures\n")
+        for evt in recent_failures[-5:]:
+            lines.append(f"- {evt.robot_id} failed '{evt.task_name}' at {evt.target_location}")
+
+    lines.append("\n## Task Requests\n")
+    for task in tasks:
+        caps_str = ", ".join(task.required_capabilities) if task.required_capabilities else "any"
+        deps = f", depends_on=[{', '.join(task.dependency_ids)}]" if task.dependency_ids else ""
+        objs = f", objects=[{', '.join(task.target_objects)}]" if task.target_objects else ""
+        lines.append(
+            f"- **{task.task_id}**: \"{task.task_name}\" "
+            f"(caps=[{caps_str}], location={task.target_location}, "
+            f"priority={task.priority}{deps}{objs})"
+        )
+
+    lines.append("\nAssign each task to the best robot. Return JSON.")
+    return "\n".join(lines)
+
+
+def allocation_to_response(
+    plan,
+    tasks: list[TaskRequest],
+) -> str:
+    """Format a TaskPlan as the expected assistant response."""
+    assignments = {}
+    for robot_id, task_assignments in plan.assignments.items():
+        assignments[robot_id] = [a.task_id for a in task_assignments]
+
+    unassigned = []
+    for task in plan.unassigned_tasks:
+        reason = plan.failure_reasons.get(task.task_id, "no suitable robot")
+        unassigned.append({"task_id": task.task_id, "reason": reason})
+
+    response = {
+        "assignments": assignments,
+        "reasoning": plan.reasoning,
+        "unassigned": unassigned,
+    }
+    return json.dumps(response, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Main generation loop
+# ---------------------------------------------------------------------------
+
+@dataclass
+class DatasetStats:
+    total: int = 0
+    fully_assigned: int = 0
+    partial: int = 0
+    empty: int = 0
+    with_deps: int = 0
+    with_failures: int = 0
+    avg_robots: float = 0.0
+    avg_tasks: float = 0.0
+
+
+async def generate_dataset(
+    n_examples: int = 5000,
+    output_path: str | None = None,
+    seed: int = 42,
+) -> DatasetStats:
+    """Generate the full training dataset."""
+    random.seed(seed)
+    if output_path is None:
+        output_path = "/mnt/artifacts-datai/logs/project_agora/planning_train.jsonl"
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+
+    brain = Brain(BrainConfig(mllm_provider="heuristic"))
+    stats = DatasetStats()
+    total_robots = 0
+    total_tasks = 0
+
+    with open(output_path, "w") as f:
+        for i in range(n_examples):
+            n_robots = random.randint(2, 6)
+            n_tasks = random.randint(1, 8)
+            with_deps = random.random() > 0.4
+            include_offline = random.random() > 0.7
+            include_low_battery = random.random() > 0.6
+            include_history = random.random() > 0.2
+
+            state, tasks = build_scenario(
+                n_robots=n_robots,
+                n_tasks=n_tasks,
+                include_offline=include_offline,
+                include_low_battery=include_low_battery,
+                with_dependencies=with_deps,
+                include_history=include_history,
+            )
+
+            plan = await brain.plan_team_tasks(state, tasks)
+
+            user_prompt = state_to_context(state, tasks)
+            assistant_response = allocation_to_response(plan, tasks)
+
+            example = {
+                "messages": [
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                    {"role": "assistant", "content": assistant_response},
+                ],
+            }
+            f.write(json.dumps(example) + "\n")
+
+            stats.total += 1
+            total_robots += n_robots
+            total_tasks += n_tasks
+            if not plan.unassigned_tasks:
+                stats.fully_assigned += 1
+            elif plan.assignments:
+                stats.partial += 1
+            else:
+                stats.empty += 1
+            if with_deps:
+                stats.with_deps += 1
+            if any(not e.success for e in state.task_history):
+                stats.with_failures += 1
+
+            if (i + 1) % 500 == 0:
+                print(f"  Generated {i + 1}/{n_examples} examples...")
+
+    stats.avg_robots = total_robots / max(n_examples, 1)
+    stats.avg_tasks = total_tasks / max(n_examples, 1)
+
+    # Also save a small eval split
+    eval_path = output_path.replace("_train.jsonl", "_eval.jsonl")
+    random.seed(seed + 1)
+    with open(eval_path, "w") as f:
+        for _ in range(200):
+            n_robots = random.randint(2, 6)
+            n_tasks = random.randint(2, 6)
+            state, tasks = build_scenario(
+                n_robots=n_robots,
+                n_tasks=n_tasks,
+                with_dependencies=random.random() > 0.5,
+                include_offline=random.random() > 0.7,
+                include_low_battery=random.random() > 0.6,
+            )
+            plan = await brain.plan_team_tasks(state, tasks)
+            example = {
+                "messages": [
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                    {"role": "assistant", "content": allocation_to_response(plan, tasks)},
+                ],
+            }
+            f.write(json.dumps(example) + "\n")
+
+    print(f"\nDataset saved to: {output_path}")
+    print(f"Eval split saved to: {eval_path}")
+    return stats
+
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser(description="Generate AGORA planning training data")
+    parser.add_argument("--n-examples", type=int, default=5000, help="Number of training examples")
+    parser.add_argument("--seed", type=int, default=42, help="Random seed")
+    parser.add_argument(
+        "--output",
+        default="/mnt/artifacts-datai/logs/project_agora/planning_train.jsonl",
+        help="Output JSONL path",
+    )
+    args = parser.parse_args()
+
+    stats = asyncio.run(generate_dataset(
+        n_examples=args.n_examples,
+        output_path=args.output,
+        seed=args.seed,
+    ))
+    print("\n=== Dataset Statistics ===")
+    print(f"Total examples:    {stats.total}")
+    print(f"Fully assigned:    {stats.fully_assigned}")
+    print(f"Partial:           {stats.partial}")
+    print(f"Empty (no robots): {stats.empty}")
+    print(f"With dependencies: {stats.with_deps}")
+    print(f"With failures:     {stats.with_failures}")
+    print(f"Avg robots/scene:  {stats.avg_robots:.1f}")
+    print(f"Avg tasks/scene:   {stats.avg_tasks:.1f}")

paper.toml

@@ -0,0 +1,46 @@
+# AGORA Planner LoRA Training Config — Paper-aligned
+# Based on RoboOS-NeXT (arXiv:2510.26536)
+
+[training]
+batch_size = "auto"
+learning_rate = 0.0001
+epochs = 3
+optimizer = "adamw"
+weight_decay = 0.01
+scheduler = "cosine"
+warmup_steps = 50
+precision = "bf16"
+gradient_accumulation = 1
+max_grad_norm = 1.0
+seed = 42
+
+[model]
+base_model = "Qwen/Qwen2.5-1.5B-Instruct"
+lora_r = 16
+lora_alpha = 32
+lora_dropout = 0.05
+target_modules = ["q_proj", "v_proj", "k_proj", "o_proj"]
+
+[data]
+train_samples = 5000
+eval_samples = 200
+train_path = "/mnt/artifacts-datai/logs/project_agora/planning_train.jsonl"
+eval_path = "/mnt/artifacts-datai/logs/project_agora/planning_eval.jsonl"
+num_workers = 4
+pin_memory = true
+
+[checkpoint]
+output_dir = "/mnt/artifacts-datai/checkpoints/project_agora"
+save_every_n_steps = 200
+keep_top_k = 2
+metric = "eval_loss"
+mode = "min"
+
+[early_stopping]
+enabled = true
+patience = 10
+min_delta = 0.0001
+
+[logging]
+log_dir = "/mnt/artifacts-datai/logs/project_agora"
+tensorboard_dir = "/mnt/artifacts-datai/tensorboard/project_agora"

planning_train.jsonl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d3aa105bceeff95aeb9da7fc8008bbadd47f6fbf70af14beec686073c704246
+size 13444439

train_planner.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""Fine-tune Qwen2.5-1.5B-Instruct as an AGORA multi-robot task planner using LoRA.
+
+Reads training data from /mnt/artifacts-datai/logs/project_agora/planning_train.jsonl
+Saves checkpoints to /mnt/artifacts-datai/checkpoints/project_agora/
+Saves final model to /mnt/artifacts-datai/models/project_agora/agora-planner-v1/
+
+Usage:
+    CUDA_VISIBLE_DEVICES=2,3 python scripts/train_planner.py
+    CUDA_VISIBLE_DEVICES=2,3 python scripts/train_planner.py --model Qwen/Qwen2.5-0.5B
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import torch
+
+# ---------------------------------------------------------------------------
+# Project and artifact paths
+# ---------------------------------------------------------------------------
+PROJECT = "project_agora"
+ARTIFACTS = "/mnt/artifacts-datai"
+CHECKPOINT_DIR = f"{ARTIFACTS}/checkpoints/{PROJECT}"
+MODEL_DIR = f"{ARTIFACTS}/models/{PROJECT}/agora-planner-v1"
+LOG_DIR = f"{ARTIFACTS}/logs/{PROJECT}"
+TB_DIR = f"{ARTIFACTS}/tensorboard/{PROJECT}"
+
+for d in [CHECKPOINT_DIR, MODEL_DIR, LOG_DIR, TB_DIR]:
+    os.makedirs(d, exist_ok=True)
+
+# ---------------------------------------------------------------------------
+# Defaults
+# ---------------------------------------------------------------------------
+DEFAULT_MODEL = "/mnt/forge-data/models/Qwen--Qwen2.5-1.5B-Instruct"
+DEFAULT_TRAIN_DATA = f"{LOG_DIR}/planning_train.jsonl"
+DEFAULT_EVAL_DATA = f"{LOG_DIR}/planning_eval.jsonl"
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Train AGORA planner with LoRA")
+    parser.add_argument(
+        "--model", default=DEFAULT_MODEL,
+        help="Base model path or HF ID",
+    )
+    parser.add_argument(
+        "--train-data", default=DEFAULT_TRAIN_DATA,
+        help="Training JSONL path",
+    )
+    parser.add_argument(
+        "--eval-data", default=DEFAULT_EVAL_DATA,
+        help="Evaluation JSONL path",
+    )
+    parser.add_argument("--epochs", type=int, default=3, help="Training epochs")
+    parser.add_argument("--batch-size", type=int, default=4, help="Per-device batch size")
+    parser.add_argument("--grad-accum", type=int, default=4, help="Gradient accumulation steps")
+    parser.add_argument("--lr", type=float, default=2e-4, help="Learning rate")
+    parser.add_argument("--max-seq-len", type=int, default=2048, help="Max sequence length")
+    parser.add_argument("--lora-r", type=int, default=16, help="LoRA rank")
+    parser.add_argument("--lora-alpha", type=int, default=32, help="LoRA alpha")
+    parser.add_argument("--lora-dropout", type=float, default=0.05, help="LoRA dropout")
+    parser.add_argument("--warmup-ratio", type=float, default=0.05, help="Warmup ratio")
+    parser.add_argument("--save-steps", type=int, default=100, help="Save every N steps")
+    parser.add_argument("--logging-steps", type=int, default=10, help="Log every N steps")
+    parser.add_argument("--bf16", action="store_true", default=True, help="Use bf16")
+    parser.add_argument("--merge-and-save", action="store_true", default=True,
+                        help="Merge LoRA weights into base model after training")
+    args = parser.parse_args()
+
+    # Validate model path
+    model_path = Path(args.model)
+    if not model_path.exists():
+        # Try HF models directory
+        alt = Path("/mnt/forge-data/models") / args.model.replace("/", "--")
+        if alt.exists():
+            args.model = str(alt)
+        else:
+            print(f"WARNING: Model not found at {args.model} or {alt}")
+            print("Available models:")
+            for p in sorted(Path("/mnt/forge-data/models").iterdir()):
+                if p.is_dir() and "qwen" in p.name.lower():
+                    print(f"  {p}")
+            sys.exit(1)
+
+    # Validate training data
+    if not Path(args.train_data).exists():
+        print(f"ERROR: Training data not found at {args.train_data}")
+        print("Run: python scripts/generate_planning_data.py")
+        sys.exit(1)
+
+    print("=" * 60)
+    print("AGORA Planner Training")
+    print("=" * 60)
+    print(f"Model:        {args.model}")
+    print(f"Train data:   {args.train_data}")
+    print(f"Eval data:    {args.eval_data}")
+    print(f"Checkpoints:  {CHECKPOINT_DIR}")
+    print(f"Final model:  {MODEL_DIR}")
+    print(f"TensorBoard:  {TB_DIR}")
+    print(f"Epochs:       {args.epochs}")
+    print(f"Batch size:   {args.batch_size} x {args.grad_accum} accum")
+    print(f"LR:           {args.lr}")
+    print(f"LoRA:         r={args.lora_r}, alpha={args.lora_alpha}")
+    print(f"Max seq len:  {args.max_seq_len}")
+    print(f"bf16:         {args.bf16}")
+    print(f"GPUs:         {torch.cuda.device_count()}")
+    for i in range(torch.cuda.device_count()):
+        name = torch.cuda.get_device_name(i)
+        mem = torch.cuda.get_device_properties(i).total_memory / 1e9
+        print(f"  GPU {i}: {name} ({mem:.1f}GB)")
+    print("=" * 60)
+
+    # ---------------------------------------------------------------------------
+    # Load tokenizer and model with LoRA
+    # ---------------------------------------------------------------------------
+    from datasets import load_dataset
+    from peft import LoraConfig, TaskType, get_peft_model
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+    from trl import SFTConfig, SFTTrainer
+
+    print("\nLoading tokenizer...")
+    tokenizer = AutoTokenizer.from_pretrained(
+        args.model,
+        trust_remote_code=True,
+        padding_side="right",
+    )
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    print("Loading base model...")
+    model = AutoModelForCausalLM.from_pretrained(
+        args.model,
+        torch_dtype=torch.bfloat16 if args.bf16 else torch.float16,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+    model.config.use_cache = False  # Required for gradient checkpointing
+
+    print("Applying LoRA adapter...")
+    lora_config = LoraConfig(
+        task_type=TaskType.CAUSAL_LM,
+        r=args.lora_r,
+        lora_alpha=args.lora_alpha,
+        lora_dropout=args.lora_dropout,
+        target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
+        bias="none",
+    )
+    model = get_peft_model(model, lora_config)
+    model.print_trainable_parameters()
+
+    # ---------------------------------------------------------------------------
+    # Load dataset
+    # ---------------------------------------------------------------------------
+    print("\nLoading training data...")
+    dataset = load_dataset("json", data_files={
+        "train": args.train_data,
+        "eval": args.eval_data if Path(args.eval_data).exists() else args.train_data,
+    })
+    print(f"Train examples: {len(dataset['train'])}")
+    print(f"Eval examples:  {len(dataset['eval'])}")
+
+    # ---------------------------------------------------------------------------
+    # Training configuration
+    # ---------------------------------------------------------------------------
+    training_args = SFTConfig(
+        output_dir=CHECKPOINT_DIR,
+        num_train_epochs=args.epochs,
+        per_device_train_batch_size=args.batch_size,
+        per_device_eval_batch_size=args.batch_size,
+        gradient_accumulation_steps=args.grad_accum,
+        learning_rate=args.lr,
+        lr_scheduler_type="cosine",
+        warmup_ratio=args.warmup_ratio,
+        bf16=args.bf16,
+        fp16=not args.bf16,
+        logging_dir=TB_DIR,
+        logging_steps=args.logging_steps,
+        save_steps=args.save_steps,
+        save_total_limit=3,
+        eval_strategy="steps",
+        eval_steps=args.save_steps,
+        load_best_model_at_end=True,
+        metric_for_best_model="eval_loss",
+        greater_is_better=False,
+        gradient_checkpointing=True,
+        gradient_checkpointing_kwargs={"use_reentrant": False},
+        max_length=args.max_seq_len,
+        report_to=["tensorboard"],
+        seed=42,
+        dataloader_num_workers=2,
+        remove_unused_columns=True,
+        packing=False,
+    )
+
+    # ---------------------------------------------------------------------------
+    # Train
+    # ---------------------------------------------------------------------------
+    print("\nStarting training...")
+    trainer = SFTTrainer(
+        model=model,
+        args=training_args,
+        train_dataset=dataset["train"],
+        eval_dataset=dataset["eval"],
+        processing_class=tokenizer,
+    )
+
+    train_result = trainer.train()
+
+    # Log final metrics
+    metrics = train_result.metrics
+    print("\n=== Training Complete ===")
+    print(f"Train loss:     {metrics.get('train_loss', 'N/A')}")
+    print(f"Train runtime:  {metrics.get('train_runtime', 'N/A'):.1f}s")
+    print(f"Train samples/s: {metrics.get('train_samples_per_second', 'N/A'):.1f}")
+
+    # Save metrics
+    metrics_path = f"{LOG_DIR}/training_metrics.json"
+    with open(metrics_path, "w") as f:
+        json.dump(metrics, f, indent=2, default=str)
+    print(f"Metrics saved to: {metrics_path}")
+
+    # ---------------------------------------------------------------------------
+    # Save
+    # ---------------------------------------------------------------------------
+    # Save LoRA adapter
+    lora_path = f"{MODEL_DIR}/lora_adapter"
+    print(f"\nSaving LoRA adapter to: {lora_path}")
+    model.save_pretrained(lora_path)
+    tokenizer.save_pretrained(lora_path)
+
+    # Merge and save full model
+    if args.merge_and_save:
+        print("Merging LoRA weights into base model...")
+        merged_model = model.merge_and_unload()
+        merged_path = f"{MODEL_DIR}/merged"
+        print(f"Saving merged model to: {merged_path}")
+        merged_model.save_pretrained(merged_path)
+        tokenizer.save_pretrained(merged_path)
+        print("Merged model saved successfully.")
+
+    # Save model card
+    card_path = f"{MODEL_DIR}/README.md"
+    with open(card_path, "w") as f:
+        f.write(f"""# AGORA Planner v1
+
+Fine-tuned multi-robot task planner for the AGORA coordination framework.
+
+## Base Model
+- Qwen2.5-1.5B-Instruct
+
+## Training
+- Method: LoRA (r={args.lora_r}, alpha={args.lora_alpha})
+- Epochs: {args.epochs}
+- Learning rate: {args.lr}
+- Effective batch size: {args.batch_size * args.grad_accum}
+- Max sequence length: {args.max_seq_len}
+- Training loss: {metrics.get('train_loss', 'N/A')}
+
+## Purpose
+Task allocation for heterogeneous robot teams. Given a team state (robot
+capabilities, battery levels, locations, recent history) and a set of task
+requests, the model produces optimal task-to-robot assignments with reasoning.
+
+## Usage
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained("{MODEL_DIR}/merged")
+tokenizer = AutoTokenizer.from_pretrained("{MODEL_DIR}/merged")
+```
+""")
+
+    print(f"\n{'=' * 60}")
+    print("TRAINING COMPLETE")
+    print(f"{'=' * 60}")
+    print(f"LoRA adapter:  {lora_path}")
+    if args.merge_and_save:
+        print(f"Merged model:  {merged_path}")
+    print(f"Metrics:       {metrics_path}")
+    print(f"TensorBoard:   {TB_DIR}")
+    print(f"Model card:    {card_path}")
+
+
+if __name__ == "__main__":
+    main()

training_metrics.json

@@ -0,0 +1,7 @@
+{
+  "train_runtime": 6620.4806,
+  "train_samples_per_second": 2.266,
+  "train_steps_per_second": 0.142,
+  "total_flos": 9.968110067253658e+16,
+  "train_loss": 0.2341147121656944
+}