agent-curriculum 0.1.0__tar.gz

agent_curriculum-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+  packages: write
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-curriculum
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_curriculum-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+*.so
+.env

agent_curriculum-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FableForge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_curriculum-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: agent-curriculum
+Version: 0.1.0
+Summary: Curriculum learning for agent training — difficulty-scored stages
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# AgentCurriculum
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![Tests](https://img.shields.io/badge/tests-0-yellow.svg)](tests/)
+
+
+Curriculum learning for coding agents — train through progressive difficulty stages.
+
+## Overview
+
+AgentCurriculum ranks agent traces by difficulty and builds a 5-stage training curriculum where the model learns basic tool use first, then progressively harder multi-step reasoning and error recovery.
+
+## Stages
+
+| Stage | Name | Difficulty | Tools | Errors | LR | LoRA r |
+|-------|------|-----------|-------|--------|----|--------|
+| 1 | Basic | 0.0–0.2 | <5 | 0 | 2e-4 | 64 |
+| 2 | Intermediate | 0.2–0.4 | <15 | ≤2 | 1e-4 | 64 |
+| 3 | Advanced | 0.4–0.6 | <30 | ≤5 | 5e-5 | 32 |
+| 4 | Expert | 0.6–0.8 | <60 | ≤10 | 3e-5 | 32 |
+| 5 | Master | 0.8–1.0 | <100 | ≤20 | 1e-5 | 16 |
+
+## Installation
+
+```bash
+pip install agent-curriculum
+```
+
+## Quick Start
+
+```python
+from agent_curriculum import DifficultyScorer, StageBuilder, CurriculumTrainer
+
+# Score traces by difficulty
+scorer = DifficultyScorer()
+scores = scorer.score_file("traces.jsonl")
+
+# Build curriculum stages
+builder = StageBuilder(scorer=scorer)
+stages = builder.build_stages("traces.jsonl")
+builder.generate_configs("configs/")
+
+# Train through the curriculum
+trainer = CurriculumTrainer(base_model="Qwen/Qwen2.5-14B")
+results = trainer.train_curriculum("traces.jsonl", start_stage=1, end_stage=5)
+```
+
+## License
+
+MIT
+
+## Ecosystem
+
+Part of the [FableForge](../) ecosystem — 21 open-source projects built from 210K real agent traces:
+
+| Project | Description |
+| --- | --- |
+| **[Anvil](../anvil)** | Self-verified coding agent |
+| **[VerifyLoop](../verifyloop)** | Plan→Execute→Verify→Recover framework |
+| **[ErrorRecovery](../error-recovery)** | Self-healing middleware (3,725 error patterns) |
+| **[FableForge-14B](../fableforge-14b)** | The fine-tuned 14B model (4-stage training) |
+| **[ShellWhisperer](../shell-whisperer)** | 1.5B edge agent (phone/RPi, 50ms) |
+| **[ReasonCritic](../reason-critic)** | Verification model (130 benchmark tasks) |
+| **[TraceCompiler](../trace-compiler)** | Compile traces → LoRA skills |
+| **[AgentRuntime](../agent-runtime)** | Persistent agent daemon (systemd for AI) |
+| **[AgentSwarm](../agent-swarm)** | Multi-agent from real trace transitions |
+| **[AgentTelemetry](../agent-telemetry)** | Datadog for agents (token tracking, costs) |
+| **[BenchAgent](../bench-agent)** | HumanEval for tool-use (107 tasks) |
+| **[AgentDev](../agent-dev)** | VSCode extension with verification |
+| **[TraceViz](../trace-viz)** | Trace replay visualizer (Next.js) |
+| **[AgentSkills](../agent-skills)** | npm for agent behaviors |
+| **[AgentCurriculum](../agent-curriculum)** | 5-stage progressive training |
+| **[AgentFuzzer](../agent-fuzzer)** | Adversarial testing for agents |
+| **[AgentConstitution](../agent-constitution)** | Safety guardrails from traces |
+| **[CostOptimizer](../cost-optimizer)** | Token cost reduction (50-80%) |
+| **[AgentProfiler](../agent-profiler)** | Behavioral fingerprinting |
+| **[TrajectoryDistiller](../trajectory-distiller)** | Trace→training data pipeline |
+| **[Fable5-Dataset](../fable5-dataset)** | HuggingFace dataset release |

agent_curriculum-0.1.0/README.md

@@ -0,0 +1,77 @@
+# AgentCurriculum
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![Tests](https://img.shields.io/badge/tests-0-yellow.svg)](tests/)
+
+
+Curriculum learning for coding agents — train through progressive difficulty stages.
+
+## Overview
+
+AgentCurriculum ranks agent traces by difficulty and builds a 5-stage training curriculum where the model learns basic tool use first, then progressively harder multi-step reasoning and error recovery.
+
+## Stages
+
+| Stage | Name | Difficulty | Tools | Errors | LR | LoRA r |
+|-------|------|-----------|-------|--------|----|--------|
+| 1 | Basic | 0.0–0.2 | <5 | 0 | 2e-4 | 64 |
+| 2 | Intermediate | 0.2–0.4 | <15 | ≤2 | 1e-4 | 64 |
+| 3 | Advanced | 0.4–0.6 | <30 | ≤5 | 5e-5 | 32 |
+| 4 | Expert | 0.6–0.8 | <60 | ≤10 | 3e-5 | 32 |
+| 5 | Master | 0.8–1.0 | <100 | ≤20 | 1e-5 | 16 |
+
+## Installation
+
+```bash
+pip install agent-curriculum
+```
+
+## Quick Start
+
+```python
+from agent_curriculum import DifficultyScorer, StageBuilder, CurriculumTrainer
+
+# Score traces by difficulty
+scorer = DifficultyScorer()
+scores = scorer.score_file("traces.jsonl")
+
+# Build curriculum stages
+builder = StageBuilder(scorer=scorer)
+stages = builder.build_stages("traces.jsonl")
+builder.generate_configs("configs/")
+
+# Train through the curriculum
+trainer = CurriculumTrainer(base_model="Qwen/Qwen2.5-14B")
+results = trainer.train_curriculum("traces.jsonl", start_stage=1, end_stage=5)
+```
+
+## License
+
+MIT
+
+## Ecosystem
+
+Part of the [FableForge](../) ecosystem — 21 open-source projects built from 210K real agent traces:
+
+| Project | Description |
+| --- | --- |
+| **[Anvil](../anvil)** | Self-verified coding agent |
+| **[VerifyLoop](../verifyloop)** | Plan→Execute→Verify→Recover framework |
+| **[ErrorRecovery](../error-recovery)** | Self-healing middleware (3,725 error patterns) |
+| **[FableForge-14B](../fableforge-14b)** | The fine-tuned 14B model (4-stage training) |
+| **[ShellWhisperer](../shell-whisperer)** | 1.5B edge agent (phone/RPi, 50ms) |
+| **[ReasonCritic](../reason-critic)** | Verification model (130 benchmark tasks) |
+| **[TraceCompiler](../trace-compiler)** | Compile traces → LoRA skills |
+| **[AgentRuntime](../agent-runtime)** | Persistent agent daemon (systemd for AI) |
+| **[AgentSwarm](../agent-swarm)** | Multi-agent from real trace transitions |
+| **[AgentTelemetry](../agent-telemetry)** | Datadog for agents (token tracking, costs) |
+| **[BenchAgent](../bench-agent)** | HumanEval for tool-use (107 tasks) |
+| **[AgentDev](../agent-dev)** | VSCode extension with verification |
+| **[TraceViz](../trace-viz)** | Trace replay visualizer (Next.js) |
+| **[AgentSkills](../agent-skills)** | npm for agent behaviors |
+| **[AgentCurriculum](../agent-curriculum)** | 5-stage progressive training |
+| **[AgentFuzzer](../agent-fuzzer)** | Adversarial testing for agents |
+| **[AgentConstitution](../agent-constitution)** | Safety guardrails from traces |
+| **[CostOptimizer](../cost-optimizer)** | Token cost reduction (50-80%) |
+| **[AgentProfiler](../agent-profiler)** | Behavioral fingerprinting |
+| **[TrajectoryDistiller](../trajectory-distiller)** | Trace→training data pipeline |
+| **[Fable5-Dataset](../fable5-dataset)** | HuggingFace dataset release |

agent_curriculum-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-curriculum"
+version = "0.1.0"
+description = "Curriculum learning for agent training — difficulty-scored stages"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["pydantic>=2.0", "pyyaml>=6.0", "numpy>=1.24", "click>=8.0", "rich>=13.0"]
+
+[project.scripts]
+acurriculum = "agent_curriculum.cli:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_curriculum"]

agent_curriculum-0.1.0/src/agent_curriculum/__init__.py

@@ -0,0 +1,3 @@
+"""AgentCurriculum — Curriculum learning for agent training with difficulty-scored stages."""
+
+__version__ = "0.1.0"

agent_curriculum-0.1.0/src/agent_curriculum/cli.py

@@ -0,0 +1,119 @@
+"""CLI for AgentCurriculum — curriculum learning with difficulty-scored stages."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from agent_curriculum.difficulty_scorer import DifficultyScorer
+from agent_curriculum.stage_builder import StageBuilder
+from agent_curriculum.scheduler import DEFAULT_SCHEDULE
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def cli():
+    """AgentCurriculum — Curriculum learning for agent training with difficulty-scored stages."""
+    pass
+
+
+@cli.command()
+@click.argument("trace_file", type=click.Path(exists=True))
+@click.option("--output", "-o", type=click.Path(), help="Output JSONL file for scores")
+def score(trace_file, output):
+    """Score traces by difficulty level."""
+    scorer = DifficultyScorer()
+    scores = scorer.score_file(trace_file)
+
+    table = Table(title="Difficulty Scores")
+    table.add_column("Trace ID", style="cyan")
+    table.add_column("Difficulty", style="bold")
+    table.add_column("Level", style="magenta")
+    table.add_column("Tools", justify="right")
+    table.add_column("Errors", justify="right")
+
+    for s in scores:
+        level_color = {"basic": "green", "intermediate": "yellow", "advanced": "orange3", "expert": "red", "master": "bold red"}.get(s.difficulty_level, "white")
+        table.add_row(
+            s.trace_id,
+            f"{s.overall_difficulty:.3f}",
+            f"[{level_color}]{s.difficulty_level}[/{level_color}]",
+            str(s.tool_count),
+            str(s.error_count),
+        )
+
+    console.print(table)
+
+    if output:
+        out_data = [s.to_dict() for s in scores]
+        Path(output).write_text("\n".join(json.dumps(d) for d in out_data))
+        console.print(f"[green]Scores saved to {output}[/green]")
+
+
+@cli.command()
+@click.argument("trace_file", type=click.Path(exists=True))
+@click.option("--stages", "-s", default=5, type=int, help="Number of curriculum stages")
+@click.option("--output", "-o", type=click.Path(), help="Output directory for stage files")
+def build(trace_file, stages, output):
+    """Build curriculum stages from a trace file."""
+    stager = StageBuilder(num_stages=stages)
+    result = stager.build_from_file(trace_file)
+
+    table = Table(title=f"Curriculum Stages ({len(result)} stages)")
+    table.add_column("Stage", style="cyan")
+    table.add_column("Name", style="bold")
+    table.add_column("Difficulty", style="magenta")
+    table.add_column("Traces", justify="right")
+
+    for stage in result:
+        table.add_row(
+            str(stage.stage_id),
+            stage.name,
+            f"[{stage.difficulty_range[0]:.1f} - {stage.difficulty_range[1]:.1f}]",
+            str(len(stage.traces)),
+        )
+
+    console.print(table)
+
+    if output:
+        out_path = Path(output)
+        out_path.mkdir(parents=True, exist_ok=True)
+        for stage in result:
+            stage_file = out_path / f"stage_{stage.stage_id}_{stage.name}.json"
+            stage_file.write_text(json.dumps(stage.to_dict(), indent=2))
+        console.print(f"[green]Stages saved to {output}[/green]")
+
+
+@cli.command()
+def schedule():
+    """Show the default learning rate / batch size schedule."""
+    table = Table(title="Default Curriculum Schedule")
+    table.add_column("Stage", style="cyan")
+    table.add_column("LR", style="green")
+    table.add_column("Batch", justify="right")
+    table.add_column("LoRA r", justify="right")
+    table.add_column("LoRA alpha", justify="right")
+    table.add_column("Epochs", justify="right")
+
+    for s in DEFAULT_SCHEDULE:
+        table.add_row(
+            str(s.stage_id),
+            f"{s.learning_rate:.1e}",
+            str(s.batch_size),
+            str(s.lora_r),
+            str(s.lora_alpha),
+            str(s.num_epochs),
+        )
+
+    console.print(table)
+
+
+if __name__ == "__main__":
+    cli()

agent_curriculum-0.1.0/src/agent_curriculum/configs/stage1.yaml

@@ -0,0 +1,9 @@
+stage_id: 1
+name: basic
+description: "Basic tool use — simple read/edit/bash tasks with no errors"
+difficulty_range: [0.0, 0.2]
+num_traces: 0
+learning_rate: 0.0002
+batch_size: 8
+num_epochs: 3
+lora_r: 64

agent_curriculum-0.1.0/src/agent_curriculum/configs/stage2.yaml

@@ -0,0 +1,9 @@
+stage_id: 2
+name: intermediate
+description: "Intermediate tasks — multi-tool sequences with simple error recovery"
+difficulty_range: [0.2, 0.4]
+num_traces: 0
+learning_rate: 0.0001
+batch_size: 4
+num_epochs: 2
+lora_r: 64

agent_curriculum-0.1.0/src/agent_curriculum/configs/stage3.yaml

@@ -0,0 +1,9 @@
+stage_id: 3
+name: advanced
+description: "Advanced tasks — complex multi-step with error recovery"
+difficulty_range: [0.4, 0.6]
+num_traces: 0
+learning_rate: 5.0e-05
+batch_size: 4
+num_epochs: 2
+lora_r: 32

agent_curriculum-0.1.0/src/agent_curriculum/configs/stage4.yaml

@@ -0,0 +1,9 @@
+stage_id: 4
+name: expert
+description: "Expert tasks — multi-session with complex error patterns"
+difficulty_range: [0.6, 0.8]
+num_traces: 0
+learning_rate: 3.0e-05
+batch_size: 2
+num_epochs: 2
+lora_r: 32

agent_curriculum-0.1.0/src/agent_curriculum/configs/stage5.yaml

@@ -0,0 +1,9 @@
+stage_id: 5
+name: master
+description: "Master tasks — long-horizon planning with complex recovery"
+difficulty_range: [0.8, 1.0]
+num_traces: 0
+learning_rate: 1.0e-05
+batch_size: 2
+num_epochs: 1
+lora_r: 16

agent_curriculum-0.1.0/src/agent_curriculum/difficulty_scorer.py

@@ -0,0 +1,177 @@
+"""Score trace difficulty based on tool count, error count, reasoning length, and session duration."""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class DifficultyScore:
+    """Composite difficulty score for an agent trace."""
+
+    trace_id: str
+    tool_count: int = 0
+    error_count: int = 0
+    reasoning_length: int = 0
+    session_duration: float = 0.0
+    unique_tools: int = 0
+    retry_count: int = 0
+    branch_count: int = 0
+
+    # Computed scores
+    tool_complexity: float = 0.0
+    error_complexity: float = 0.0
+    reasoning_complexity: float = 0.0
+    duration_complexity: float = 0.0
+    overall_difficulty: float = 0.0
+    difficulty_level: str = "basic"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "trace_id": self.trace_id,
+            "tool_count": self.tool_count,
+            "error_count": self.error_count,
+            "reasoning_length": self.reasoning_length,
+            "session_duration": self.session_duration,
+            "unique_tools": self.unique_tools,
+            "retry_count": self.retry_count,
+            "branch_count": self.branch_count,
+            "tool_complexity": round(self.tool_complexity, 3),
+            "error_complexity": round(self.error_complexity, 3),
+            "reasoning_complexity": round(self.reasoning_complexity, 3),
+            "duration_complexity": round(self.duration_complexity, 3),
+            "overall_difficulty": round(self.overall_difficulty, 3),
+            "difficulty_level": self.difficulty_level,
+        }
+
+
+class DifficultyScorer:
+    """Score agent traces by difficulty to build curriculum training stages.
+
+    Scoring factors:
+    - Tool count: More tool calls = harder
+    - Error count: More errors = harder, but retries show recovery skill
+    - Reasoning length: Longer reasoning = harder
+    - Session duration: Longer sessions = harder
+    - Unique tools: More diverse tool use = harder
+    - Branch count: More decision branches = harder
+    """
+
+    def __init__(
+        self,
+        tool_weight: float = 0.25,
+        error_weight: float = 0.20,
+        reasoning_weight: float = 0.20,
+        duration_weight: float = 0.15,
+        diversity_weight: float = 0.10,
+        branch_weight: float = 0.10,
+        max_tool_count: int = 100,
+        max_reasoning_length: int = 50000,
+        max_session_duration: float = 3600.0,
+    ):
+        self.tool_weight = tool_weight
+        self.error_weight = error_weight
+        self.reasoning_weight = reasoning_weight
+        self.duration_weight = duration_weight
+        self.diversity_weight = diversity_weight
+        self.branch_weight = branch_weight
+        self.max_tool_count = max_tool_count
+        self.max_reasoning_length = max_reasoning_length
+        self.max_session_duration = max_session_duration
+
+    def score_trace(self, trace: dict[str, Any]) -> DifficultyScore:
+        """Score an individual trace for difficulty.
+
+        Args:
+            trace: Dictionary with trace data including tool_calls, errors, etc.
+
+        Returns:
+            DifficultyScore with computed difficulty metrics.
+        """
+        trace_id = trace.get("id", trace.get("trace_id", "unknown"))
+        tool_calls = trace.get("tool_calls", [])
+        errors = trace.get("errors", [])
+        reasoning = trace.get("reasoning", "")
+        duration = trace.get("duration", trace.get("session_duration", 0.0))
+
+        # Extract metrics
+        tool_count = len(tool_calls)
+        error_count = len(errors)
+        unique_tools = len(set(tc.get("name", "") for tc in tool_calls if tc.get("name")))
+        retry_count = sum(1 for e in errors if e.get("type") == "retry" or "retry" in str(e).lower())
+        branch_count = trace.get("branch_count", len(set(tc.get("name", "") for tc in tool_calls[:5])))
+        reasoning_length = len(reasoning) if isinstance(reasoning, str) else sum(len(r) for r in reasoning) if isinstance(reasoning, list) else 0
+
+        # Compute normalized sub-scores (0-1)
+        tool_complexity = min(tool_count / self.max_tool_count, 1.0) if self.max_tool_count > 0 else 0.0
+        error_complexity = 1.0 - math.exp(-error_count / 3.0)  # exponential decay
+        reasoning_complexity = min(reasoning_length / self.max_reasoning_length, 1.0) if self.max_reasoning_length > 0 else 0.0
+        duration_complexity = min(duration / self.max_session_duration, 1.0) if self.max_session_duration > 0 else 0.0
+        diversity_score = min(unique_tools / 6.0, 1.0)  # 6 = max unique tool types
+        branch_complexity = min(branch_count / 10.0, 1.0) if branch_count > 0 else 0.0
+
+        # Weighted overall difficulty
+        overall = (
+            tool_complexity * self.tool_weight
+            + error_complexity * self.error_weight
+            + reasoning_complexity * self.reasoning_weight
+            + duration_complexity * self.duration_weight
+            + diversity_score * self.diversity_weight
+            + branch_complexity * self.branch_weight
+        )
+
+        # Classify difficulty level
+        if overall < 0.2:
+            level = "basic"
+        elif overall < 0.4:
+            level = "intermediate"
+        elif overall < 0.6:
+            level = "advanced"
+        elif overall < 0.8:
+            level = "expert"
+        else:
+            level = "master"
+
+        return DifficultyScore(
+            trace_id=trace_id,
+            tool_count=tool_count,
+            error_count=error_count,
+            reasoning_length=reasoning_length,
+            session_duration=duration,
+            unique_tools=unique_tools,
+            retry_count=retry_count,
+            branch_count=branch_count,
+            tool_complexity=tool_complexity,
+            error_complexity=error_complexity,
+            reasoning_complexity=reasoning_complexity,
+            duration_complexity=duration_complexity,
+            overall_difficulty=overall,
+            difficulty_level=level,
+        )
+
+    def score_file(self, path: str | Path) -> list[DifficultyScore]:
+        """Score all traces in a JSONL file.
+
+        Args:
+            path: Path to JSONL file with traces.
+
+        Returns:
+            List of DifficultyScore objects.
+        """
+        path = Path(path)
+        scores = []
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    trace = json.loads(line)
+                    scores.append(self.score_trace(trace))
+                except json.JSONDecodeError:
+                    continue
+        return scores

agent_curriculum-0.1.0/src/agent_curriculum/scheduler.py

@@ -0,0 +1,80 @@
+"""Learning rate and batch size scheduling per curriculum stage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class ScheduleConfig:
+    """Learning rate and batch size schedule for a single stage."""
+
+    stage_id: int
+    learning_rate: float
+    batch_size: int
+    warmup_steps: int = 0
+    lora_r: int = 64
+    lora_alpha: int = 128
+    gradient_accumulation_steps: int = 4
+    weight_decay: float = 0.01
+    num_epochs: int = 2
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: getattr(self, k) for k in self.__dataclass_fields__}
+
+
+# Default schedule: progressively lower learning rates and higher discriminative LoRA
+DEFAULT_SCHEDULE: list[ScheduleConfig] = [
+    ScheduleConfig(stage_id=1, learning_rate=2e-4, batch_size=8, lora_r=64, num_epochs=3),
+    ScheduleConfig(stage_id=2, learning_rate=1e-4, batch_size=4, lora_r=64, num_epochs=2),
+    ScheduleConfig(stage_id=3, learning_rate=5e-5, batch_size=4, lora_r=32, num_epochs=2),
+    ScheduleConfig(stage_id=4, learning_rate=3e-5, batch_size=2, lora_r=32, num_epochs=2),
+    ScheduleConfig(stage_id=5, learning_rate=1e-5, batch_size=2, lora_r=16, num_epochs=1),
+]
+
+
+class CurriculumScheduler:
+    """Schedule learning rates, batch sizes, and LoRA parameters per stage.
+
+    The scheduler follows a curriculum learning approach where later stages
+    use lower learning rates (to preserve earlier learning), smaller LoRA
+    ranks (more discriminative fine-tuning), and smaller batch sizes
+    (more gradient updates per sample).
+    """
+
+    def __init__(self, schedule: list[ScheduleConfig] | None = None):
+        self.schedule = schedule or DEFAULT_SCHEDULE
+
+    def get_config(self, stage_id: int) -> ScheduleConfig:
+        """Get training config for a specific stage.
+
+        Args:
+            stage_id: Curriculum stage (1-5).
+
+        Returns:
+            ScheduleConfig for the stage.
+
+        Raises:
+            ValueError: If stage_id is out of range.
+        """
+        for s in self.schedule:
+            if s.stage_id == stage_id:
+                return s
+        raise ValueError(f"Unknown stage {stage_id}. Available: 1-{len(self.schedule)}")
+
+    def get_all_configs(self) -> list[ScheduleConfig]:
+        """Get all stage configs in order."""
+        return list(self.schedule)
+
+    def save_configs(self, output_dir: str) -> None:
+        """Save all stage configs as YAML files."""
+        from pathlib import Path
+        output_path = Path(output_dir)
+        output_path.mkdir(parents=True, exist_ok=True)
+        for config in self.schedule:
+            path = output_path / f"stage{config.stage_id}.yaml"
+            with open(path, "w") as f:
+                yaml.dump(config.to_dict(), f, default_flow_style=False)

agent_curriculum-0.1.0/src/agent_curriculum/stage_builder.py

@@ -0,0 +1,197 @@
+"""Build curriculum training stages from difficulty-scored traces."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from agent_curriculum.difficulty_scorer import DifficultyScore, DifficultyScorer
+
+
+@dataclass
+class CurriculumStage:
+    """A single stage in the training curriculum."""
+
+    stage_id: int
+    name: str
+    description: str
+    difficulty_range: tuple[float, float]
+    max_tools: int
+    max_errors: int
+    traces: list[dict[str, Any]] = field(default_factory=list)
+    scores: list[DifficultyScore] = field(default_factory=list)
+    config: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "stage_id": self.stage_id,
+            "name": self.name,
+            "description": self.description,
+            "difficulty_range": list(self.difficulty_range),
+            "max_tools": self.max_tools,
+            "max_errors": self.max_errors,
+            "num_traces": len(self.traces),
+            "config": self.config,
+        }
+
+
+# Pre-defined curriculum stages
+STAGE_DEFINITIONS = [
+    CurriculumStage(
+        stage_id=1,
+        name="basic",
+        description="Basic tool use — simple read/edit/bash tasks with no errors",
+        difficulty_range=(0.0, 0.2),
+        max_tools=5,
+        max_errors=0,
+        config={
+            "learning_rate": 2e-4,
+            "batch_size": 8,
+            "num_epochs": 3,
+            "lora_r": 64,
+        },
+    ),
+    CurriculumStage(
+        stage_id=2,
+        name="intermediate",
+        description="Intermediate tasks — multi-tool sequences with simple error recovery",
+        difficulty_range=(0.2, 0.4),
+        max_tools=15,
+        max_errors=2,
+        config={
+            "learning_rate": 1e-4,
+            "batch_size": 4,
+            "num_epochs": 2,
+            "lora_r": 64,
+        },
+    ),
+    CurriculumStage(
+        stage_id=3,
+        name="advanced",
+        description="Advanced tasks — complex multi-step with error recovery",
+        difficulty_range=(0.4, 0.6),
+        max_tools=30,
+        max_errors=5,
+        config={
+            "learning_rate": 5e-5,
+            "batch_size": 4,
+            "num_epochs": 2,
+            "lora_r": 32,
+        },
+    ),
+    CurriculumStage(
+        stage_id=4,
+        name="expert",
+        description="Expert tasks — multi-session with complex error patterns",
+        difficulty_range=(0.6, 0.8),
+        max_tools=60,
+        max_errors=10,
+        config={
+            "learning_rate": 3e-5,
+            "batch_size": 2,
+            "num_epochs": 2,
+            "lora_r": 32,
+        },
+    ),
+    CurriculumStage(
+        stage_id=5,
+        name="master",
+        description="Master tasks — long-horizon planning with complex recovery",
+        difficulty_range=(0.8, 1.0),
+        max_tools=100,
+        max_errors=20,
+        config={
+            "learning_rate": 1e-5,
+            "batch_size": 2,
+            "num_epochs": 1,
+            "lora_r": 16,
+        },
+    ),
+]
+
+
+class StageBuilder:
+    """Build training stages from difficulty-scored traces.
+
+    Assigns traces to curriculum stages based on difficulty scores and
+    generates YAML configs for each stage.
+    """
+
+    def __init__(self, scorer: DifficultyScorer | None = None, stages: list[CurriculumStage] | None = None):
+        self.scorer = scorer or DifficultyScorer()
+        self.stages = stages or [CurriculumStage(**s.__dict__) if isinstance(s, CurriculumStage) else CurriculumStage(**s) for s in STAGE_DEFINITIONS]
+
+    def build_stages(self, trace_path: str | Path) -> list[CurriculumStage]:
+        """Build curriculum stages from a trace file.
+
+        Args:
+            trace_path: Path to JSONL file with agent traces.
+
+        Returns:
+            List of CurriculumStage objects with assigned traces.
+        """
+        trace_path = Path(trace_path)
+        scores = self.scorer.score_file(trace_path)
+
+        # Load traces
+        traces: list[dict[str, Any]] = []
+        with open(trace_path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    traces.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+
+        # Assign traces to stages based on difficulty
+        for score, trace in zip(scores, traces):
+            for stage in self.stages:
+                low, high = stage.difficulty_range
+                if low <= score.overall_difficulty < high:
+                    stage.traces.append(trace)
+                    stage.scores.append(score)
+                    break
+
+        # Add unmatched traces to the closest stage
+        assigned_traces = set()
+        for stage in self.stages:
+            for t in stage.traces:
+                if "id" in t:
+                    assigned_traces.add(t["id"])
+
+        return self.stages
+
+    def generate_configs(self, output_dir: str | Path) -> list[Path]:
+        """Generate YAML config files for each stage.
+
+        Args:
+            output_dir: Directory to write config files.
+
+        Returns:
+            List of paths to generated config files.
+        """
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        config_paths = []
+
+        for stage in self.stages:
+            config = {
+                "stage_id": stage.stage_id,
+                "name": stage.name,
+                "description": stage.description,
+                "difficulty_range": list(stage.difficulty_range),
+                "num_traces": len(stage.traces),
+                **stage.config,
+            }
+            config_path = output_dir / f"stage{stage.stage_id}.yaml"
+            with open(config_path, "w") as f:
+                yaml.dump(config, f, default_flow_style=False)
+            config_paths.append(config_path)
+
+        return config_paths

agent_curriculum-0.1.0/src/agent_curriculum/trainer.py

@@ -0,0 +1,124 @@
+"""Train model through curriculum stages with progressive difficulty."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from agent_curriculum.stage_builder import StageBuilder, CurriculumStage
+from agent_curriculum.difficulty_scorer import DifficultyScorer
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TrainingResult:
+    """Result of training a single curriculum stage."""
+
+    stage_id: int
+    stage_name: str
+    num_traces: int
+    status: str = "configured"
+    output_dir: str = ""
+    metrics: dict[str, Any] = field(default_factory=dict)
+
+
+class CurriculumTrainer:
+    """Train a model through curriculum stages with progressive difficulty.
+
+    The curriculum approach trains the model on easy examples first (basic
+    tool use) and progressively introduces harder examples (multi-step
+    reasoning with errors), allowing the model to build foundational
+    skills before tackling complex tasks.
+    """
+
+    def __init__(
+        self,
+        base_model: str = "Qwen/Qwen2.5-14B",
+        output_dir: str = "output/curriculum",
+        scorer: DifficultyScorer | None = None,
+        builder: StageBuilder | None = None,
+    ):
+        self.base_model = base_model
+        self.output_dir = Path(output_dir)
+        self.scorer = scorer or DifficultyScorer()
+        self.builder = builder or StageBuilder(scorer=self.scorer)
+        self.results: list[TrainingResult] = []
+
+    def train_curriculum(
+        self,
+        trace_path: str | Path,
+        start_stage: int = 1,
+        end_stage: int = 5,
+    ) -> list[TrainingResult]:
+        """Train the model through curriculum stages.
+
+        Args:
+            trace_path: Path to JSONL file with agent traces.
+            start_stage: Stage to start from (1-5).
+            end_stage: Stage to end at (1-5).
+
+        Returns:
+            List of TrainingResult objects.
+        """
+        # Build stages from traces
+        stages = self.builder.build_stages(trace_path)
+
+        self.results = []
+        for stage in stages:
+            if stage.stage_id < start_stage or stage.stage_id > end_stage:
+                continue
+
+            result = self._train_stage(stage)
+            self.results.append(result)
+
+            logger.info(f"Stage {stage.stage_id} ({stage.name}): {result.status}")
+            logger.info(f"  Traces: {result.num_traces}, Output: {result.output_dir}")
+
+        return self.results
+
+    def _train_stage(self, stage: CurriculumStage) -> TrainingResult:
+        """Train a single curriculum stage.
+
+        In production, this would call the training pipeline (Unsloth/trl).
+        Here we configure and prepare the training.
+        """
+        stage_dir = self.output_dir / f"stage{stage.stage_id}_{stage.name}"
+        stage_dir.mkdir(parents=True, exist_ok=True)
+
+        # Save stage traces
+        traces_path = stage_dir / "traces.jsonl"
+        with open(traces_path, "w") as f:
+            for trace in stage.traces:
+                f.write(json.dumps(trace) + "\n")
+
+        # Save stage config
+        config = {
+            **stage.config,
+            "base_model": self.base_model,
+            "stage_id": stage.stage_id,
+            "stage_name": stage.name,
+            "num_traces": len(stage.traces),
+            "difficulty_range": list(stage.difficulty_range),
+        }
+        config_path = stage_dir / "training_config.json"
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+
+        return TrainingResult(
+            stage_id=stage.stage_id,
+            stage_name=stage.name,
+            num_traces=len(stage.traces),
+            status="configured",
+            output_dir=str(stage_dir),
+            metrics={
+                "num_traces": len(stage.traces),
+                "difficulty_range": list(stage.difficulty_range),
+                "learning_rate": stage.config.get("learning_rate"),
+                "batch_size": stage.config.get("batch_size"),
+                "lora_r": stage.config.get("lora_r"),
+            },
+        )