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
```