Metadata-Version: 2.1
Name: pplx-research
Version: 1.0.2
Summary: Monolithic research CLI powered by Perplexity Sonar API with auto-classification and iterative gap analysis
Author-email: kleinpanic <kleinpanic@users.noreply.github.com>
Project-URL: Homepage, https://github.com/kleinpanic/pplx-research
Project-URL: Documentation, https://github.com/kleinpanic/pplx-research#readme
Project-URL: Repository, https://github.com/kleinpanic/pplx-research.git
Project-URL: Issues, https://github.com/kleinpanic/pplx-research/issues
Keywords: perplexity,research,cli,ai,sonar,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# PPLX Research

A monolithic, versatile research CLI powered by Perplexity's Sonar API. Features auto-classification, iterative gap analysis, multi-perspective synthesis, and comprehensive output formats.

[![CI](https://github.com/kleinpanic/pplx-research/actions/workflows/ci.yml/badge.svg)](https://github.com/kleinpanic/pplx-research/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pplx-research?color=blue&label=PyPI)](https://pypi.org/project/pplx-research/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Why This Exists

Other Perplexity wrappers are simple API clients. **PPLX Research is a research orchestration layer** that adds:

- **Auto-classification**: Analyzes your query and picks the optimal mode/depth/sources
- **Gap analysis**: Iteratively identifies and fills knowledge gaps (deep mode)
- **Multi-perspective synthesis**: Gathers insights from academic, news, forums, docs, and code sources
- **Full API coverage**: All Perplexity features including `search_domain_filter`, `reasoning_effort`, `return_images`, etc.

## Installation

```bash
pip install pplx-research
```

## Quick Start

```bash
# Set your API key
export PERPLEXITY_API_KEY="pplx-..."

# Basic research
pplx-research "what is quantum computing"

# Let AI pick the best approach
pplx-research "React vs Vue performance" --auto

# Deep academic research
pplx-research "transformer architecture" --mode deep --sources academic --depth 4

# Multi-perspective analysis
pplx-research "microservices pros and cons" --mode synthesis
```

## Modes

| Mode | Description | Best For |
|------|-------------|----------|
| `quick` | Single query, fast response | Facts, definitions, current events |
| `deep` | Iterative gap analysis | Complex topics, research reports |
| `synthesis` | Multi-source perspectives | Comparisons, debates, pros/cons |

## Options

```
pplx-research <query> [options]

Modes:
  -m, --mode {quick,deep,synthesis}  Research mode (default: quick)

Scope:
  -s, --site DOMAIN         Constrain to specific domain
  -e, --exclude DOMAIN      Exclude domain (can use multiple times)
  -t, --time-range {hour,day,week,month,year}
  -r, --region CODE        Country/region code (US, UK, JP)
  --sources TYPES          academic,news,docs,forums,code,all

Output:
  -f, --format {markdown,json,summary,plain}
  -d, --depth 1-5          Iteration depth (default: 3)

Automation:
  -a, --auto               Auto-classify query
  -o, --output PATH        Save to file
  -q, --quiet              Suppress progress
```

## Python API

```python
from pplx_research import ResearchEngine, PerplexitySDK

# High-level research
engine = ResearchEngine(query="quantum computing", mode="deep", sources=["academic"])
report = engine.run()

# Low-level SDK
sdk = PerplexitySDK()
result = sdk.chat("Hello", model="sonar-pro")
```

## License

MIT License - see [LICENSE](LICENSE) for details.
