<p align="center"> <a href="https://github.com/yorkeccak/history/stargazers"><img src="https://img.shields.io/github/stars/yorkeccak/history?style=flat&color=yellow" alt="GitHub Stars"></a> <a href="https://github.com/yorkeccak/history/blob/main/LICENSE"><img src="https://img.shields.io/github/license/yorkeccak/history" alt="License"></a> <a href="https://github.com/yorkeccak/history/network/members"><img src="https://img.shields.io/github/forks/yorkeccak/history?style=flat" alt="Forks"></a> <a href="https://github.com/yorkeccak/history/graphs/contributors"><img src="https://img.shields.io/github/contributors/yorkeccak/history" alt="Contributors"></a> </p>

History

history.valyu.ai

I can't stop doomscrolling Google Maps so I built AI that researches anywhere on Earth

An interactive 3D globe that lets you explore the fascinating history of any location on the planet. Born from opening Google Maps in satellite view at 2am and clicking on random shit - obscure atolls in the Pacific that look like someone dropped a pixel, unnamed mountains in Kyrgyzstan, Arctic settlements with 9 people. Places so remote they don't have Wikipedia pages.

Be curious.

The Problem

I have a problem. I'll lose 6 hours to doomscrolling Google Maps. Just clicking. Finding volcanic islands that look photoshopped. Fjords that defy physics. Tiny dots of land in the middle of nowhere. And every single time I think: what IS this place? Who found it? Why does it exist? What happened here?

Then you try to research it and it's hell. 47 Wikipedia tabs. A poorly-translated Kazakh government PDF from 2003. A travel blog from 1987. A single Reddit comment from 2014 that says "I think my uncle went there once." You piece it together like a conspiracy theorist and still don't get the full story.

The information exists somewhere. Historical databases. Academic archives. Colonial records. Exploration logs from the 1800s. But it's scattered everywhere and takes forever to find.

The Solution

Click anywhere on a globe. Get actual research. It searches hundreds of sources for up to 10 minutes and gives you the full story. With citations so you know it's not making shit up.

Not ChatGPT summarizing from training data. Actual research. It searches:

• Historical databases and archives
• Academic papers and journals
• Colonial records and exploration logs
• Archaeological surveys
• Wikipedia and structured knowledge bases
• Real-time web sources

Example: Tristan da Cunha (most remote inhabited island on Earth, population 245)

Click on it and you get:

• Discovery by Portuguese explorers in 1506
• British annexation in 1816 (strategic location during Napoleonic Wars)
• Volcanic eruption in 1961 that evacuated the entire population
• Current economy (crayfish export, philately)
• Cultural evolution of the tiny community
• Full timeline with sources

What would take hours of manual research happens automatically. And you can verify everything.

Why This Exists

Because I've spent literal months of my life doomscrolling Google Maps clicking on random islands at 3am and I want to actually understand them. Not skim a 4-paragraph Wikipedia stub. Not guess based on the name. Proper historical research. Fast.

The databases exist. The archives are digitized. The APIs are built. Someone just needed to connect them to a globe and make it accessible.

This is what AI should be doing. Not writing emails. Augmenting genuine human curiosity about the world.

Key Features

Real Research Infrastructure

• Valyu DeepResearch API - Access to academic databases, archives, historical records
• Runs for up to 10 minutes - Searches hundreds of sources
• Full citations - Every claim linked to verifiable sources
• Live progress tracking - Watch the research unfold in real-time, see every source it queries

Interactive Globe

• 3D Satellite Visualization - Stunning Mapbox satellite imagery with globe projection
• Click literally anywhere - Any country, island, mountain, or geographical feature
• Random Discovery - "I'm Feeling Lucky" button for random location exploration
• Multiple Map Styles - Satellite, streets, outdoors, and more

Save & Share

• Research History - Save and revisit your discoveries
• Shareable Links - Generate public links to research
• Mobile responsive - Works on phone/tablet/desktop

Technology Stack

Research

• Valyu DeepResearch API - Comprehensive search across databases, archives, academic sources

Frontend

• Next.js 15 + React 19 - Modern web framework
• Mapbox GL JS - Interactive 3D globe visualization
• Tailwind CSS + Framer Motion - Beautiful UI with smooth animations
• React Markdown - Rendering research reports

Backend

• Supabase - Authentication and database (valyu mode)
• SQLite - Local database (self-hosted mode)
• Drizzle ORM - Type-safe database queries

Infrastructure

• Vercel - Deployment and hosting
• TypeScript - Type safety throughout

Fully open-source. Self-hostable. Model-agnostic.

Quick Start (Self-Hosted)

Self-hosted mode is the recommended way to run History locally. It requires only 2 API keys and takes about 5 minutes to set up.

Prerequisites

• Node.js 18+
• pnpm (npm install -g pnpm)
• Valyu DeepResearch API key (get one free at platform.valyu.ai)
• Mapbox access token (get one free at mapbox.com)

Installation

1. Clone the repository

   git clone https://github.com/yorkeccak/history.git
   cd history
   

2. Install dependencies

   pnpm install
   

3. Set up environment variables

   Create a .env.local file in the root directory:

   # Self-Hosted Mode - No Auth Required
   NEXT_PUBLIC_APP_MODE=self-hosted
   
   # Valyu API (Required)
   VALYU_API_KEY=valyu_your_api_key_here
   
   # Mapbox Configuration (Required)
   NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your_mapbox_access_token_here
   
   # App URL
   NEXT_PUBLIC_APP_URL=http://localhost:3000
   

4. Run the development server

   pnpm dev
   

5. Open your browser

   Navigate to http://localhost:3000

6. Start exploring

   • Click anywhere on the globe to research that location
   • Use the "Random Location" button to discover somewhere new
   • Watch the AI research unfold in real-time

How to Use

Basic Usage

1. Navigate the Globe

   • Drag to rotate
   • Scroll to zoom in/out
   • The globe auto-rotates when idle

2. Research a Location

   • Click on any country, city, island, or geographical feature
   • A popup will show the location name
   • The research interface opens automatically

3. Watch the Research

   • See the AI's reasoning process
   • View tool calls (web searches, database queries)
   • See sources being discovered in real-time

4. Review Results

   • Read the comprehensive historical analysis
   • Click on source citations to verify information
   • View images and visual aids (if available)

5. Save for Later

   • Your research is automatically saved locally
   • Access past research from the sidebar

Advanced Features

• Random Discovery: Click "Random Location" to explore a random place on Earth
• Map Styles: Switch between satellite, streets, and other map styles
• Reasoning View: Click to see the detailed reasoning trace of the AI
• Dark Mode: Automatically matches your system preferences

App Modes

History runs in self-hosted mode:

Self-Hosted Mode (Recommended)

NEXT_PUBLIC_APP_MODE=self-hosted

Features:

• No Supabase required - uses local SQLite
• No authentication needed - auto-login as dev user
• Unlimited queries - no rate limits
• Uses your Valyu API key directly
• Works completely offline (except API calls)
• Perfect for local usage and contributing

Deploy to Vercel

The quickest way to get History running in production:

1. Fork this repository to your GitHub account
2. Create a new project on vercel.com and import your fork
3. Add environment variables in Vercel project settings (Settings > Environment Variables):
   • NEXT_PUBLIC_APP_MODE = self-hosted
   • VALYU_API_KEY = your Valyu API key
   • NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN = your Mapbox access token
4. Deploy - Vercel handles the rest

Getting API Keys

Valyu API (Required)

1. Go to platform.valyu.ai
2. Sign up for a free account
3. Navigate to API Keys
4. Create a new API key
5. Add it to .env.local as VALYU_API_KEY

Pricing:

• Free tier available for testing
• Pay-as-you-go pricing for production
• Fast model: approximately $0.10 per research
• Heavy model: approximately $0.50 per research

Mapbox Access Token (Required)

1. Go to mapbox.com
2. Sign up for a free account
3. Create a new access token
4. Add it to .env.local as NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN

Pricing:

• 50,000 free map loads per month
• Additional usage billed per load (very affordable)

Database Schema

History uses a minimal database schema optimi