PyPI CLI Installation Guide - Using UV

This guide explains how to install and use Investor Paradise CLI from PyPI using uv (the fast Python package manager).

Prerequisites

Python 3.11 or higher
Google API Key (Get one here)

Step 1: Install UV

uv is a fast Python package installer and resolver written in Rust.

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative (using pip):

pip install uv

Verify installation:

uv --version

Step 2: Install Investor Paradise CLI

uv tool install investor-paradise-cli

This will:

Install the CLI tool globally along with all dependencies (including google-adk)

Step 3: Install Investor Paradise CLI

Method 1: Using `uv tool install` (Recommended - Simplest)

uv tool install investor-paradise-cli

This is the easiest method:

Installs the CLI globally in an isolated environment
Automatically adds to PATH (accessible from anywhere)
No need to activate virtual environments
Just run investor-paradise-cli from any directory

From GitHub (Latest Development):

uv tool install git+https://github.com/atulkumar2/investor_paradise.git

Method 2: Using `uv pip install` (Works Anywhere)

From PyPI (Stable Release):

uv pip install investor-paradise-cli

From GitHub (Latest Development):

uv pip install git+https://github.com/atulkumar2/investor_paradise.git

Method 3: Using `uv add` (For Project-Based Setup)

Note: This method requires you to be in a project directory with pyproject.toml.

First, create a project:

# Create a new directory for your analysis work
mkdir my-stock-analysis
cd my-stock-analysis

# Initialize a uv project
uv init

Then add the dependency:

# Add Investor Paradise CLI (includes google-adk)
uv add investor-paradise-cli

This automatically:

Installs the package in your project
Updates pyproject.toml with the dependency
Resolves and locks dependencies in uv.lock

Step 4: Add CLI to PATH (Optional - Only for Method 2)

Note: Skip this step if you used Method 1 (uv tool install) - it already adds to PATH automatically!

If you used uv pip install and want to run investor-paradise-cli from anywhere:

Manual PATH Setup

macOS/Linux (bash):

# Add to ~/.bashrc or ~/.bash_profile
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

macOS (zsh):

# Add to ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell):

# Add to PowerShell profile
$profilePath = $PROFILE
if (!(Test-Path -Path $profilePath)) {
    New-Item -ItemType File -Path $profilePath -Force
}
Add-Content -Path $profilePath -Value '$env:PATH += ";$env:USERPROFILE\.local\bin"'

Windows (Command Prompt):

Open System Properties → Environment Variables
Under User Variables, find Path
Click Edit → New
Add: %USERPROFILE%\.local\bin
Click OK to save

After adding to PATH, verify:

which investor-paradise-cli  # macOS/Linux
where investor-paradise-cli  # Windows

Step 5: Set Up Your API Key

The CLI needs a Google API key to function. You have multiple options:

Option 1: Let the CLI Prompt You (Recommended - Easiest)

Simply start the CLI without setting up the API key:

investor-paradise-cli

The CLI will:

Detect that no API key is configured
Prompt you to enter your Google API key
Securely store it in your system's credential manager:
- Windows: Windows Credential Manager
- macOS: Keychain
- Linux: Secret Service (gnome-keyring, kwallet, or similar)

You only need to do this once - the key will be remembered for future sessions.

Option 2: Environment Variable

macOS/Linux:

export GOOGLE_API_KEY="your_google_api_key_here"

Windows (PowerShell):

$env:GOOGLE_API_KEY="your_google_api_key_here"

Windows (Command Prompt):

set GOOGLE_API_KEY=your_google_api_key_here

Option 3: .env File

Create a .env file in your working directory:

echo "GOOGLE_API_KEY=your_google_api_key_here" > .env

Step 6: Run the CLI

If Using Method 1 (`uv tool install`)

Simply run from anywhere:

investor-paradise-cli

If Using Method 2 (`uv pip install`)

investor-paradise-cli

Or with uv:

uv run investor-paradise-cli

If Using Method 3 (Project setup with `uv add`)

From your project directory:

uv run investor-paradise-cli

First Run Experience

On the first launch, the CLI will:

Check API Key: Prompt for Google API key if not found
Check Data Files: Look for market data cache and news vector data
Download Data (if needed):
- NSE market data cache (2019-2025) - ~50MB, takes about 1 minute
- Economic Times news articles (last 6 months) - ~580MB download, ~1.2GB disk space after extraction, takes a few minutes
Load Data: Load the market data into memory (~10-20 seconds)
Ready! Start asking questions

Example First Run:

🚀 Initializing Investor Paradise...

📦 Checking if latest market data parquet cache and Economic Times news vector data is available...

⚠️  Starting download of latest NSE market data cache (2019-2025)
📊 This could take a minute (size ~50MB)

Downloading combined_data.parquet ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 50.9/50.9 MB
✅ All cache files downloaded successfully!

⚠️  Starting download of Economic Times news articles (last 6 months)
📰 This could take a few minutes (download ~580MB, disk space ~1.2GB after extraction)

Downloading 202506.zip ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Extracting 202506.zip...
✅ Extracted and cleaned up 202506.zip
...
✅ All vector data files downloaded and extracted successfully!

📂 Loading NSE stock data...
✅ Data loaded: 2,797,728 rows
📅 Database Context: 2019-10-01 to 2025-11-28

💬 Ready! Ask me about NSE stocks or just say hi!
Session: 3a7f8b2c... | Commands: 'exit', 'clear', 'switch'

💭 You:

Step 5: Start Using the CLI

Example Queries

💭 You: Show me top 5 performing stocks in the last month

💭 You: What are the latest news about Reliance Industries?

💭 You: Analyze TCS stock performance

💭 You: Compare HDFC Bank and ICICI Bank

💭 You: exit

CLI Commands

Session Management

switch - Change to a different session or create new one
clear - Clear current session history and start fresh
exit, quit, bye - Exit the application

Command-Line Flags

# Show help
uv run investor-paradise-cli --help

# Reset stored API key
uv run investor-paradise-cli --reset-api-key

# Refresh cache data
uv run investor-paradise-cli --refresh-cache

# Download vector data manually
uv run investor-paradise-cli --download-vector-data

Using UV Virtual Environments

For isolated project setup with full dependency management:

# Create a new project directory
mkdir my-stock-analysis
cd my-stock-analysis

# Initialize UV project
uv init

# Add Investor Paradise CLI (includes google-adk)
uv add investor-paradise-cli

# Run the CLI
uv run investor-paradise-cli

This approach:

Creates isolated environment per project
Manages dependencies in pyproject.toml
Locks versions in uv.lock for reproducibility
Best for development and team projects

Advanced Usage: Using as Python Library

# Create a script: analyze.py
import asyncio
from investor_agent.data_engine import NSESTORE

async def analyze_stock():
    # Load data
    df = NSESTORE.df
    print(f"Loaded {len(df):,} rows")
    
    # Get specific stock data
    stock_data = NSESTORE.get_stock_data("TCS", start_date="2024-01-01")
    print(stock_data.head())

asyncio.run(analyze_stock())

Run with uv:

uv run analyze.py

Data Storage Locations

By default, data is stored in:

<project-root>/
└── investor_agent/
    └── data/
        ├── cache/                          # Market data parquet files
        │   ├── combined_data.parquet
        │   ├── nse_indices_cache.parquet
        │   ├── nse_sector_cache.parquet
        │   └── nse_symbol_company_mapping.parquet
        ├── vector-data/                    # News articles by month
        │   ├── 202506/
        │   ├── 202507/
        │   ├── 202508/
        │   ├── 202509/
        │   ├── 202510/
        │   └── 202511/
        └── investor_agent_sessions.db      # Session history

Quick Start Summary

Simplest Installation (Recommended for Most Users)

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install Investor Paradise CLI globally (includes google-adk)
uv tool install investor-paradise-cli

# 3. Run the CLI from anywhere (it will prompt for API key on first run)
investor-paradise-cli

Alternative: Using uv pip install

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install Investor Paradise CLI (includes google-adk)
uv pip install investor-paradise-cli

# 3. Run the CLI
investor-paradise-cli

Project-Based Installation (For Development)

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Create and initialize project
mkdir my-stock-analysis && cd my-stock-analysis && uv init

# 3. Install Investor Paradise CLI (includes google-adk)
uv add investor-paradise-cli

# 4. Run the CLI
uv run investor-paradise-cli

That's it! The CLI will guide you through API key setup and data downloads on first run.

Troubleshooting

UV Installation Issues

Problem: uv: command not found

Solution:

# Reload your shell configuration
source ~/.bashrc  # or ~/.zshrc on macOS

# Or install via pip
pip install uv

Package Installation Issues

Problem: Installation fails with dependency conflicts

Solution:

# Use fresh virtual environment
uv venv --python 3.11
source .venv/bin/activate
uv pip install investor-paradise-cli

Problem: Google ADK not found

Solution:

# Reinstall the CLI to ensure all dependencies are installed
uv add investor-paradise-cli

API Key Not Found

Problem: "GOOGLE_API_KEY not found" error

Solution:

Run with --reset-api-key flag to re-enter your key
Or set environment variable before running

export GOOGLE_API_KEY="your_key_here"
uv run investor-paradise-cli

Data Download Issues

Problem: Download fails or times out

Solution:

# Retry with refresh flag
uv run investor-paradise-cli --refresh-cache

# For vector data specifically
uv run investor-paradise-cli --download-vector-data

Slow Performance

Problem: CLI is slow or unresponsive

Solutions:

First query is always slower (data loads into memory)
Ensure you have at least 2GB free RAM
Check internet connection for API calls
Use specific date ranges in queries for faster results

Updating the CLI

Check Current Version

uv pip show investor-paradise-cli

Update to Latest

uv pip install --upgrade investor-paradise-cli

Reinstall from Scratch

uv pip uninstall investor-paradise-cli
uv pip install investor-paradise-cli

System Requirements

Python: 3.11 or higher
RAM: Minimum 2GB free, Recommended 4GB
Disk Space:
- ~50MB for market data cache
- ~1.2GB for news vector data (6 months)
- Total: ~1.3GB
Network: Required for:
- Initial data download
- Google API calls during queries
- News fetching (optional)

Performance Tips

First launch takes longer: Data downloads and loads (~5-10 minutes first time)
Subsequent launches are fast: Data is cached locally
Keep sessions: Previous conversations are saved, use switch to resume
Clear when needed: Use clear command to reset context if confused
Specific queries: More specific = faster and better results

Data Coverage

Stocks: 2000+ NSE-listed companies
Date Range: October 2019 - November 2025
Data Points: OHLCV (Open, High, Low, Close, Volume)
News: Economic Times articles (last 6 months, embedded for RAG)
Updates: Manual refresh with --refresh-cache

Uninstallation

# Uninstall package
uv pip uninstall investor-paradise-cli

# Remove data (optional)
rm -rf investor_agent/data/

Quick Reference

# Simplest Installation (Recommended)
uv tool install investor-paradise-cli
investor-paradise-cli

# Alternative: Using uv pip
uv pip install investor-paradise-cli
investor-paradise-cli

# Project-Based Installation
mkdir my-stock-analysis && cd my-stock-analysis
uv init
uv add investor-paradise-cli
uv run investor-paradise-cli

# Commands within CLI
exit          # Exit application
clear         # Clear session history
switch        # Switch/create session

# Command-line flags
--help                    # Show help
--reset-api-key          # Reset API key
--refresh-cache          # Refresh market data
--download-vector-data   # Download news data

Support & Resources

GitHub: https://github.com/atulkumar2/investor_paradise
Issues: https://github.com/atulkumar2/investor_paradise/issues
PyPI: https://pypi.org/project/investor-paradise-cli/
UV Docs: https://docs.astral.sh/uv/

FilesExpand file tree

CLI_USAGE.md

Latest commit

History

CLI_USAGE.md

File metadata and controls

PyPI CLI Installation Guide - Using UV

Prerequisites

Step 1: Install UV

Step 2: Install Investor Paradise CLI

Step 3: Install Investor Paradise CLI

Method 1: Using uv tool install (Recommended - Simplest)

Method 2: Using uv pip install (Works Anywhere)

Method 3: Using uv add (For Project-Based Setup)

Step 4: Add CLI to PATH (Optional - Only for Method 2)

Manual PATH Setup

Step 5: Set Up Your API Key

Option 1: Let the CLI Prompt You (Recommended - Easiest)

Option 2: Environment Variable

Option 3: .env File

Step 6: Run the CLI

If Using Method 1 (uv tool install)

If Using Method 2 (uv pip install)

If Using Method 3 (Project setup with uv add)

First Run Experience

Step 5: Start Using the CLI

Example Queries

CLI Commands

Session Management

Command-Line Flags

Using UV Virtual Environments

Advanced Usage: Using as Python Library

Data Storage Locations

Quick Start Summary

Simplest Installation (Recommended for Most Users)

Alternative: Using uv pip install

Project-Based Installation (For Development)

Troubleshooting

UV Installation Issues

Package Installation Issues

API Key Not Found

Data Download Issues

Slow Performance

Updating the CLI

Check Current Version

Update to Latest

Reinstall from Scratch

System Requirements

Performance Tips

Data Coverage

Uninstallation

Quick Reference

Support & Resources

Method 1: Using `uv tool install` (Recommended - Simplest)

Method 2: Using `uv pip install` (Works Anywhere)

Method 3: Using `uv add` (For Project-Based Setup)

If Using Method 1 (`uv tool install`)

If Using Method 2 (`uv pip install`)

If Using Method 3 (Project setup with `uv add`)