docs/agent-design.md

# Agent Design: ResearchLink AI

## Agent Responsibilities

| Agent | Input | Output | Uses LLM? |
|-------|-------|--------|-----------|
| IntakeAgent | raw dict | IngestionInput | No |
| SourceResolverAgent | IngestionInput | ResolvedSources | No |
| PDFExtractionAgent | ResolvedSources | PaperExtraction | No |
| MetadataAgent | IngestionInput + PaperExtraction | PaperMetadata | Yes |
| CitationVerificationAgent | PaperExtraction + bibtex | CitationReport | No |
| GitHubRepoAnalyzerAgent | github_url | RepoAnalysis | No |
| PaperDigestAgent | PaperMetadata + PaperExtraction | dict[str, str] | Yes |
| LiteratureReviewAgent | PaperMetadata + PaperExtraction | dict[str, str] | Yes |
| ConceptMapAgent | PaperMetadata + PaperExtraction | dict[str, str] | Yes |
| ImplementationLinkAgent | PaperMetadata + RepoAnalysis | dict[str, str] | Yes |
| ReproducibilityAgent | PaperMetadata + RepoAnalysis + Extraction | dict[str, str] | Yes |
| LimitationsAgent | PaperMetadata + PaperExtraction | dict[str, str] | Yes |
| TeachingPathAgent | PaperMetadata + PaperExtraction | dict[str, str] | Yes |
| LabsGeneratorAgent | PaperMetadata + PaperExtraction | dict[str, str] | Yes |
| ReviewerAgent | PaperMetadata + CitationReport + content | dict[str, str] | Yes |
| ExportAgent | All above | GenerationReport | No |

## Base Agent

All agents inherit from `BaseAgent` which provides:

- `_call_llm(system, user)` — standardised Anthropic API call
- `log(message)` — verbose-gated console logging
- `warn(message)` — always-visible warnings
- Settings injection via `get_settings()`

## Failure Handling

Every agent catches exceptions internally and returns partial results with notes.
The pipeline continues even if individual agents fail.
All failures are collected in the `GenerationReport`.

## LLM System Prompts

Each content-generating agent has a focused system prompt that:
1. States the agent's role
2. Mandates the label system (`[paper-claim]`, `[needs-verification]`, etc.)
3. Forbids inventing citations
4. Specifies output format