did some stuff... maybe better for a second branch?

.gitignore

@@ -1,2 +1,55 @@
-ppl-ai-venv
-cURL.sh
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+.venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Project output
+orchestrator-output/
+temp/
+*.log
+
+# Browser profiles
+.perplexity-cli/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/

README.md

@@ -1,13 +1,170 @@
-# Perplexity.ai-CLI
+# Perplexity AI CLI
 
-> All merits to [Helpingai](https://github.com/HelpingAI/Helpingai_T2).
-
-This is a simple script that lets you interact with [perplexity.ai](https://www.perplexity.ai/) from the command line.
+Browser automation bridge to Perplexity AI with CLI, HTTP API, and Task Orchestration.
 
 <div align="center"> <img src="ppl-ai.gif" width=500> </div>
 
-USAGE:
-1. You can easily use the installation script to use it as a binary file.
-2. To send a question you need to press [Ctrl-d] on a blank line (great for pasting multiple lines)
-3. Perplexity has the great feature of returning references, you can get them by sending `$refs`
-4. [Ctrl-c] to quit (also exits the python-venv).
+## Features
+
+- 🌐 **Browser Automation** - Automates the Perplexity web UI via Playwright
+- 💬 **CLI Interface** - Ask questions directly from the terminal
+- 🔌 **HTTP API** - RESTful API for integration with other projects
+- 🤖 **Task Orchestrator** - Multi-step task execution with sub-task decomposition
+- 🔄 **Model Selection** - Choose from GPT, Claude, Gemini, Grok, and more
+- 🔬 **Research Mode** - Deep, multi-step research capabilities
+- 🧪 **Labs Mode** - Access experimental features
+
+## Installation
+
+### From GitHub (recommended for development)
+
+```bash
+# Clone the repository
+git clone https://github.com/Cfomodz/perplexity.ai-cli.git
+cd perplexity.ai-cli
+
+# Install as editable package
+pip install -e .
+
+# Install Playwright browsers
+playwright install chromium
+```
+
+### As a dependency in other projects
+
+```bash
+# In your project's requirements.txt or pip install:
+pip install git+https://github.com/Cfomodz/perplexity.ai-cli.git
+```
+
+## Prerequisites
+
+1. **Perplexity Pro Account** - Required for model selection and advanced features
+2. **Browser with CDP** (recommended) - For using your existing logged-in session:
+   ```bash
+   brave --remote-debugging-port=9222
+   # or
+   google-chrome --remote-debugging-port=9222
+   ```
+
+## Quick Start
+
+### First-time Login
+
+```bash
+# Login and save session (one-time setup)
+perplexity-ai --login
+# or
+ppl --login
+```
+
+### CLI Usage
+
+```bash
+# Ask a question
+ppl "What is quantum computing?"
+
+# Use a specific model
+ppl --model claude "Explain relativity"
+
+# Research mode (deep, multi-step)
+ppl --research "History of quantum computing"
+
+# Labs mode (experimental features)
+ppl --labs "Build me a chart"
+
+# Interactive mode
+ppl -i
+
+# Connect to existing browser (uses your logged-in session)
+ppl --cdp "Your question"
+```
+
+### HTTP API
+
+```bash
+# Start the API server
+ppl --serve
+
+# Query via HTTP
+curl "http://localhost:8000/ask?q=What+is+AI"
+curl "http://localhost:8000/ask?q=Topic&model=claude"
+curl "http://localhost:8000/ask?q=Deep+topic&research=true"
+```
+
+### Task Orchestrator
+
+```bash
+# Run orchestrated multi-step task
+ppl --orchestrate "Create a business plan for a SaaS startup"
+
+# List previous runs
+ppl --orchestrate-list
+
+# Resume a previous run
+ppl --orchestrate-resume path/to/state.json
+```
+
+## Programmatic Usage
+
+```python
+import asyncio
+from perplexity_ai_cli import PerplexityBrowser, TaskOrchestrator, AVAILABLE_MODELS
+
+async def main():
+    # Simple query
+    async with PerplexityBrowser(cdp_url="http://localhost:9222") as browser:
+        response = await browser.ask(
+            "What is quantum computing?",
+            model="claude",
+            research_mode=False,
+        )
+        print(response.answer)
+        print(response.references)
+
+    # Task orchestration
+    async with PerplexityBrowser() as browser:
+        orchestrator = TaskOrchestrator(
+            goal="Create a marketing plan",
+            browser=browser,
+            auto_confirm=True,
+        )
+        await orchestrator.run_async()
+
+asyncio.run(main())
+```
+
+## Available Models
+
+| Key | Model |
+|-----|-------|
+| `auto` / `best` | Best (auto-select) |
+| `sonar` | Sonar |
+| `gpt` / `gpt-5` | GPT-5.1 |
+| `o3-pro` | o3-pro |
+| `claude` / `claude-sonnet` | Claude Sonnet 4.5 |
+| `claude-opus` | Claude Opus 4.5 |
+| `gemini` / `gemini-pro` | Gemini 3 Pro |
+| `grok` | Grok 4.1 |
+| `kimi` | Kimi K2 Thinking |
+
+## Project Structure
+
+```
+perplexity.ai-cli/
+├── perplexity_ai_cli/          # Python package
+│   ├── __init__.py             # Package exports
+│   └── core.py                 # Main implementation
+├── perplexity.ai-cli.py        # Standalone script (legacy)
+├── examples/                   # Usage examples
+├── pyproject.toml              # Package configuration
+└── requirements.txt            # Dependencies
+```
+
+## License
+
+MIT License
+
+## Credits
+
+Originally inspired by [Helpingai](https://github.com/HelpingAI/Helpingai_T2).

examples/basic-examples.sh

@@ -0,0 +1,148 @@
+#!/bin/bash
+#
+# Basic Examples - Quick reference for common CLI usage patterns
+#
+
+CLI="../perplexity.ai-cli.py"
+PYTHON="../.venv/bin/python"
+
+echo "═══════════════════════════════════════════════════════════════"
+echo "  Perplexity CLI - Basic Usage Examples"
+echo "═══════════════════════════════════════════════════════════════"
+echo ""
+
+# ─────────────────────────────────────────────────────────────────
+# Example 1: Simple query
+# ─────────────────────────────────────────────────────────────────
+example_simple() {
+    echo "Example 1: Simple Query"
+    echo "─────────────────────────────────────────────────────────────"
+    $PYTHON $CLI --no-typing "What is the capital of France?"
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Example 2: Research mode for deep analysis
+# ─────────────────────────────────────────────────────────────────
+example_research() {
+    echo "Example 2: Research Mode (Deep Analysis)"
+    echo "─────────────────────────────────────────────────────────────"
+    $PYTHON $CLI --no-typing --research "Explain the current state of quantum computing"
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Example 3: Labs mode for creative tasks
+# ─────────────────────────────────────────────────────────────────
+example_labs() {
+    echo "Example 3: Labs Mode (Creative/Visual)"
+    echo "─────────────────────────────────────────────────────────────"
+    $PYTHON $CLI --no-typing --labs "Create a comparison table of major cloud providers"
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Example 4: Specific model selection
+# ─────────────────────────────────────────────────────────────────
+example_models() {
+    echo "Example 4: Model Selection"
+    echo "─────────────────────────────────────────────────────────────"
+
+    echo ""
+    echo "Using Claude:"
+    $PYTHON $CLI --no-typing -m claude "Write a haiku about programming"
+
+    echo ""
+    echo "Using GPT:"
+    $PYTHON $CLI --no-typing -m gpt "Explain recursion simply"
+
+    echo ""
+    echo "Using Grok:"
+    $PYTHON $CLI --no-typing -m grok "What's a hot take on cryptocurrency?"
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Example 5: Focus modes
+# ─────────────────────────────────────────────────────────────────
+example_focus() {
+    echo "Example 5: Focus Modes"
+    echo "─────────────────────────────────────────────────────────────"
+
+    echo ""
+    echo "Academic focus:"
+    $PYTHON $CLI --no-typing -f academic "Recent papers on transformer architectures"
+
+    echo ""
+    echo "Reddit focus:"
+    $PYTHON $CLI --no-typing -f reddit "Best mechanical keyboards for programming"
+
+    echo ""
+    echo "YouTube focus:"
+    $PYTHON $CLI --no-typing -f youtube "Best tutorials for learning Rust"
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Example 6: Combining options
+# ─────────────────────────────────────────────────────────────────
+example_combined() {
+    echo "Example 6: Combined Options"
+    echo "─────────────────────────────────────────────────────────────"
+
+    echo ""
+    echo "Research mode + Claude + Academic focus:"
+    $PYTHON $CLI --no-typing --research -m claude -f academic \
+        "Latest breakthroughs in CRISPR gene editing"
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Example 7: Piping output
+# ─────────────────────────────────────────────────────────────────
+example_piping() {
+    echo "Example 7: Piping Output to Files"
+    echo "─────────────────────────────────────────────────────────────"
+
+    $PYTHON $CLI --no-typing "List 5 interesting facts about space" > space_facts.txt
+    echo "Output saved to space_facts.txt"
+    cat space_facts.txt
+    rm space_facts.txt
+}
+
+# ─────────────────────────────────────────────────────────────────
+# Run selected example or show menu
+# ─────────────────────────────────────────────────────────────────
+if [ -n "$1" ]; then
+    case "$1" in
+        1|simple) example_simple ;;
+        2|research) example_research ;;
+        3|labs) example_labs ;;
+        4|models) example_models ;;
+        5|focus) example_focus ;;
+        6|combined) example_combined ;;
+        7|piping) example_piping ;;
+        all)
+            example_simple
+            echo ""; example_research
+            echo ""; example_labs
+            echo ""; example_models
+            echo ""; example_focus
+            echo ""; example_combined
+            echo ""; example_piping
+            ;;
+        *)
+            echo "Unknown example: $1"
+            echo "Usage: $0 [1-7|all]"
+            ;;
+    esac
+else
+    echo "Usage: $0 [example_number]"
+    echo ""
+    echo "Available examples:"
+    echo "  1, simple    - Basic query"
+    echo "  2, research  - Research mode"
+    echo "  3, labs      - Labs mode"
+    echo "  4, models    - Model selection"
+    echo "  5, focus     - Focus modes"
+    echo "  6, combined  - Combined options"
+    echo "  7, piping    - Output to files"
+    echo "  all          - Run all examples"
+    echo ""
+    echo "Example: $0 2"
+fi
+