Metadata-Version: 2.4
Name: pgagent
Version: 0.1.0
Summary: ProteoGenomics CLI — terminal-first multi-agent research assistant
Author: Zhang Lab
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer[all]>=0.12
Requires-Dist: rich>=13
Requires-Dist: pydantic>=2.5
Requires-Dist: ruamel.yaml>=0.18
Requires-Dist: jinja2>=3.1
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.26
Requires-Dist: matplotlib>=3.8
Requires-Dist: seaborn>=0.13
Requires-Dist: langgraph>=0.1
Requires-Dist: langchain-core>=0.2
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.5; extra == "gemini"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"

# 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

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

```bash
# 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).

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

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

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