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
Metadata
Release files for pgagent 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pgagent-0.1.0.tar.gz | 35.5 kB | Without provenance | Details for pgagent-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pgagent-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pgagent-0.1.0-py3-none-any.whl |
Total release size: 75.2 kB
Release files / pgagent-0.1.0.tar.gz
| Download URL | pgagent-0.1.0.tar.gz |
|---|---|
| Size | 35.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c78484b48ce1f7d2e86393aa3b2bb5a44c073e10c96822d26132f2ab72308e20
|
|
BLAKE2b-256 checksum How to use checksums |
65fcd5de0eaf6b78eecae24e1a668031010d7eaad62f2c21f8b3c26f014ff91d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.6
|
Release files / pgagent-0.1.0-py3-none-any.whl
| Download URL | pgagent-0.1.0-py3-none-any.whl |
|---|---|
| Size | 39.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2ae86643e0a96c4d7635dc33ecbd0b3332938f29e12162fed32c7f6fd2df6532
|
|
BLAKE2b-256 checksum How to use checksums |
af45c464dfb8b45f072bafda9aa9b48fb673981666e839afb26c2935147897d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.6
|
Security for pgagent 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.