Your First Timeline - Complete Walkthrough¶

A comprehensive step-by-step guide to creating, validating, and customizing your first timeline in ChronoScope.

Overview¶

This tutorial covers the complete timeline creation workflow:

1. Document preparation
2. Upload and processing
3. Reviewing extracted events
4. Quality validation
5. Customization and filtering
6. Adding personal insights
7. Export options

Time Required: 15-20 minutes

Phase 1: Preparing Your Document¶

What Makes a Good Source Document?¶

ChronoScope works best with documents that have:

✅ Clear Dates

✓ Good: "January 2020 - March 2023"
✗ Poor: "recently" or "a few years ago"

✅ Structured Information

✓ Good: Resume with sections (Experience, Education)
✗ Poor: Unstructured narrative without headings

✅ Specific Details

✓ Good: "Senior Developer at TechCorp, San Francisco"
✗ Poor: "Worked at a company doing tech stuff"

Recommended Document Types¶

WORK EXPERIENCE
Senior Software Engineer | Google, Mountain View, CA
June 2020 - Present
- Led team of 5 developers
...

EDUCATION
BS Computer Science | Stanford University
Sept 2016 - May 2020

After graduating from MIT in 2018, I joined Startup Inc.
as a founding engineer. Over the next three years (2018-2021),
I built the core platform...

Document Checklist¶

Before uploading, ensure your document has:

• Clear dates (month/year or specific dates)
• Event titles or descriptions
• Locations (if applicable)
• Structured format (headings, bullets, sections)
• Readable text (not scanned images)
• Supported format (PDF, TXT, DOCX)

Phase 2: Upload and Processing¶

Step 1: Access Upload Tab¶

1. Launch ChronoScope: streamlit run timeline-mvp-pipeline.py
2. Navigate to "📤 Upload & Process" tab
3. Ensure you see the file uploader

Step 2: Configure Processing (Optional)¶

For most users, default settings work well. Advanced users can:

Step 3: Upload Document¶

Method 1: Drag and Drop

┌────────────────────────────┐
│   Drop file here           │
│                            │
│   or click to browse       │
└────────────────────────────┘

Method 2: File Browser

1. Click "Browse files"
2. Navigate to your document
3. Select and click "Open"

Step 4: Initiate Processing¶

1. Verify file is uploaded (you'll see filename)
2. Click "🚀 Process Documents"
3. Watch progress indicator

Processing Steps:

📄 Reading document...
🔍 Detecting document type... (Resume detected)
🤖 Extracting events with AI...
✅ Processing complete!

Timing:

• Short resume (1-2 pages): 5-10 seconds
• Long CV (10+ pages): 20-30 seconds
• Multiple documents: ~10s per document

Phase 3: Reviewing Extracted Events¶

Understanding Event Structure¶

Navigate to "📈 Timeline" tab. Each event contains:

Event Display Table¶

The timeline tab shows events in a sortable table:

┌─────────────────────────────────────────────────────────────────┐
│  Title              | Start Date  | End Date    | Confidence   │
├─────────────────────────────────────────────────────────────────┤
│  Senior Developer   │ 2020-01-15  │ 2023-03-20  │ 85%         │
│  BS Computer Sci    │ 2016-09-01  │ 2020-05-15  │ 92%         │
│  AWS Certification  │ 2021-06-10  │ -           │ 78%         │
└─────────────────────────────────────────────────────────────────┘

Quick Actions¶

• 🔍 Hover - See full details in tooltip
• 📋 Sort - Click column headers
• ✏️ Edit - Inline editing (select cell)
• 🗑️ Delete - Click X icon
• 📥 Export - Download as CSV/JSON

Phase 4: Quality Validation¶

Running Validation¶

1. Navigate to "✅ Validation" tab
2. Click "Run Validation" button
3. Review metrics dashboard

Understanding Metrics¶

Precision (Accuracy)

Precision = True Positives / (True Positives + False Positives)

• How many extracted events are correct?
• High (>80%): Excellent accuracy
• Medium (60-80%): Good, few errors
• Low (<60%): Many incorrect events

Recall (Completeness)

Recall = True Positives / (True Positives + False Negatives)

• How many real events were captured?
• High (>80%): Comprehensive extraction
• Medium (60-80%): Missing some events
• Low (<60%): Many events missed

F1-Score (Overall Quality)

F1 = 2 * (Precision * Recall) / (Precision + Recall)

• Balanced measure of quality
• 80%+: Excellent
• 60-80%: Acceptable
• <60%: Needs improvement

Validation Results Example¶

┌──────────────────────────────────────┐
│  Quality Metrics                     │
├──────────────────────────────────────┤
│  Precision:  78.5%                   │
│  Recall:     65.2%                   │
│  F1-Score:   71.2%                   │
│                                      │
│  Events Extracted:    14             │
│  Gold Standard:       28             │
│  Matched Events:      11             │
│  Missing Events:      17             │
│  Extra Events:        3              │
└──────────────────────────────────────┘

Improving Quality¶

If validation scores are low:

1. Check Source Document - Are dates explicit and clear? - Is information structured? - Try reformatting for clarity

2. Adjust AI Settings

# Try GPT-4 for better accuracy
Model: gpt-4
Temperature: 0.2 (more deterministic)
Max Tokens: 3000 (for longer docs)

3. Manual Review - Check low-confidence events - Verify dates against source - Add missing events manually

Phase 5: Customization and Filtering¶

Applying Filters¶

Sidebar Filter Options:

Start Date: [2020-01-01]
End Date:   [2023-12-31]

☑ work
☑ education
☐ personal
☐ certification

Minimum Confidence: [0.7] (70%)

Minimum Priority: [5]

Visualization Options¶

Timeline Chart

• Gantt-style chronological view
• Color-coded by event type
• Interactive hover tooltips

Priority Matrix

• Scatter plot: Confidence vs Priority
• Identify high-value events
• Spot low-confidence, high-priority items

Distribution Chart

• Events over time histogram
• Identify busy periods
• Visualize career density

Phase 6: Adding Personal Insights¶

Using the Notes Feature¶

Scroll below the tabs to find "📝 User Notes":

Creating a Note:

1. Enter note name (e.g., "Career Reflections")
2. Type your thoughts in text area
3. Click "💾 Save Note"

Example Uses:

# Career Insights (2020-2023)

## Key Learnings
- Leadership skills grew significantly at TechCorp
- AWS certification opened new opportunities
- Remote work transition in 2020 was challenging but valuable

## Future Goals
- Pursue management track
- Complete advanced ML certification
- Contribute to open source

## Patterns Noticed
- Major role changes every ~2 years
- Education/certification precedes promotions
- Location changes correlate with career growth

Note Features:

• ✍️ Rich text editing
• 💾 Persistent storage (survives sessions)
• 📊 Character count tracking
• 🕒 Last modified timestamp
• 🗑️ Delete with confirmation

Phase 7: Export Options¶

Available Export Formats¶

📊 Timeline → Export → PNG
Resolution: 1920x1080

title,start_date,end_date,location,confidence
Senior Developer,2020-01-15,2023-03-20,SF,0.85

{
  "events": [...],
  "metadata": {...}
}

=== "PDF Report" (Coming Soon) Will include:

- Timeline visualization
- Event summary table
- Validation metrics
- Notes and insights

Best Practices¶

Do's ✅¶

• Start with clean, structured documents
• Review confidence scores - Focus on >70%
• Run validation regularly after adding documents
• Use filters to focus analysis
• Save notes to capture insights
• Export backups of your timeline data

Don'ts ❌¶

• Don't upload scanned images (use OCR first)
• Don't ignore low confidence events (review them)
• Don't process all documents at once (start small)
• Don't forget to save notes before closing
• Don't share API keys (keep .streamlit/secrets.toml private)

Next Steps¶

🎉 Congratulations! You've created a comprehensive timeline!

Continue Your Journey:¶

• 📤 Upload Best Practices - Optimize extraction
• 📊 Visualization Deep Dive - Advanced charting
• 🔧 Advanced Features - Power user guide
• 🐛 Troubleshooting - Common problems

Community Resources:¶

• 💬 Join Discussions
• 📖 Share Your Timeline