pgagent — ProteoGenomics Agentic Research Assistant

A terminal-first, multi-agent research assistant for proteogenomics.
Literature review · Data analysis · Hypothesis generation · Manuscript drafting
Zero API keys required — powered by MockClient by default.

---

Quick Start

# 1. Install
pip install -e ".[dev]"

# 2. One-time setup
pgagent setup

# 3. Create a project workspace
pgagent init demo
cd demo

# 4. Run the full pipeline (MockClient, no API keys)
pgagent run "Identify dysregulated pathways and propose hypotheses"

# 5. Publish HTML report
pgagent report publish

# 6. Open the report
open results/reports/latest.html   # macOS

---

Installation

# Base (MockClient included)
pip install -e .

# With OpenAI
pip install -e ".[openai]"

# With Anthropic
pip install -e ".[anthropic]"

# With Google Gemini
pip install -e ".[gemini]"

# Dev (includes pytest)
pip install -e ".[dev]"

---

CLI Reference

Command	Description
pgagent	Start interactive REPL session
pgagent run "<query>"	Explicit run command
pgagent init <project>	Create workspace
pgagent setup	Create ~/.pgagent/config.yaml
pgagent doctor	Environment diagnostics
pgagent report publish	Markdown → HTML
pgagent cache clear	Clear tool cache
pgagent agents list	List all agents
pgagent config show	Display configuration
pgagent config set <key> <value>	Set a config value
pgagent summarize latest	Print run summary
pgagent explain <artifact>	Explain a plot/table
pgagent manuscript pack	Package manuscript files
pgagent papers add <pdf>	Add offline paper
pgagent resume <run_id>	Resume from checkpoint

---

Architecture

pgagent run "query"
      │
      ▼
┌─────────────────────────────────────────────────┐
│             LangGraph StateGraph                │
│                                                 │
│  lead_plan ──► literature ──► data ──► stats   │
│                                          │      │
│                              hypothesis ◄┘      │
│                                   │             │
│                  writing ◄────────┘             │
│                     │                           │
│               verifier ──(ok)──► finalize       │
│                     │                           │
│               (retry)──► writing                │
└─────────────────────────────────────────────────┘
      │
      ▼
results/
  logs/run_<id>.jsonl
  reports/run_<id>.md  ←── latest.md
  manifests/run_<id>.yaml
  artifacts/run_<id>/
    volcano_<hash>.png
    heatmap_<hash>.png
  checkpoints/run_<id>.json

Evidence-First Policy

Every claim in the generated report must be:

• A) Citation-backed (PMID:...)
• B) Artifact-backed (references a figure path)
• C) Labeled hypothesis with a confidence score (0–1)

VerifierAgent audits all sections and computes an Evidence Coverage %.

---

Workspace Layout

<project_root>/
  pgproject.yaml
  data/raw/                  ← place your TSV/CSV files here
  data/processed/
  results/
    artifacts/               ← volcano.png, heatmap.png
    reports/                 ← run_<id>.md, latest.md
    logs/                    ← run_<id>.jsonl
    manifests/               ← run_<id>.yaml
    checkpoints/             ← run_<id>.json (resume support)
  knowledge/
    papers/                  ← offline PDFs (pgagent papers add)
    bib/
    notes/
  cache/                     ← SHA-256 content cache

---

LLM Provider Configuration

Default is MockClient (offline, deterministic).

# Switch to OpenAI
pgagent config set default_provider openai
pgagent config set default_model gpt-4o

# Switch per-agent
pgagent config set agent_models.literature.provider anthropic
pgagent config set agent_models.literature.model claude-3-5-sonnet-20241022

Or edit ~/.pgagent/config.yaml directly.

---

Demo: End-to-End Run

pip install -e ".[dev]"
pgagent setup
pgagent init demo && cd demo

# Copy synthetic data
cp /path/to/pgagent/examples/data/synthetic_proteomics.tsv data/raw/

# Run
pgagent run "Identify pathways and propose hypotheses for the proteomics dataset"

# View outputs
ls results/logs/       # JSONL event log
ls results/reports/    # Markdown report + latest.md
ls results/manifests/  # YAML manifest
ls results/artifacts/  # PNG plots

# Publish HTML
pgagent report publish
open results/reports/latest.html

# Summarize
pgagent summarize latest

# Doctor
pgagent doctor

---

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Test coverage:

Test file	What it tests
test_cache.py	Cache hit/miss, clear, key stability
test_manifest.py	Manifest completeness, JSONL log
test_evidence.py	Evidence-First policy, coverage %
test_checkpoint.py	Save/load round-trip, list
test_report.py	All 9 section headings, HTML publish

---

Agents Reference

Agent	Class	Role
literature	LiteratureAgent	PubMed search, abstract fetch, citation assembly
data	DataAgent	Table loading, QC, data discovery
stats	StatsAgent	Differential expression, enrichment, volcano + heatmap
hypothesis	HypothesisAgent	Ranked hypothesis generation with confidence scores
writing	WritingAgent	9-section manuscript drafting
verifier	VerifierAgent	Evidence-First Policy + coverage %

---

Safety Guardrails

Tools only read/write inside project_root. Path traversal is blocked at the load_table level.

---

License

MIT — Zhang Lab