src/researchlink/agents/implementation_link_agent.py

"""Implementation Link Agent — connects the paper to its GitHub repository."""

from __future__ import annotations

from researchlink.agents.base import BaseAgent
from researchlink.providers.base import AgentRole
from researchlink.schemas.paper import PaperMetadata
from researchlink.schemas.repository import RepoAnalysis
from researchlink.services import offline

SYSTEM_IMPL = """You are a senior software engineer helping researchers understand code repositories.
Be cautious about claims. Never assert exact reproducibility unless verified.
Use [needs-verification] for any unconfirmed claims about the code."""




class ImplementationLinkAgent(BaseAgent):
    name = "ImplementationLinkAgent"
    task_role = AgentRole.coding

    def run(
        self,
        meta: PaperMetadata,
        repo: RepoAnalysis,
    ) -> dict[str, str]:
        self.log("Generating implementation link file...")

        content = self._generate(meta, repo)
        return {"implementation-link.md": content}

    def _generate(self, meta: PaperMetadata, repo: RepoAnalysis) -> str:
        if not repo.url:
            return offline.implementation_link(meta, repo)

        context = (
            f"Paper: {meta.title}\n"
            f"GitHub URL: {repo.url}\n"
            f"Owner/Repo: {repo.owner}/{repo.repo_name}\n"
            f"Language: {repo.detected_language or 'unknown'}\n"
            f"Frameworks: {', '.join(repo.detected_frameworks)}\n"
            f"Top-level folders: {repo.top_level_folders[:15]}\n"
            f"Top-level files: {repo.top_level_files[:15]}\n"
            f"Has tests: {repo.has_tests}\n"
            f"Setup commands: {repo.setup_commands}\n"
            f"Is likely official impl: {repo.is_likely_official_impl}\n"
            f"Confidence: {repo.official_impl_confidence}\n"
        )
        if repo.readme_content:
            context += f"README (first 1000 chars):\n{repo.readme_content[:1000]}\n"

        prompt = f"""Based on the following repository information, write implementation-link.md.

{context}

Paper areas: {', '.join(meta.areas)}
Paper tags: {', '.join(meta.tags)}

Write with these EXACT sections:
# Implementation Link: {meta.title}

## Official or Related Code Repository

## What the Repository Contains

## How It Maps to the Paper

## Important Folders

## Suggested Reading Order for the Code

## Reproducibility Notes

## Known Metadata or Documentation Issues

## Suggested Future Improvements

Use [needs-verification] for unconfirmed claims.
Do not assert exact reproducibility of paper results."""

        return self._complete(
            SYSTEM_IMPL, prompt,
            extractive=lambda: offline.implementation_link(meta, repo),
        )