docs/architecture.md

Architecture: ResearchLink AI

Overview

ResearchLink AI is a sequential multi-agent pipeline where each agent handles one concern and passes structured Pydantic models to the next.

Pipeline Flow

IngestionInput (user)
    │
    ▼
IntakeAgent ──────────────── validates + normalises inputs
    │
    ▼
SourceResolverAgent ────────── downloads PDF, checks URLs
    │
    ▼
PDFExtractionAgent ─────────── extracts text + structure
    │
    ▼
MetadataAgent ──────────────── builds PaperMetadata (+ LLM)
    │
    ▼
CitationVerificationAgent ───── parses + classifies references
    │
    ▼
GitHubRepoAnalyzerAgent ─────── inspects code repository
    │
    ▼
[Content Agents — all run in sequence, all use LLM]
PaperDigestAgent
LiteratureReviewAgent
ConceptMapAgent
ImplementationLinkAgent
ReproducibilityAgent
LimitationsAgent
TeachingPathAgent
LabsGeneratorAgent
    │
    ▼
ReviewerAgent ──────────────── quality-checks all content
    │
    ▼
ExportAgent ─────────────────── writes files to disk
    │
    ▼
GenerationReport

Key Design Decisions

Pydantic schemas: All inter-agent data is typed. No raw dict passing between agents.

LLM for content, heuristics for structure: Structural extraction (PDF parsing, URL checking, citation regex) uses deterministic code. Content generation (digest, review, labs) uses the Claude API.

Fail-open with flags: If an agent step fails (LLM error, URL unreachable), it returns a partial result with notes and continues. Errors are collected in the GenerationReport.

Honest labels: All generated content uses [paper-claim], [agent-interpretation], and [needs-verification] labels throughout.

File Structure

src/researchlink/
  cli.py          — Typer CLI entrypoint
  pipeline.py     — Pipeline orchestrator
  config.py       — Settings (env vars / .env)
  schemas/        — Pydantic data models
  agents/         — One file per agent
  services/       — Reusable utilities (PDF, HTTP, GitHub, etc.)
  templates/      — Jinja2 templates (for structured sections)
  validators/     — Output and citation validation