src/researchlink/agents/teaching_path_agent.py

"""Teaching Path Agent — creates a staged learning path through the paper."""

from __future__ import annotations

from researchlink.agents.base import BaseAgent
from researchlink.providers.base import AgentRole
from researchlink.schemas.paper import PaperExtraction, PaperMetadata
from researchlink.services import offline

SYSTEM_TEACH = """You are a patient, expert educator creating learning paths for research papers.
Break complex ideas into stages. Link each stage to specific paper sections or code locations.
Focus on building intuition before formalism."""




class TeachingPathAgent(BaseAgent):
    name = "TeachingPathAgent"
    task_role = AgentRole.writing

    def run(
        self,
        meta: PaperMetadata,
        extraction: PaperExtraction,
    ) -> dict[str, str]:
        self.log("Generating teaching path...")

        context = (
            f"Title: {meta.title}\n"
            f"Areas: {', '.join(meta.areas)}\n"
            f"Tags: {', '.join(meta.tags)}\n"
        )
        if extraction.abstract:
            context += f"Abstract: {extraction.abstract[:1000]}\n"
        if extraction.section_headings:
            context += f"Sections: {extraction.section_headings[:15]}\n"

        prompt = f"""Based on the following paper information, write teaching-path.md.

Paper Information:
{context}

Write with these EXACT sections:
# Teaching Path: {meta.title}

## Stage 1: Understand the Problem

**Prerequisites:** ...
**Goal:** ...
**Key questions to answer:** ...

## Stage 2: Understand the Background

**Prerequisites:** ...
**Goal:** ...
**Recommended resources:** ...

## Stage 3: Understand the Method

**Prerequisites:** ...
**Goal:** ...
**Link to paper section:** ...

## Stage 4: Understand the Experiments

**Prerequisites:** ...
**Goal:** ...
**Link to paper section:** ...

## Stage 5: Understand the Implementation

**Prerequisites:** ...
**Goal:** ...
**Link to code:** ...
**Link to labs:** [labs/README.md](labs/README.md)

## Stage 6: Understand the Limitations

**Prerequisites:** ...
**Goal:** ...
**Link to:** [limitations.md](limitations.md)

## Stage 7: Extend the Work

**Prerequisites:** ...
**Goal:** ...
**Suggested directions:** ...

Make each stage concrete and actionable."""

        content = self._complete(
            SYSTEM_TEACH, prompt,
            extractive=lambda: offline.teaching_path(meta, extraction),
        )
        return {"teaching-path.md": content}