Metadata-Version: 2.4
Name: autoreport-gui
Version: 1.1
Summary: Agent-based automated physics experiment report writing system
Project-URL: Homepage, https://github.com/xjsongphy/AutoReport
Project-URL: Repository, https://github.com/xjsongphy/AutoReport
Project-URL: Issues, https://github.com/xjsongphy/AutoReport/issues
Author: xjsongphy
License-Expression: MIT
License-File: LICENSE
Keywords: agents,latex,physics,pyqt6,report
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Requires-Dist: aiofiles<25.0.0,>=24.0.0
Requires-Dist: anthropic<1.0.0,>=0.45.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: loguru<1.0.0,>=0.7.3
Requires-Dist: markdown<4.0.0,>=3.5.0
Requires-Dist: matplotlib<4.0.0,>=3.10.0
Requires-Dist: openai<2.0.0,>=1.60.0
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas<3.0.0,>=2.2.0
Requires-Dist: pydantic-settings<3.0.0,>=2.12.0
Requires-Dist: pydantic<3.0.0,>=2.12.0
Requires-Dist: pyqt6-qscintilla>=2.14.1
Requires-Dist: pyqt6<7.0.0,>=6.8.0
Requires-Dist: pyyaml<7.0.0,>=6.0
Requires-Dist: rich<14.0.0,>=13.0.0
Requires-Dist: typer<1.0.0,>=0.15.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio<1.0.0,>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

![title](https://raw.githubusercontent.com/xjsongphy/AutoReport/master/assets/screenshots/title.png)

### A Multi-Agent Collaborative System for Automated Physics Experiment Report Writing

[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#)
[![Python](https://img.shields.io/badge/python-%E2%89%A5%203.12-blue.svg)](https://www.python.org/)
[![Built with PyQt6](https://img.shields.io/badge/built%20with-PyQt6-green.svg)](https://www.riverbankcomputing.com/software/pyqt/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/xjsongphy/AutoReport/blob/master/LICENSE)

English | [中文](https://github.com/xjsongphy/AutoReport/blob/master/README_zh.md)

</div>

## Overview

A multi-agent collaborative automated physics experiment report writing system. Users provide experimental data and reference materials, then agents collaboratively generate LaTeX reports through theoretical derivation, data analysis, visualization, and typesetting.

## Features

### Core Capabilities
- **Multi-Agent Collaboration** — Main Agent orchestrates, with four sub-agents (Data Analysis, Plotting, Theory, Report) each specializing in their domain
- **Directory Permission Isolation** — Each agent can only write to designated directories, preventing cross-contamination
- **Waitlist/Todolist Tracking** — Structured task delegation with linked waitlist-todolist chains and auto-notification on completion
- **Checkpoint Rollback** — Automatically creates checkpoints at key nodes; roll back to any historical state
- **Interactive Adjustment** — Users can message any agent at any time for intervention and optimization

### UI/UX (Claude Code Style)
- **Streaming Responses** — Real-time agent output, word-by-word streaming
- **Switchable Agent Panel** — A single agent chat panel with a dropdown selector to switch among Main / Data Analysis / Plotting / Theory / Report
- **Recent Projects Cache** — VSCode-style recent projects list, cached in `~/.autoreport/recent_projects.json`
- **File Explorer** — VSCode-style file tree with 22px row height, 16px icons, concise labels (Data, References, Theory, Plots, Outline, Tex)
- **Context Chip Bar** — Visual indicator for file/line selections with toggle to include/exclude from messages
- **Chat Interface** — Claude Code-style conversation display with proper Markdown rendering and grouped tool calls
- **Slash Commands** — `/clear`, `/new`, `/help`, `/compact`, `/init`

### Developer Tools
- **@ File References** — Type `@` in chat to fuzzy-search and insert file references as Markdown links
- **Selected Line Context** — Text selections in preview pane are automatically appended to agent messages
- **Sub-Agent Debug Mode** — Disconnect from Main Agent channel, test individual agents independently

### LLM Integration
- **Multi-Provider Support** — Anthropic, OpenAI, DeepSeek, etc. Runtime model switching
- **Provider Presets** — 50+ provider templates from [cc-switch](https://github.com/farion1231/cc-switch)
- **Context Auto-Compact** — Automatically trims conversation history when approaching context window limits

## Main Workspace

The main workspace combines the project file tree, document preview, and agent chat timeline in one window. Users can inspect generated LaTeX/PDF output while continuing to interact with the agent team.

![AutoReport main workspace](https://raw.githubusercontent.com/xjsongphy/AutoReport/master/assets/screenshots/main-window.png)

## Quick Start

**Prerequisites:** Python >= 3.12, [uv](https://docs.astral.sh/uv/) package manager, TeX distribution, at least one LLM Provider API key.

Install from PyPI:

```bash
pip install autoreport-gui
autoreport
```

Or with `uv`:

```bash
uv pip install autoreport-gui
autoreport
```

Install from source:

```bash
git clone https://github.com/xjsongphy/AutoReport && cd AutoReport
uv sync
```

Run:

```bash
autoreport
```

The start window lets users open an existing experiment folder, create a new project, configure API providers, or resume a recent project.

![AutoReport start window](https://raw.githubusercontent.com/xjsongphy/AutoReport/master/assets/screenshots/start-window.png)

First launch prompts for API configuration. Pre-configure via environment variables:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export DEEPSEEK_API_KEY="sk-..."
autoreport
```

## MinerU Integration

AutoReport uses [mineru-open-api](https://github.com/opendatalab/MinerU) CLI for PDF parsing (PDF, images, DOCX, PPTX, XLSX → Markdown).

**Setup:**

1. Install mineru-open-api:
   ```bash
   curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh | sh
   ```
   See [mineru-open-api docs](https://mineru.net/ecosystem?tab=cli) for details.

2. Register at [MinerU](https://mineru.net/apiManage/token) for an API key, then authenticate:
   ```bash
   mineru-open-api auth
   ```

3. The app auto-detects availability on startup and shows a warning if not installed.

Supports batch processing (max 200MB / 600 pages per file), text/image/table/formula extraction.

## Configuration

Configuration file: `autoreport.config.yaml`

The API configuration dialog manages provider presets, active provider selection, API keys, base URLs, and default models.

![AutoReport API configuration](https://raw.githubusercontent.com/xjsongphy/AutoReport/master/assets/screenshots/configuration-window.png)

```yaml
agents:
  defaults:
    model: "anthropic/claude-sonnet-4.5"
    temperature: 0.1
    max_tool_iterations: 200
```

## Debug Mode

```bash
autoreport --debug-agent data_analysis
autoreport --debug-agent data_analysis --debug-agent plotting
```

Valid agents: `data_analysis`, `plotting`, `theory`, `report`

## Project Structure

```
my_experiment/
├── Data/            # Raw experimental data (user input) + analysis results
│   └── Processed/   # Data Analysis Agent output only
├── References/      # Reference materials (PDF, images), custom templates
├── Theory/          # Theory Agent output only
├── Plots/           # Plotting Agent plots and generated images
│   ├── Fig/         # Generated figures
│   └── Scripts/     # Plotting scripts
├── Outline/         # Main Agent report outline and routing notes
└── Tex/             # Report Agent LaTeX source and compiled output
```

### Agent Permissions

| Agent | Write Directory | Read Scope |
|-------|----------------|------------|
| Main Agent | `Outline/` | All directories |
| Data Analysis | `Data/Processed/` | All directories |
| Plotting | `Plots/` | All directories |
| Theory | `Theory/` | All directories |
| Report | `Tex/` | All directories |
| User | `Data/`, `References/` | All directories |

## Architecture

```
autoreport/
├── app.py                 # Entry point: CLI parsing, LoopManager startup
├── config/                # Pydantic-based config (YAML loading, API key validation)
├── core/
│   ├── loops/            # Agent runtime: LoopManager, AgentLoop, MessageBus
│   ├── providers/        # LLM provider abstraction (factory, base classes)
│   ├── prompts/          # Progressive prompt loading (identity → full instructions)
│   ├── tools/            # Tool system (registry, file tools, exec tools, PDF tool, skill tool)
│   ├── checkpoints.py    # Operation-log checkpoints with reversible file operations
│   ├── conversations.py  # Multi-session conversation store
│   ├── file_search.py    # Fuzzy file search for @ references
│   ├── preset_sync.py    # cc-switch preset synchronization
│   └── recent_projects.py# Recent projects cache
├── gui/                  # PyQt6 interface (main window, dialogs, widgets)
│   └── widgets/          # Reusable components (file tree, preview, agent panel)
├── interfaces/           # GUI-backend protocol (protocol definitions, message types)
├── resources/            # Built-in resources
├── templates/            # Built-in templates (agent prompts, report templates)
│   ├── agents/           # Agent prompt files (Markdown)
│   └── reports/          # LaTeX report templates
├── external/             # Git-ignored synced content (presets, skills)
│   ├── cc-switch/        # Provider presets from cc-switch repo
│   └── skills/           # Skill Markdown files
└── utils/                # Logging configuration (loguru)
```

## Development

```bash
# Run tests
uv run pytest -v

# Lint
uv run ruff check autoreport tests
uv run ruff check --fix autoreport tests

# Run with coverage
uv run pytest --cov=autoreport --cov-report=html
```

## UI Icons

Agent type icons are from [Tabler Icons](https://tabler-icons.io/) — 6000+ free SVG icons, MIT License.

## Reference Projects

- [DeepCode](https://github.com/HKUDS/DeepCode) — API config (YAML secrets + env fallback), multi-provider support, error handling
- [cc-switch](https://github.com/farion1231/cc-switch) — Provider presets (50+ providers)
- [nanobot](https://github.com/HKUDS/nanobot) — AgentLoop architecture, tool definitions, compact/command system
- [codex](https://github.com/openai/codex) — UI design patterns, streaming implementation
- [openclaw](https://github.com/openclaw/openclaw) — Personal AI assistant, skills system, multi-channel agent design
- [VS Code](https://github.com/microsoft/vscode) — Editor UI/UX patterns, panel layout, command and extension architecture
- [Claude Code](https://claude.com/claude-code) — Agent chat panel UI/UX (bubble messages, grouped tool calls, streaming, `@` references, slash commands)
- [PKUMpLtX](https://github.com/CastleStar14654/PKUMpLtX) — Built-in LaTeX report template (PKU Modern Physics Laboratory, revtex4-2 based)

## Star History

[![Star History Chart](https://api.star-history.com/chart?repos=xjsongphy/AutoReport&type=date&legend=top-left)](https://www.star-history.com/?repos=xjsongphy%2FAutoReport&type=date&legend=top-left)

## License

MIT License
