Metadata-Version: 2.3
Name: deepdiver-cli
Version: 0.2.3
Summary: SWEDeepDiver is an automated analysis agent for Software Engineering (SWE) problems.
Keywords: software-engineering,debugging,analysis,agent,react,llm
Author: Steve Yang
Author-email: Steve Yang <steve.yang92@gmail.com>
License: MIT License
         
         Copyright (c) 2025 SteveYang92
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: openai>=1.40.0
Requires-Dist: pydantic~=2.7
Requires-Dist: httpx~=0.27
Requires-Dist: tenacity~=8.2
Requires-Dist: structlog~=24.0
Requires-Dist: typer==0.21.0
Requires-Dist: pycryptodome==3.22.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
Requires-Dist: black>=24.0.0 ; extra == 'dev'
Requires-Dist: isort>=5.13.0 ; extra == 'dev'
Requires-Dist: flake8>=7.0.0 ; extra == 'dev'
Requires-Dist: mypy>=1.8.0 ; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0 ; extra == 'dev'
Maintainer: Steve Yang
Maintainer-email: Steve Yang <steve.yang92@gmail.com>
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/SteveYang92/SWEDeepDiver
Project-URL: Documentation, https://github.com/SteveYang92/SWEDeepDiver#readme
Project-URL: Repository, https://github.com/SteveYang92/SWEDeepDiver.git
Project-URL: Issues, https://github.com/SteveYang92/SWEDeepDiver/issues
Project-URL: Changelog, https://github.com/SteveYang92/SWEDeepDiver/releases
Provides-Extra: dev
Description-Content-Type: text/markdown

# SWEDeepDiver

SWEDeepDiver is an automated analysis agent for **Software Engineering (SWE) problems**, designed to perform deep diagnosis and root cause analysis for multi-technology stack issues including Android, iOS, Backend, and Frontend.

It simulates experienced engineers' troubleshooting habits: from whole to part, from symptoms to root causes, comprehensively utilizing logs, exception traces, various issue files, source code, and knowledge bases to build "timeline + evidence chains", ultimately providing structured, verifiable diagnostic conclusions.

[![PyPI version](https://badge.fury.io/py/deepdiver-cli.svg)](https://badge.fury.io/py/deepdiver-cli)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

## ✨ Features

### Core Capabilities
- **🤖 Automated Problem Diagnosis**: Simulates experienced engineers' troubleshooting approach using ReAct (Reasoning + Acting) architecture
- **🔍 Multi-source Evidence Analysis**: Correlates logs, exception traces, issue files, source code, and knowledge bases
- **📊 Structured Reasoning**: Builds verifiable "timeline + evidence chain" for root cause analysis
- **🎯 Multi-technology Stack**: Supports Android, iOS, backend (Java, Python, Node.js, etc.), and frontend
- **💾 Zero-intrusion Design**: All state saved in `~/.deepdiver/`, no files written to user projects
- **🔑 Session Management**: Independent sessions, fully traceable and reproducible
- **🔌 Plugin System**: Custom desensitization, decryption, and filtering strategies
- **📚 Knowledge Base Integration**: Domain-specific knowledge injection for better accuracy
- **🌐 Multi-LLM Support**: DeepSeek, Moonshot, Alibaba Tongyi, OpenRouter, and more

### 🎉 New in v0.2.0

#### Modern UI & Real-time Feedback
- **🖥️ Rich Terminal UI**: Beautiful, informative terminal interface powered by Rich library
- **📊 Real-time Progress Tracking**: Watch the agent think, explore, and analyze in real-time
- **💡 Key Finding Highlights**: Important discoveries are highlighted as they happen
- **🎛️ Dual Display Modes**:
  - **Concise Mode**: Clean output with just the essentials
  - **Verbose Mode**: Detailed thinking process and tool outputs
  - Press `v` during runtime to toggle between modes
- **🛠️ Smart Tool Display**: Tool calls show only key parameters for clarity

#### Enhanced Reporting
- **📄 Interactive HTML Reports**: Professional reports with collapsible sections and mobile-responsive design
- **📑 Structured Output Formats**: JSON for machine processing, Markdown for documentation, HTML for presentation
- **📈 Enhanced Metadata**: Includes commit counts, review results, and confidence scores

#### Improved Analysis Tools
- **⏱️ Time-Range Filtering**: Filter logs by time windows for focused analysis
- **🔎 Better Grep Results**: Shows total/returned line counts with truncation warnings
- **📖 Enhanced Read Tool**: File size and line count information for better context
- **🧪 Improved Review Process**: Better separation between LLM summaries and user-facing details

## Installation

### Using uv (Recommended)

[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver written in Rust. It's the recommended way to install SWEDeepDiver:

```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install SWEDeepDiver using uv tool
uv tool install deepdiver-cli
```

### Using pip (Alternative)

```bash
pip install deepdiver-cli
```

### Additional Requirements

SWEDeepDiver requires `ripgrep` for efficient file searching:

```bash
# On macOS
brew install ripgrep

# On Ubuntu/Debian
sudo apt-get install ripgrep

# Other platforms: refer to ripgrep installation guide
```

For code analysis functionality, Claude Code CLI is optional:
```bash
npm install -g @anthropic-ai/claude-code
```

## Quick Start

### Basic Usage

```bash
# Analyze issue with code directory (current directory as code)
cd /path/to/your/code
deepdiver -c --attachment_path /path/to/issue/attachments --issue "Application crashes on startup"

# Analyze issue from attachment directory
cd /path/to/issue/attachments
deepdiver --code_path /path/to/your/code --issue "Performance degradation in payment service"

# Analyze attachments only (no code)
cd /path/to/issue/attachments
deepdiver --issue "Database connection timeout errors"
```

### UI Interaction

During analysis, SWEDeepDiver provides real-time feedback:

```
Step 1: Thinking...
💡 Key Finding: Exception trace indicates database connection timeout

Step 1: Grep(/var/log/app.log, "Connection timeout")
⎿ Grep found 15 result(s)

Step 2: Inspect(/var/log/app.log)
⎿ Inspected /var/log/app.log

[Press 'v' to toggle verbose/concise mode]
```

**Press `v` anytime during analysis to toggle between:**
- **Concise Mode** (default): Clean output with tool summaries
- **Verbose Mode**: Full thinking process and detailed tool outputs

### Parameter Reference

- `-c`, `--code`: Declare current working directory as code directory
- `--code-path <PATH>`: Additional code directories (multiple allowed)
- `--attachment-path <PATH>`: Attachment directories (multiple allowed)
- `--issue "<TEXT>"`: Problem description in natural language
- `--verbose`: Start in verbose mode (show detailed thinking and tool outputs)
- `--list-sessions`: List historical diagnosis sessions
- `--show-report <session_id>`: Show diagnostic report for specific session

## Configuration

### Agent Configuration

Configuration files are automatically created on first run. The first time you run DeepDiver, it will automatically generate configuration files from templates:

```bash
# Configuration files are auto-created in ~/.deepdiver/config/
# - config.toml: Main configuration (LLM providers, API keys, model settings)
# - knowledge_config.toml: Knowledge base configuration (optional)
```

To manually configure or update settings:

```bash
# Edit the main configuration
# Configure LLM providers, API keys, model settings, etc.
vim ~/.deepdiver/config/config.toml
```

### Plugin Development

Implement custom plugins for data processing:

```python
# Example: Custom data masking
from deepdiver_cli.plugins.datamask import DataMasker

class MyDataMasker(DataMasker):
    def mask(self, raw: str) -> str:
        # Implement your data masking logic
        return masked
```

The plugin system automatically discovers and loads classes implementing Protocol interfaces.

## Usage Example

Analyzing an Android ANR issue:

```bash
deepdiver -c --attachment_path examples/android/anr --issue "Application experiences ANR, please analyze the cause"
```

SWEDeepDiver will:
1. Parse problem description and attachments
2. Identify problem type and evidence sources
3. Call analysis tools (Glob, ProcessFile, Grep, Inspect, AnalyzeCode, etc.)
4. Build timeline and evidence chains
5. Generate structured diagnostic report (Markdown + JSON + HTML)
6. Save all results in `~/.deepdiver/sessions/<session_id>/`

**Report Output**:
- `summary.md`: Executive summary with core conclusions and timeline
- `report.json`: Complete structured data for further processing
- `report.html`: Interactive HTML report with collapsible sections
- `diagnosis_*.md`: Detailed diagnosis files with evidence chains

## Output Example

```markdown
**Conclusion**: ANR root cause is `HeavyService.performHeavyOperation` calling `Thread.sleep` in main thread.

**Confidence**: High

**Evidence Strength**: High

**Core Evidence**:
1. **Log/Trace Evidence**:
   - `03:34:05.428` MainActivity: "Performing heavy database operation"
   - `03:34:11.428` ActivityManager reports ANR for service `com.example.testapp/.HeavyService`
   - ANR Trace shows main thread Sleeping at `Thread.sleep`, called by `HeavyService.performHeavyOperation`

**Timeline**:
| Time           | Event                                       | Source              |
|----------------|---------------------------------------------|---------------------|
| 03:34:05.428   | Heavy operation starts                      | MainActivity log    |
| 03:34:11.428   | ANR reported                                | ActivityManager log |
| 03:34:11       | Main thread blocked in sleep                | ANR Trace           |
```

## Project Structure

```
SWEDeepDiver/
├── src/deepdiver_cli/          # Source code
│   ├── react_core/             # ReAct core engine (agent, llm, tool)
│   ├── tools/                  # Analysis tools (grep, glob, read, inspect, etc.)
│   ├── events/                 # Event-driven architecture (NEW)
│   ├── ui/                     # UI rendering system (NEW)
│   ├── app/                    # Application logic
│   ├── chat/                   # Chat models and providers
│   ├── plugins/                # Plugin interfaces (datamask, decryptor, filter)
│   ├── templates/              # Report templates (HTML, Markdown)
│   ├── config.py              # Configuration management
│   └── cli.py                 # CLI entry point
├── examples/                   # Example issues
├── config/                     # Configuration templates
├── knowledge/                  # Knowledge base directory
├── pyproject.toml             # Python project configuration
├── README.md                  # This file
└── CLAUDE.md                  # Development guide
```

## Technology Stack

- **Python 3.12+** - Primary language
- **Typer** - Modern CLI framework
- **Pydantic** - Data validation and settings management
- **Rich** - Terminal UI and formatting
- **OpenAI** - LLM API client
- **HTTPX** - Async HTTP client
- **Tenacity** - Retry library with exponential backoff
- **Structlog** - Structured logging
- **ReAct Pattern** - Reasoning + Acting architecture for agent decision-making
- **Event-Driven Architecture** - Decoupled UI and business logic (NEW)
- **ripgrep** - Fast text search for log analysis

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

### Development Setup

```bash
git clone https://github.com/SteveYang92/SWEDeepDiver.git
cd SWEDeepDiver
uv venv --python 3.12
source .venv/bin/activate  # Unix/macOS
uv pip install -e ".[dev]"
uv run pytest tests/ -v
```

## License

MIT License - see [LICENSE](LICENSE) file.

## Disclaimer

### Security & Privacy
- SWEDeepDiver is designed for local/self-hosted use
- Logs, traces, and source code may contain sensitive information
- Implement proper data masking/decryption plugins for your security requirements
- API keys and configurations should be kept secure

### Diagnostic Limitations
- Results depend on available data, knowledge bases, and LLM capabilities
- Not guaranteed to be completely accurate in all scenarios
- Use as an auxiliary analysis tool, not the sole basis for decisions

### Usage Responsibility
- Provided "as-is" without warranties
- Test thoroughly in controlled environments before production use

## Acknowledgments

- Configuration system references [OpenManus](https://github.com/FoundationAgents/OpenManus)
- Prompt and tool design references [ClaudeCode](https://github.com/anthropics/claude-code)

---

*For Chinese documentation, see [README_CN.md](README_CN.md)*