Worldline

Explore why reality unfolded this way.

Worldline is a causal reality exploration platform for researching how a situation formed, which actors shaped it, what alternative worlds were plausible, and how the current reality is shifting over time.

This repository contains the full-stack Worldline application:

• FastAPI backend for analysis, orchestration, and SSE streaming
• React + Vite frontend for search, workspace exploration, simulation replay, and Reality Memory
• Empathy Engine as the internal actor-cognition subsystem inside Worldline

What Worldline Does

Worldline is designed to move from:

query -> analysis -> simulation

into:

topic -> memory -> comparison -> evolution -> investigation

Current product capabilities include:

• search-first issue analysis
• multi-source context scraping and grounding
• causal actor network generation
• real-time SSE streaming for analysis and simulation
• interactive Reality Space and Actor Network views
• simulation replay and mitigation output
• local snapshot save, reopen, compare, and export
• Reality Memory with topic grouping, timelines, drift history, and topic briefs

Product Model

Worldline is not a forecasting dashboard and not a generic chatbot.

It is a causal reasoning workspace that helps answer:

• Why did reality unfold this way?
• Which actors mattered most?
• What changed between one understanding state and another?
• How has this topic evolved over time?
• What is the latest state compared with the first known state?

Core Experience

1. Search and Context Analysis

The user starts with a query.

Worldline:

• gathers public signals
• verifies facts
• builds an initial world model
• proposes scenario directions

2. Interactive Workspace

The user moves through:

• Overview
• Reality Space
• Actor Network
• Evidence
• Simulation

3. Snapshot and Compare

The user can:

• save a local snapshot
• reopen a previous state without rerunning analysis
• compare two snapshots
• export comparison Markdown

4. Reality Memory

Worldline groups snapshots into topic memory so users can inspect:

• topic history
• drift progression
• change milestones
• first vs latest state
• topic-level memory briefs

Architecture

graph TD
    User["User Query"] --> Analyze["/api/analyze-context"]
    Analyze --> Scrape["Multi-source scraping"]
    Analyze --> Verify["Fact grounding"]
    Analyze --> World["World state construction"]
    World --> UI["React workspace"]
    UI --> Debate["/api/run-debate"]
    Debate --> Stream["Round-by-round SSE stream"]
    Stream --> Memory["Snapshots, compare, Reality Memory"]

Loading

Stack

• Backend: Python, FastAPI, LiteLLM, CrewAI, SQLite, ChromaDB
• Frontend: React, Vite, Tailwind CSS, D3.js
• Transport: Server-Sent Events (SSE)

Repository Structure

repo_github/
├─ api.py
├─ core/
├─ frontend/
├─ docs/
├─ tests/
├─ start_dev.py
└─ README.md

Quick Start

One-command dev launch

From this repository root:

py .\start_dev.py

This starts:

• backend at http://localhost:8000
• frontend at http://localhost:5173

Manual backend

pip install -r requirements.txt
python api.py

Manual frontend

cd frontend
npm install
npm run dev

Validation

Backend regression suite:

py tests/test_blackbox.py

Frontend checks:

cd frontend
npm run lint
npm run build

Current UI Direction

The UI direction is:

• light
• minimal
• modern
• research-oriented

Reality Memory is intended to feel like a living research history rather than a storage drawer.

Important Technical Notes

• SSE formatting in /api/run-debate must remain stable.
• Snapshot and memory flows are local-first and browser-based.
• The canvas interaction layer and graph exploration flows should be preserved carefully during frontend work.
• Worldline is the product name. Empathy Engine is the subsystem name for actor cognition.

Supporting Docs

• docs/WORLDLINE_ARCHITECTURE_V1.md
• docs/WORLDLINE_CORE_V2.md
• docs/WORLDLINE_V2_STATUS.md
• docs/WORLDLINE_V3_BUILD_PLAN.md
• docs/WORLDLINE_V3_FOUNDER_BRIEF.md

Status

The current system already supports:

• Worldline workspace
• snapshot memory
• comparison flow
• topic memory
• memory storytelling
• memory landing dashboard

Worldline is now positioned as a memory-aware causal reality research product, with future roadmap room for alignment, validation, and continuous reality tracking.