Installation

Prerequisites

Install Homebrew (if not already installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Python 3.9+ via Homebrew:

brew install python

Verify Python installation:

python3 --version  # Should show 3.9 or higher

Install git:

brew install git

Project Setup

Clone or create project:

# If starting fresh:
mkdir ~/Documents/pynions
cd ~/Documents/pynions
 
# If cloning:
git clone https://github.com/yourusername/pynions.git
cd pynions

Create virtual environment:

# Create venv
python3 -m venv venv
 
# Activate it
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Install Playwright browsers:

playwright install

Configuration

Set up environment variables:

# Copy example files
cp .env.example .env
cp config.example.json config.json

Edit .env file:

# Open in your preferred editor
nano .env
 
# Add your API keys:
SERPER_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
JINA_API_KEY=your_key_here

Verify Installation

Run test workflow:

# Make sure venv is activated
source venv/bin/activate
 
# Run example
python examples/serp_analysis.py

Check the output:

Should see progress messages
Results saved in data/ directory
No error messages

IDE Setup (Cursor)

Download Cursor:
- Visit https://cursor.sh
- Download Mac version
- Install application
Open project:
- Open Cursor
- File -> Open Folder
- Select ~/Documents/pynions
Configure Python interpreter:
- Click Python version in status bar
- Select interpreter from virtual environment: ~/Documents/pynions/venv/bin/python

Common Issues

Python Version Issues

# Check Python version
python --version
 
# If needed, specify Python 3 explicitly
python3 --version

Virtual Environment Issues

# Deactivate if already in a venv
deactivate
 
# Remove existing venv if needed
rm -rf venv
 
# Create new venv
python3 -m venv venv
 
# Activate
source venv/bin/activate

Permission Issues

# Fix venv permissions
chmod +x venv/bin/activate
chmod +x venv/bin/python
 
# Fix data directory permissions
chmod 755 data

Module Not Found Issues

# Verify installation
pip list
 
# Reinstall dependencies
pip install -r requirements.txt

Next Steps

Read 03-configuration.md for detailed API setup
Try example workflows in examples/
Check 04-plugins.md for plugin usage
See 05-workflows.md for creating custom workflows

Development Tools

Optional but recommended tools:

HTTPie for API testing:

brew install httpie

jq for JSON processing:

brew install jq

Visual Studio Code extensions:
- Python
- Python Environment Manager
- Git Lens
- Docker (if using containers)

Updating

To update dependencies:

pip install --upgrade -r requirements.txt

To update Playwright:

playwright install