Cogniscor/SETUP_GUIDE.md

Cogniscor - Setup Guide

🚀 Quick Start (First Time Users)

Step 1: Run Setup Wizard

./cogniscor.sh --setup

The interactive wizard will:

1. Create your configuration file at ~/.cogniscor/config.properties
2. Prompt for your OpenAI API key (optional)
3. Configure AI features
4. Set output directory and logging preferences

Step 2: Use Cogniscor

./cogniscor.sh "Company Name" "https://company.com"

That's it! 🎉

📋 What the Setup Wizard Does

1. Creates Configuration Directory

The wizard creates ~/.cogniscor/ in your home directory containing:

• config.properties - Your personal configuration file

2. Prompts for OpenAI API Key

You'll be asked:

Do you have an OpenAI API key? (yes/no) [no]:

If you have one:

• Paste your API key (starts with sk-)
• Choose your preferred model (gpt-4o-mini recommended)
• Enable/disable AI features

If you don't:

• No problem! The tool works great without AI
• You can add it later by running --setup again

3. Configures AI Features

If you enable AI, you can choose:

• ✅ AI-enhanced extraction - Fills gaps in data extraction
• ✅ AI report review - Polishes and improves reports
• ❌ Source planning (future feature)

4. Sets Other Preferences

• Output directory (default: ./data)
• Logging level (INFO or DEBUG)

📁 Configuration File Location

Your configuration is stored at:

~/.cogniscor/config.properties

Benefits:

• ✅ Works from any directory
• ✅ Shared across all projects
• ✅ Easy to back up and restore
• ✅ Secure (in your home directory)

🔧 Manual Configuration

You can also edit the config file directly:

# Open in your favorite editor
nano ~/.cogniscor/config.properties

# Or
vim ~/.cogniscor/config.properties

Example Configuration

# HTTP Settings
http.timeout.seconds=30
rate.limit.delay.ms=2000

# OpenAI Configuration (Optional)
openai.api.key=sk-your-key-here
openai.model=gpt-4o-mini
llm.enabled=true
llm.enhance.extraction=true
llm.review.reports=true

# Output
output.base.dir=./data
log.level=INFO

🔑 Getting an OpenAI API Key

Step 1: Create OpenAI Account

1. Go to https://platform.openai.com/signup
2. Sign up with email or Google/Microsoft account
3. Verify your email

Step 2: Add Payment Method

1. Go to https://platform.openai.com/account/billing
2. Add a payment method (credit card)
3. Add credits ($5 minimum)

Step 3: Create API Key

1. Go to https://platform.openai.com/api-keys
2. Click "Create new secret key"
3. Give it a name (e.g., "Cogniscor")
4. Copy the key (starts with sk-)
5. Save it securely!

Note: You'll only see the key once. If you lose it, create a new one.

Step 4: Run Setup

./cogniscor.sh --setup

Paste your API key when prompted.

💰 Cost Expectations

With gpt-4o-mini (recommended):

• Per company: ~$0.025
• 10 companies: ~$0.25
• 100 companies: ~$2.50
• 1,000 companies: ~$25

With gpt-4o (more capable):

• Per company: ~$0.15
• 10 companies: ~$1.50
• 100 companies: ~$15

Free tier: 3 requests/minute • Upgrade for higher limits

⚙️ Re-running Setup

You can run setup again anytime:

./cogniscor.sh --setup

This will:

• ✅ Overwrite your existing configuration
• ✅ Let you update your API key
• ✅ Change AI feature settings
• ✅ Modify output directory

🔍 Checking Your Configuration

View Current Config

cat ~/.cogniscor/config.properties

Check if Config Exists

ls -la ~/.cogniscor/

Test Configuration

./cogniscor.sh "Test Company" "https://example.com"

🚨 Troubleshooting

"Configuration Required" Error

Problem: Running without setup

⚠ CONFIGURATION REQUIRED ⚠

Solution:

./cogniscor.sh --setup

API Key Not Working

Check:

1. Key starts with sk-
2. No extra spaces
3. Key is valid at https://platform.openai.com/api-keys
4. You have available credits

Fix:

./cogniscor.sh --setup  # Re-enter your key

Wrong Model Selected

Change model:

# Edit config file
nano ~/.cogniscor/config.properties

# Change this line:
openai.model=gpt-4o-mini

Or re-run setup:

./cogniscor.sh --setup

Want to Disable AI

Option 1: Set in config

nano ~/.cogniscor/config.properties
# Change to:
llm.enabled=false

Option 2: Remove API key

nano ~/.cogniscor/config.properties
# Change to:
openai.api.key=

Config File Corrupted

Delete and recreate:

rm -rf ~/.cogniscor/
./cogniscor.sh --setup

📝 Configuration Options Reference

HTTP Settings

http.timeout.seconds=30          # Request timeout
http.user.agent=Mozilla/5.0...   # User agent string
http.max.redirects=5             # Max HTTP redirects

Rate Limiting

rate.limit.delay.ms=2000         # Delay between requests
rate.limit.enabled=true          # Enable rate limiting

Scraping

scraper.max.retries=3            # Retry attempts
scraper.retry.delay.ms=5000      # Delay between retries

OpenAI / LLM

openai.api.key=sk-...            # Your API key
openai.model=gpt-4o-mini         # Model name
openai.max.tokens=4000           # Max response length
openai.temperature=0.3           # Creativity (0.0-1.0)

LLM Features

llm.enabled=true                 # Master switch
llm.enhance.extraction=true      # Enhance extraction
llm.review.reports=true          # Review reports
llm.plan.sources=false           # Future feature

Output & Logging

output.base.dir=./data           # Output directory
log.level=INFO                   # Logging level
analyzer.max.summary.words=500   # Summary length

🔒 Security Best Practices

Keep API Keys Secure

• ✅ Never commit config.properties to git
• ✅ Don't share your API key
• ✅ Use separate keys for different projects
• ✅ Revoke keys you're not using

File Permissions

# Secure your config file
chmod 600 ~/.cogniscor/config.properties

Backup Your Config

# Backup
cp ~/.cogniscor/config.properties ~/cogniscor-config-backup.properties

# Restore
cp ~/cogniscor-config-backup.properties ~/.cogniscor/config.properties

🎯 Different Setup Scenarios

Scenario 1: No AI (Free)

Do you have an OpenAI API key? no

Result: Fast, free, regex-based extraction

Scenario 2: AI-Enhanced

Do you have an OpenAI API key? yes
Enter your OpenAI API key: sk-...
Choose model: 1 (gpt-4o-mini)
Enable AI-enhanced extraction? yes
Enable AI report review? yes

Result: Better extraction + polished reports (~$0.025/company)

Scenario 3: Budget-Conscious

Choose model: 3 (gpt-3.5-turbo)
Enable AI-enhanced extraction? yes
Enable AI report review? no

Result: Enhanced extraction only (~$0.01/company)

Scenario 4: Best Quality

Choose model: 2 (gpt-4o)
Enable all features: yes

Result: Highest quality (~$0.15/company)

🚀 Next Steps

After setup:

1. Test it out:

   ./cogniscor.sh "GitHub" "https://github.com"
   

2. Check results:

   ls data/github/reports/
   cat data/github/reports/executive_summary.md
   

3. Monitor costs (if using AI):

   • https://platform.openai.com/usage

4. Read more:

   • README.md - Full documentation
   • LLM_SETUP_GUIDE.md - Detailed AI guide
   • CHEATSHEET.md - Quick reference

💡 Tips

• Start without AI to see baseline results
• Enable AI to compare the improvement
• Monitor your first few API calls for cost
• Use gpt-4o-mini for best price/performance
• Run setup again anytime to change settings

---

Ready to research companies? Run ./cogniscor.sh --setup to get started! 🎉