Files
Cogniscor/SETUP_GUIDE.md

384 lines
7.7 KiB
Markdown

# Cogniscor - Setup Guide
## 🚀 Quick Start (First Time Users)
### Step 1: Run Setup Wizard
```bash
./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
```bash
./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:
```bash
# Open in your favorite editor
nano ~/.cogniscor/config.properties
# Or
vim ~/.cogniscor/config.properties
```
### Example Configuration
```properties
# 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
```bash
./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:
```bash
./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
```bash
cat ~/.cogniscor/config.properties
```
### Check if Config Exists
```bash
ls -la ~/.cogniscor/
```
### Test Configuration
```bash
./cogniscor.sh "Test Company" "https://example.com"
```
## 🚨 Troubleshooting
### "Configuration Required" Error
**Problem**: Running without setup
```
⚠ CONFIGURATION REQUIRED ⚠
```
**Solution**:
```bash
./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**:
```bash
./cogniscor.sh --setup # Re-enter your key
```
### Wrong Model Selected
**Change model**:
```bash
# Edit config file
nano ~/.cogniscor/config.properties
# Change this line:
openai.model=gpt-4o-mini
```
Or re-run setup:
```bash
./cogniscor.sh --setup
```
### Want to Disable AI
**Option 1**: Set in config
```bash
nano ~/.cogniscor/config.properties
# Change to:
llm.enabled=false
```
**Option 2**: Remove API key
```bash
nano ~/.cogniscor/config.properties
# Change to:
openai.api.key=
```
### Config File Corrupted
**Delete and recreate**:
```bash
rm -rf ~/.cogniscor/
./cogniscor.sh --setup
```
## 📝 Configuration Options Reference
### HTTP Settings
```properties
http.timeout.seconds=30 # Request timeout
http.user.agent=Mozilla/5.0... # User agent string
http.max.redirects=5 # Max HTTP redirects
```
### Rate Limiting
```properties
rate.limit.delay.ms=2000 # Delay between requests
rate.limit.enabled=true # Enable rate limiting
```
### Scraping
```properties
scraper.max.retries=3 # Retry attempts
scraper.retry.delay.ms=5000 # Delay between retries
```
### OpenAI / LLM
```properties
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
```properties
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
```properties
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
```bash
# Secure your config file
chmod 600 ~/.cogniscor/config.properties
```
### Backup Your Config
```bash
# 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:**
```bash
./cogniscor.sh "GitHub" "https://github.com"
```
2. **Check results:**
```bash
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! 🎉