acquisition-agent-spec

Agent Specification: Acquisition Agent

1. Agent Overview

| Attribute | Value | |-----------|-------| | **Name** | Acquisition Agent | | **ID** | research-acquisition-agent | | **Purpose** | Download research papers, extract metadata, validate FAIR compliance, and assign persistent identifiers | | **Lifecycle Stage** | Acquisition (Stage 2 of Research Framework) | | **Model** | sonnet | | **Version** | 1.0.0 | | **Status** | Draft |

Description

The Acquisition Agent transforms discovery results into a structured research corpus. It downloads PDFs from open access sources, extracts or retrieves metadata, assigns REF-XXX persistent identifiers, computes SHA-256 checksums for integrity verification, and validates FAIR (Findable, Accessible, Interoperable, Reusable) compliance. The agent handles paywalled papers through manual upload workflows and integrates with shared research corpora to avoid duplicate downloads.

2. Capabilities

Primary Capabilities

| Capability | Description | NFR Reference | |------------|-------------|---------------| | PDF Download | Download papers from Semantic Scholar, arXiv, publisher sites | NFR-RF-A-01 | | Metadata Extraction | Extract title, authors, year, DOI from PDF or API | NFR-RF-A-02 | | FAIR Validation | Score papers on Findable, Accessible, Interoperable, Reusable criteria | NFR-RF-A-09 | | Checksum Computation | Generate SHA-256 hashes for integrity verification | NFR-RF-A-05 | | REF-XXX Assignment | Assign sequential persistent identifiers | BR-RF-A-001 | | Bulk Acquisition | Process multiple papers in parallel with rate limiting | NFR-RF-A-03 |

Secondary Capabilities

| Capability | Description | |------------|-------------| | Manual Upload Handling | Accept user-provided PDFs for paywalled papers | | Shared Corpus Deduplication | Create symlinks to existing papers in shared repository | | Format Validation | Verify PDF format via magic bytes check | | Progress Reporting | Real-time progress updates for bulk operations |

3. Tools

Required Tools

| Tool | Purpose | Permission | |------|---------|------------| | Bash | Execute downloads, compute checksums | Execute | | Read | Access acquisition queue, existing metadata | Read | | Write | Save PDFs, metadata JSON, reports | Write | | Glob | Find existing papers for deduplication | Read | | Grep | Search metadata for duplicates | Read |

External APIs

| API | Endpoint | Purpose | Auth | |-----|----------|---------|------| | Semantic Scholar | `api.semanticscholar.org` | Paper metadata, open access URLs | None | | arXiv | `arxiv.org/pdf/` | Direct PDF download | None | | CrossRef | `api.crossref.org` | DOI resolution | None | | Unpaywall | `api.unpaywall.org` | Open access detection | Email header |

System Tools

| Tool | Purpose | |------|---------| | `curl` / `wget` | HTTP downloads with resume support | | `sha256sum` | Checksum computation | | `file` | MIME type validation | | `pdftotext` | PDF text extraction |

4. Triggers

Automatic Triggers

| Trigger | Condition | Action | |---------|-----------|--------| | Discovery Complete | Acquisition queue populated (UC-RF-001) | Start bulk acquisition | | Workflow Stage | UC-RF-008 initiates Stage 2 | Process workflow queue |

Manual Triggers

| Trigger | Command | Description | |---------|---------|-------------| | Single Acquisition | `aiwg research acquire REF-XXX` | Acquire specific paper | | Bulk from Queue | `aiwg research acquire --from-queue` | Process entire queue | | Manual Upload | `aiwg research acquire --upload /path/to/file.pdf` | Add local PDF | | Retry Failed | `aiwg research acquire --retry-failed` | Retry failed downloads |

Event Triggers

| Event | Source | Action | |-------|--------|--------| | Paper Selected | Discovery Agent | Add to acquisition queue | | Quality Gate Failed | Workflow Agent | Acquire additional sources |

5. Inputs/Outputs

Inputs

| Input | Format | Source | Validation | |-------|--------|--------|------------| | Acquisition Queue | JSON | `.aiwg/research/discovery/acquisition-queue.json` | Valid paper IDs | | Paper IDs | Array of strings | Command arguments | Valid IDs in queue | | Manual PDF Path | File path | User input | File exists, valid PDF | | Manual Metadata | JSON object | User input (if extraction fails) | Required fields present |

Outputs

| Output | Format | Location | Retention | |--------|--------|----------|-----------| | PDF Files | Binary PDF | `.aiwg/research/sources/pdfs/{REF-XXX}-{slug}.pdf` | Permanent | | Metadata JSON | JSON | `.aiwg/research/sources/metadata/{REF-XXX}-metadata.json` | Permanent | | Acquisition Report | Markdown | `.aiwg/research/sources/acquisition-report-{timestamp}.md` | Permanent | | Checksums | Text | `.aiwg/research/sources/checksums.txt` | Permanent |

Output Schema: Metadata JSON

{
  "ref_id": "REF-025",
  "title": "OAuth 2.0 Security Best Practices",
  "title_slug": "oauth-2-security-best-practices",
  "authors": [
    {"name": "Smith, John", "affiliation": "Stanford University"},
    {"name": "Doe, Jane", "affiliation": "MIT"}
  ],
  "year": 2023,
  "venue": "ACM Conference on Computer and Communications Security (CCS)",
  "venue_tier": "A*",
  "doi": "10.1145/3576915.3623456",
  "abstract": "This paper presents security best practices for OAuth 2.0...",
  "license": "CC-BY-4.0",
  "url": "https://www.semanticscholar.org/paper/abc123def456",
  "pdf_url": "https://arxiv.org/pdf/2301.12345.pdf",
  "citations": 42,
  "acquisition_timestamp": "2026-01-25T14:30:00Z",
  "acquisition_source": "semantic-scholar-api",
  "fair_score": {
    "findable": 90,
    "accessible": 100,
    "interoperable": 95,
    "reusable": 90,
    "overall": 94
  },
  "checksum_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "file_size_bytes": 2457600,
  "provenance": {
    "discovery_query": "OAuth2 security best practices",
    "discovery_timestamp": "2026-01-25T10:00:00Z",
    "