Installation Guide¶

Get ChronoScope up and running on your local machine in just a few minutes.

System Requirements¶

Step 1: Install Python¶

ChronoScope requires Python 3.9 or higher. Check your Python version:

python3 --version

Step 2: Download ChronoScope¶

Option A: Clone with Git (Recommended)¶

# Clone the repository
git clone https://github.com/yourusername/chronoscope.git

# Navigate to the project directory
cd chronoscope

Option B: Download ZIP¶

1. Visit github.com/yourusername/chronoscope
2. Click the green "Code" button
3. Select "Download ZIP"
4. Extract the ZIP file
5. Open terminal/command prompt in the extracted folder

Step 3: Create Virtual Environment¶

A virtual environment keeps ChronoScope's dependencies isolated from your system Python.

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Create virtual environment
python -m venv .venv

# Activate virtual environment
.venv\Scripts\activate.bat

# Create virtual environment
python -m venv .venv

# Activate virtual environment
.venv\Scripts\Activate.ps1

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Step 4: Install Dependencies¶

With your virtual environment activated, install ChronoScope's dependencies:

pip install -r requirements.txt

This will install:

• Streamlit - Web interface framework
• OpenAI - AI extraction capabilities
• Plotly - Interactive visualizations
• Pandas - Data manipulation
• And other supporting libraries

Step 5: Configure OpenAI API Key¶

ChronoScope uses OpenAI's API for intelligent event extraction.

Get an API Key¶

1. Go to platform.openai.com/api-keys
2. Sign up or log in
3. Click "Create new secret key"
4. Copy your API key (it starts with sk-)

Add Key to ChronoScope¶

Create a configuration file:

mkdir -p .streamlit
echo 'OPENAI_API_KEY = "sk-your-key-here"' > .streamlit/secrets.toml

mkdir .streamlit
echo OPENAI_API_KEY = "sk-your-key-here" > .streamlit\secrets.toml

Replace sk-your-key-here with your actual API key.

Verify Configuration¶

Check that the file was created correctly:

cat .streamlit/secrets.toml  # macOS/Linux
type .streamlit\secrets.toml  # Windows

You should see:

OPENAI_API_KEY = "sk-your-actual-key"

Step 6: Launch ChronoScope¶

Start the application:

streamlit run timeline-mvp-pipeline.py

Verification Checklist¶

Before proceeding, verify:

• Python 3.9+ is installed
• Virtual environment is activated (you see (.venv) in terminal)
• Dependencies are installed (pip list shows streamlit, openai, plotly)
• OpenAI API key is configured in .streamlit/secrets.toml
• ChronoScope opens in your browser at localhost:8501

Troubleshooting¶

Python Not Found¶

python --version   # Try without the '3'
py --version       # Windows Python launcher

Virtual Environment Issues¶

source .venv/bin/activate

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Dependency Installation Fails¶

pip install --upgrade pip
pip install -r requirements.txt

pip install streamlit openai plotly pandas python-dateutil

OpenAI API Key Issues¶

ls .streamlit/secrets.toml  # Should exist

Port Already in Use¶

streamlit run timeline-mvp-pipeline.py --server.port 8502

Next Steps¶

✅ Installation Complete!

Now you're ready to:

1. Quick Start Tutorial - 5-minute walkthrough
2. Create Your First Timeline - Step-by-step guide
3. Upload Documents Guide - Best practices

Optional: Install Documentation Tools¶

If you want to build and view this documentation locally:

pip install -r requirements-docs.txt
mkdocs serve

Visit http://localhost:8000 to view the documentation.

Optional: Advanced AI Features (LangChain)¶

ChronoScope works great out of the box, but developers can optionally install LangChain for enhanced AI extraction features.

What is LangChain?¶

LangChain is an optional framework that adds:

• Better error handling - Automatic retries with smarter fallback logic
• Enhanced debugging - Detailed logs of AI prompts and responses
• Structured prompts - Template-based prompt management
• Advanced monitoring - Track API usage, costs, and performance

Do I Need It?¶

No! Most users don't need LangChain. ChronoScope's default AI extraction works excellently for building timelines.

Install it only if you:

• Are a developer customizing extraction prompts
• Need detailed debugging information
• Want advanced API usage tracking
• Experience extraction reliability issues

Installation¶

# Activate your virtual environment first
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Install LangChain packages
pip install langchain langchain-openai

# Restart ChronoScope
streamlit run timeline-mvp-pipeline.py

What Changes?¶

Before (Direct OpenAI):

ℹ️ Using direct OpenAI integration. LangChain not installed.

After (LangChain): - Info message disappears - Advanced debugging features available in Advanced Settings - Slightly better extraction confidence scores (85% vs 80%) - Same extraction quality and cost

Learn More¶

See Advanced Features: LangChain Integration for technical details and comparison.

Updating ChronoScope¶

To update to the latest version:

# Pull latest code
git pull origin main

# Update dependencies
pip install -r requirements.txt --upgrade

# Restart ChronoScope
streamlit run timeline-mvp-pipeline.py

alias chronoscope="cd ~/chronoscope && source .venv/bin/activate && streamlit run timeline-mvp-pipeline.py"

function Start-ChronoScope {
    cd C:\path\to\chronoscope
    .\.venv\Scripts\Activate.ps1
    streamlit run timeline-mvp-pipeline.py
}
Set-Alias chronoscope Start-ChronoScope