docs/QUICK_START.md

# Quick Start: Fraud Assistant with Confluence Integration

Follow these steps to add Confluence search to your fraud explainability assistant in **under 10 minutes**.

---

## TL;DR (For the Impatient)

```bash
# 1. Install dependencies
pip install -r requirements-with-confluence.txt

# 2. Create .env file with your Confluence credentials
cp .env.example .env
nano .env  # Add your Confluence URL, email, and API token

# 3. Test it
python confluence_integration_example.py
```

Then ask: **"What does our fair lending policy say about synthetic ID detection?"**

---

## Step-by-Step Setup

### Step 1: Get Confluence API Token (2 minutes)

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click **"Create API token"**
3. Label it: "Fraud Assistant"
4. **Copy the token** (you won't see it again!)

### Step 2: Configure Environment (1 minute)

```bash
cd fraud_model_explainability_assistant

# Copy example file
cp .env.example .env

# Edit with your credentials
nano .env  # or use your preferred editor
```

**Edit these 3 lines** in `.env`:
```bash
CONFLUENCE_URL=https://yourcompany.atlassian.net  # YOUR Confluence URL
CONFLUENCE_EMAIL=your.email@company.com           # YOUR email
CONFLUENCE_API_TOKEN=ATATT3xFfGF0...              # YOUR token (paste here)
```

Save and close.

### Step 3: Install Dependencies (2 minutes)

```bash
# Install everything needed
pip install -r requirements-with-confluence.txt

# Verify installation
python -c "from confluence_ingestor import ConfluenceRAG; print('✅ Ready!')"
```

### Step 4: Identify Confluence Spaces (1 minute)

Find the "space keys" for your Confluence spaces:

1. Open your Confluence
2. Go to a space
3. Look at the URL: `https://yourcompany.atlassian.net/wiki/spaces/SPACEKEY/`
4. The `SPACEKEY` is what you need

**Recommended spaces**:
- Model governance docs (e.g., `fraud-model-governance`)
- Compliance policies (e.g., `compliance-policies`)
- Investigation playbooks (e.g., `fraud-investigation`)

### Step 5: Update Space Keys in Code (1 minute)

Edit `confluence_integration_example.py` line 88:

```python
spaces = {
    "your-governance-space": 100,   # Replace with YOUR space key
    "your-compliance-space": 50,    # Replace with YOUR space key
    "your-playbooks-space": 75,     # Replace with YOUR space key
}
```

### Step 6: Run Initial Ingestion (5 minutes)

This downloads and indexes your Confluence content (one-time):

```bash
python confluence_integration_example.py
```

**What happens**:
1. Connects to Confluence ✅
2. Downloads pages from your spaces (~5 min)
3. Creates searchable vector database
4. Launches web UI

**First time only**: Downloads ~400MB ML model (free, runs locally)

### Step 7: Test It! (1 minute)

1. Open http://localhost:7860 in your browser
2. Try these questions:

**Question 1** (tests Confluence search):
```
What does our fair lending policy say about phone type features?
```

**Question 2** (tests fraud analysis):
```
Why was application APP-78432 flagged as high risk?
```

**Question 3** (tests compliance with policy citation):
```
Check fair lending compliance for APP-55555 and cite relevant policies
```

If the agent cites specific Confluence pages in its response, **it's working!** 🎉

---

## What You Just Built

Your fraud assistant now has access to:
- ✅ Company fair lending policies
- ✅ Model governance documentation
- ✅ Investigation procedures
- ✅ Compliance guidelines
- ✅ Historical precedents

**Use cases unlocked**:
- Executive briefings with policy citations
- Regulatory examination support
- Analyst training and investigation support
- Audit trail documentation

---

## Troubleshooting

### "3 validation errors for ConfluenceConfig"

**Problem**: Missing Confluence credentials

**Fix**:
```bash
# Check if .env exists
ls -la .env

# If missing:
cp .env.example .env

# Edit with your credentials
nano .env

# Verify:
cat .env | grep CONFLUENCE
```

### "401 Unauthorized"

**Problem**: Wrong email or API token

**Fix**:
1. Re-generate API token at https://id.atlassian.com/manage-profile/security/api-tokens
2. Double-check email is correct
3. Remove any extra spaces in `.env`

### "Space 'xyz' not found"

**Problem**: Space key doesn't exist or you don't have access

**Fix**:
1. Check the space key in Confluence URL
2. Verify you can view the space when logged in
3. Update space keys in `confluence_integration_example.py` line 88

### "Module not found: confluence_ingestor"

**Problem**: Package not installed

**Fix**:
```bash
pip install -r requirements-with-confluence.txt
```

---

## Next Steps

Once it's working:

1. **Add more spaces**: Edit the `spaces` dict in the code
2. **Customize prompts**: Update `ENHANCED_PROMPT` for your use case
3. **Set up auto-updates**: See `CONFLUENCE_INTEGRATION_ANALYSIS.md`
4. **Share with team**: Deploy on internal server
5. **Monitor usage**: Track which policies are searched most

---

## Full Documentation

- **Detailed Setup**: See `CONFLUENCE_SETUP_GUIDE.md`
- **Architecture & ROI**: See `CONFLUENCE_INTEGRATION_ANALYSIS.md`
- **Confluence-Ingestor Docs**: See `../confluence-ingestor/README.md`

---

## Summary Checklist

- [ ] Get Confluence API token (2 min)
- [ ] Create `.env` with credentials (1 min)
- [ ] Install dependencies (2 min)
- [ ] Find your Confluence space keys (1 min)
- [ ] Update space keys in code (1 min)
- [ ] Run initial ingestion (5 min)
- [ ] Test with sample questions (1 min)

**Total Time**: ~10 minutes

---

## Support

**Having issues?** Check:
1. `CONFLUENCE_SETUP_GUIDE.md` - Detailed troubleshooting
2. `CONFLUENCE_INTEGRATION_ANALYSIS.md` - Architecture details
3. The "Troubleshooting" section above

**Still stuck?** Review the error message - it usually tells you what's missing!

---

**You're done!** Your fraud assistant can now search company documentation and cite specific policies. 🚀