Upload 10 files

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Meridian Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,14 +1,123 @@
 ---
-title: Geospacial Image Generator
-emoji: 🐠
-colorFrom: indigo
-colorTo: yellow
+title: Meridian - Historical Image Generator
+emoji: 🌍
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.0.1
+sdk_version: 5.0.0
 app_file: app.py
 pinned: false
+tags:
+  - building-mcp-track-consumer
+  - mcp
+  - historical
+  - image-generation
+  - flux
+  - gemini
+  - geospatial
+  - coordinates
 license: mit
-short_description: Takes geographic coordinates, finds historical events -> 📸
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🌍 Meridian: Historical Image Generator
+
+**Turn coordinates and dates into historical images. See what happened at any location, any time.**
+
+## What It Does
+
+Meridian takes geographic coordinates and a date, finds historical events that happened there, and generates images of those moments. It solves a real problem: image generators don't understand coordinates. Ask DALL-E to show you "52.5163°N, 13.3777°E on November 9, 1989" and you'll get random landscapes. But that's exactly where the Berlin Wall fell.
+
+## The Problem
+
+Image models break coordinates into separate tokens ("52", ".", "5163") and treat them like unrelated symbols. They don't know that 52.5°N and 52.6°N are close together—to the model, they're as different as "apple" and "orange". Training data rarely includes GPS coordinates, so models never learn the connection between coordinates and what you'd actually see there.
+
+DALL-E 3 works around this by using GPT-4 as a middleman—GPT recognizes the coordinates, looks them up, rewrites them to "Berlin Wall", then DALL-E generates the image. But that's fragile and limited to what GPT knows.
+
+## How Meridian Space Works
+
+Instead of trying to teach image models about coordinates (which would need billions of coordinate-tagged images), Meridian builds a bridge: it maintains a database of historical events with their exact coordinates and dates, then converts those into descriptions that image models understand.
+
+1. You enter coordinates and a date
+2. Meridian searches its database and Wikidata for events at that location and time
+3. It builds a focused prompt emphasizing the event name, location, year, and time
+4. FLUX generates a historically accurate image
+
+The system prioritizes events that match your exact year, so "Rome, 44 BCE" gives you Julius Caesar's assassination, not a medieval event at the same spot.
+
+## Features
+
+**Multiple Styles**: Documentary, Cinematic, Photojournalistic, Dramatic, Cartoon, Minecraft, Retro, and Glitch styles let you visualize history in different ways.
+
+**Time-Aware**: The hour you choose affects lighting (dawn vs midday vs night). Month and latitude determine season and atmosphere.
+
+**Period-Accurate**: Negative prompts automatically prevent anachronisms. Ancient scenes won't have modern tech, 19th-century scenes won't have smartphones.
+
+**Dual Data Sources**: Curated database for quality, Wikidata for breadth. Events are scored by how close they are (geographically and temporally) and how reliable the source is.
+
+**MCP Integration**: Works as an MCP server, so Claude and other AI assistants can call it programmatically. Ask Claude "show me what happened at these coordinates" and it just works.
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Set API keys (optional but recommended)
+export HF_TOKEN="your_huggingface_token"  # Required for image generation
+export GEMINI_API_KEY="your_gemini_key"  # Optional, for better prompts
+
+# Run it
+python app.py
+```
+
+Visit http://localhost:7860 (or whatever port it shows in your terminal)
+
+## Examples to Try
+
+- **Julius Caesar's Assassination**: 41.8902°N, 12.4922°E, March 15, 44 BCE, 11:00
+- **Fall of Berlin Wall**: 52.5163°N, 13.3777°E, November 9, 1989, 23:00
+- **Moon Landing**: 28.5729°N, -80.6490°W, July 16, 1969, 13:32
+- **D-Day**: 49.3414°N, -0.8322°W, June 6, 1944, 06:30
+
+## MCP Server
+
+To use with Claude Desktop, add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "meridian": {
+      "command": "uv",
+      "args": ["run", "/absolute/path/to/MCP/Meridian/app.py"]
+    }
+  }
+}
+```
+
+Then for example ask Claude: "Show me what happened at 52.5163, 13.3777 on November 9, 1989"
+
+## Tech Stack
+
+- **FLUX.1-dev**: Image generation via Hugging Face
+- **Gemini 1.5 Flash**: Optional prompt enhancement
+- **Wikidata**: Historical event database
+- **SQLite**: Local curated events with Haversine distance queries (50 events so far but will add more)
+- **Gradio**: Web interface
+- **MCP**: Model Context Protocol for AI assistant integration
+
+## Limitations
+
+The curated database has about 50 events, but Wikidata adds much more coverage. Prompt quality depends on whether Gemini is available (falls back to templates if not). Images are historically inspired but may not capture every detail perfectly.
+
+## Built For
+
+The [MCP 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday) by Anthropic and Gradio.
+
+**Track**: Building MCP (MCP Server Implementation)
+
+## Social Media
+
+
+
+
+Made for the MCP community ❤️

app.py

@@ -1,3 +1,1361 @@
+<<<<<<< HEAD
+"""
+Meridian - Historical Image Generator
+
+Takes coordinates and dates, finds historical events, and generates images of those moments.
+Built for the Hugging Face MCP Hackathon.
+"""
+
+import os
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple
+
+import gradio as gr
+from PIL import Image
+from huggingface_hub import InferenceClient
+import google.generativeai as genai
+
+from services.history_service import (
+    build_event_context,
+    format_event_digest,
+    get_artifacts_for_year,
+    get_event_by_name,
+    get_event_by_slug,
+    get_event_by_qid,
+    get_events_by_coordinates,
+    get_events_response,
+    get_era_vocabulary,
+    get_region_context,
+    initialize_history,
+    search_events_globally,
+)
+
+# Import Wikidata service for MCP tools
+try:
+    from services.wikidata_service import (
+        mcp_search_historical_events,
+        mcp_get_event_by_qid,
+    )
+    WIKIDATA_MCP_AVAILABLE = True
+except ImportError:
+    WIKIDATA_MCP_AVAILABLE = False
+from services.prompt_parser import parse_prompt_context, ParsedPrompt
+
+
+def join_list(items: List[str], conjunction: str = "and") -> str:
+    cleaned = [item for item in items if item]
+    if not cleaned:
+        return ""
+    if len(cleaned) == 1:
+        return cleaned[0]
+    if len(cleaned) == 2:
+        return f"{cleaned[0]} {conjunction} {cleaned[1]}"
+    return ", ".join(cleaned[:-1]) + f", {conjunction} {cleaned[-1]}"
+
+
+def describe_time_of_day(hour: Optional[int]) -> str:
+    if hour is None:
+        return "ambient daylight with balanced, neutral lighting"
+    hour = int(hour) % 24
+    if 0 <= hour < 4:
+        return "pre-dawn darkness punctuated by sparse artificial lights"
+    if 4 <= hour < 6:
+        return "blue-hour twilight with faint glow along the horizon"
+    if 6 <= hour < 10:
+        return "soft morning light casting long, gentle shadows"
+    if 10 <= hour < 15:
+        return "bright midday sunlight with crisp contrast and vivid color"
+    if 15 <= hour < 18:
+        return "warm late-afternoon sun gilding the scene with golden highlights"
+    if 18 <= hour < 20:
+        return "dusk with saturated skies and streetlights beginning to glow"
+    if 20 <= hour < 23:
+        return "nighttime illumination from electric signage and floodlights"
+    return "deep night with high-contrast spotlights and reflective surfaces"
+
+
+def describe_season(latitude: float, month: Optional[int]) -> str:
+    if month is None or month < 1 or month > 12:
+        return "seasonal atmosphere typical for the region"
+    northern = latitude >= 0
+    if northern:
+        if month in [12, 1, 2]:
+            return "winter air with visible breath, bundled clothing, and muted vegetation"
+        if month in [3, 4, 5]:
+            return "spring freshness with blooming foliage and newly awakened colors"
+        if month in [6, 7, 8]:
+            return "summer warmth with lush greenery and vibrant skylines"
+        return "autumn chill with turning leaves and cool breezes"
+    else:
+        if month in [12, 1, 2]:
+            return "southern hemisphere summer with bright skies and humid air"
+        if month in [3, 4, 5]:
+            return "autumn hues with cooling evenings and amber light"
+        if month in [6, 7, 8]:
+            return "winter clarity with crisp air and softer daylight"
+        return "spring renewal with emerging blossoms and mild winds"
+
+
+def add_composition_cues(mood: str, event_type: str = "") -> str:
+    """Returns composition cues for the selected style."""
+    composition_map = {
+        "Documentary": "wide angle view, documentary photography style, centered composition",
+        "Dramatic": "dramatic perspective, cinematic framing, rule of thirds, leading lines",
+        "Artistic": "artistic composition, balanced framing, visual depth",
+        "Cinematic": "cinematic wide shot, dramatic shadows, foreground action, background architecture",
+        "Photojournalistic": "photojournalistic style, candid framing, natural lighting",
+        "Cartoon": "animated style, vibrant colors, cartoon illustration, bold outlines",
+        "Minecraft": "blocky pixelated style, minecraft aesthetic, cubic forms, voxel art",
+        "Retro": "vintage photography style, retro color grading, film grain, nostalgic atmosphere",
+        "Glitch": "digital glitch art, motion blur effects, halftone dot patterns, RGB channel separation, pixelated distortion, cyberpunk aesthetic, data corruption visual effects",
+    }
+    
+    base_cue = composition_map.get(mood, "wide angle view, cinematic framing")
+    
+    # Only add depth cues for photorealistic styles
+    if mood in ["Documentary", "Cinematic", "Dramatic", "Photojournalistic", "Artistic"]:
+        depth_cues = "foreground action, middle ground figures, background architecture, atmospheric depth"
+        return f"{base_cue}, {depth_cues}"
+    
+    return base_cue
+
+
+def build_event_sections(
+    event: dict,
+    time_desc: str,
+    season_desc: str,
+    mood: str,
+) -> Dict[str, str]:
+    """Builds prompt sections focusing on event, location, year, and time."""
+    vocab = get_era_vocabulary(event.get("year") or 0)
+    region_ctx = get_region_context((event.get("facets") or {}).get("region"))
+
+    # Extract event details
+    event_name = event.get("name", "Historical scene")
+    event_year = event.get("year", 0)
+    narrative = (event.get("narrative") or event.get("summary") or event.get("description") or "").strip()
+    actors = event.get("actors") or []
+    
+    # Get location context
+    region_name = (event.get("facets") or {}).get("region", "")
+    architecture = region_ctx.get("architecture") or vocab.get("architecture", "")
+    
+    # Build year/era marker (prominent)
+    if event_year < 0:
+        era_marker = f"{abs(event_year)} BCE"
+    elif event_year < 500:
+        era_marker = "ancient era"
+    elif event_year < 1500:
+        era_marker = "medieval era"
+    elif event_year < 1800:
+        era_marker = "early modern era"
+    elif event_year < 1900:
+        era_marker = "19th century"
+    else:
+        era_marker = f"{event_year}"
+    
+    # Get location name/region (prioritize location)
+    location_desc = ""
+    if region_name:
+        region_map = {
+            "western_europe": "Western Europe",
+            "eastern_europe": "Eastern Europe",
+            "north_america": "North America",
+            "south_america": "South America",
+            "east_asia": "East Asia",
+            "middle_east": "Middle East",
+            "africa": "Africa",
+        }
+        location_desc = region_map.get(region_name.lower(), region_name.replace("_", " ").title())
+    
+    # Simplify architecture description
+    architecture_lower = architecture.lower() if architecture else ""
+    if "roman" in architecture_lower:
+        arch_short = "Roman architecture"
+    elif "gothic" in architecture_lower:
+        arch_short = "Gothic architecture"
+    elif "medieval" in architecture_lower:
+        arch_short = "medieval architecture"
+    elif "asia" in region_name.lower() and event_year < 1900:
+        arch_short = "traditional Asian architecture"
+    else:
+        arch_short = architecture or "period architecture"
+    
+    # Extract key action from narrative (concise)
+    key_action = ""
+    if narrative:
+        # Get first short sentence or phrase
+        sentences = [s.strip() for s in narrative.split(".") if len(s.strip()) > 10 and len(s.strip()) < 80]
+        if sentences:
+            key_action = sentences[0]
+            # Trim if too long
+            if len(key_action) > 60:
+                key_action = key_action[:57] + "..."
+    
+    # Build focused scene: [Event] at [Location] in [Year] at [Time]: [Action]
+    # Make time prominent - include it in the main sentence
+    time_short = time_desc.split(",")[0] if "," in time_desc else time_desc  # Get first part of time description
+    
+    if location_desc:
+        if key_action:
+            scene_sentence = f"{event_name} at {location_desc} in {era_marker} at {time_short}: {key_action}"
+        else:
+            scene_sentence = f"{event_name} at {location_desc} in {era_marker} at {time_short}"
+    else:
+        if key_action:
+            scene_sentence = f"{event_name} in {era_marker} at {time_short}: {key_action}"
+        else:
+            scene_sentence = f"{event_name} in {era_marker} at {time_short}"
+    
+    # Essential participants only (concise)
+    if actors and len(actors) > 0:
+        main_actors = actors[:2]  # Limit to 2 most important
+        if len(main_actors) == 1:
+            participants_sentence = f"{main_actors[0]} present"
+        else:
+            participants_sentence = f"{main_actors[0]} and {main_actors[1]} present"
+    else:
+        participants_sentence = ""
+    
+    # Location architecture (concise, time already in main sentence)
+    if location_desc and arch_short:
+        location_sentence = f"{location_desc} with {arch_short}"
+    elif arch_short:
+        location_sentence = arch_short
+    else:
+        location_sentence = ""
+    
+    return {
+        "event_location_year": scene_sentence,  # Core: Event + Location + Year
+        "participants": participants_sentence,
+        "location_setting": location_sentence,
+    }
+
+
+def assemble_prompt_from_sections(sections: Dict[str, str], quality: str) -> str:
+    """Combines prompt sections into final prompt, keeping it 40-60 words."""
+    # Focused structure: [Event at Location in Year] [Participants] [Location/Setting] [Style/Quality]
+    parts = [
+        sections.get("event_location_year"),  # Core: Event + Location + Year (most important)
+        sections.get("participants"),  # Essential participants only
+        sections.get("location_setting"),  # Location architecture and time
+    ]
+    body = ". ".join(part for part in parts if part)
+    
+    # Add style/mood and quality tags at end (concise)
+    style_quality = f"{quality}"
+    result = f"{body}. {style_quality}".strip()
+    
+    # Ensure prompt is 40-60 words (target ~50 words)
+    word_count = len(result.split())
+    if word_count > 65:
+        # Trim if too long - keep core elements, reduce quality tags
+        words = result.split()
+        # Keep first 45 words (core content), add essential quality
+        core = " ".join(words[:45])
+        essential_quality = "historically accurate, photorealistic"
+        result = f"{core}. {essential_quality}"
+    elif word_count < 35:
+        # Expand slightly if too short - add more context
+        if not sections.get("participants"):
+            result = f"{body}. Historical figures visible. {style_quality}".strip()
+    
+    return result
+
+
+def build_fallback_prompt(
+    lat: float,
+    lon: float,
+    year: int,
+    month: int,
+    day: int,
+    hour: int,
+    mood: str,
+) -> Tuple[str, str]:
+    time_desc = describe_time_of_day(hour)
+    season_desc = describe_season(lat, month)
+    vocab = get_era_vocabulary(year)
+    artifact_titles = [artifact["title"] for artifact in get_artifacts_for_year(year, limit=3)]
+    sections = {
+        "scene": f"{mood} depiction of daily life near {lat:.2f}, {lon:.2f} in {year}.",
+        "participants": "Participants include residents, traders, and travelers in their everyday routines.",
+        "environment": (
+            f"Environment frames {vocab.get('architecture')} under {time_desc} and {season_desc}."
+        ),
+        "elements": (
+            f"Visible elements: {join_list(artifact_titles)}."
+            if artifact_titles
+            else f"Technology of the era includes {vocab.get('technology')} and {vocab.get('transport')}."
+        ),
+    }
+    # Style-appropriate quality tags
+    if mood in ["Cartoon", "Minecraft", "Retro", "Glitch"]:
+        quality_map = {
+            "Cartoon": "cartoon illustration style, vibrant colors, bold outlines, historically inspired",
+            "Minecraft": "minecraft blocky style, pixelated, cubic forms, historically themed",
+            "Retro": "retro vintage style, film grain, nostalgic color grading, historically accurate",
+            "Glitch": "digital glitch art style, cyberpunk aesthetic, data corruption effects, historically themed"
+        }
+        quality = quality_map.get(mood, f"{mood} style, historically inspired")
+    else:
+        quality = f"{mood} style, historically accurate, photorealistic, 8K"
+    prompt = assemble_prompt_from_sections(sections, quality)
+    hint = (
+        f"📍 {lat:.4f}, {lon:.4f} | 📅 {year}-{month:02d}-{day:02d} {hour:02d}:00\n"
+        "ℹ️ No curated event match found; using era vocabulary fallback."
+    )
+    return prompt, hint
+
+# Load environment variables
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+# ==========================
+# SSL Certificate Fix
+# ==========================
+# Fix SSL certificate issues on macOS/Anaconda
+try:
+    import certifi
+    cert_path = certifi.where()
+    if cert_path and os.path.exists(cert_path):
+        os.environ.setdefault("SSL_CERT_FILE", cert_path)
+        os.environ.setdefault("REQUESTS_CA_BUNDLE", cert_path)
+        os.environ.setdefault("CURL_CA_BUNDLE", cert_path)
+except ImportError:
+    pass
+
+# ==========================
+# Configuration
+# ==========================
+
+# Try both common environment variable names for HF token
+HF_TOKEN = os.getenv("HUGGINGFACE_API_TOKEN") or os.getenv("HF_TOKEN", "")
+GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "")
+
+# Display token status on startup
+print("\n" + "="*60)
+print("🔑 API Token Status:")
+print("="*60)
+if HF_TOKEN:
+    print(f"✅ HF_TOKEN: Found ({len(HF_TOKEN)} chars) - {HF_TOKEN[:10]}...")
+else:
+    print("❌ HF_TOKEN: Not found!")
+    print("   Set HUGGINGFACE_API_TOKEN or HF_TOKEN environment variable")
+
+if GEMINI_API_KEY:
+    print(f"✅ GEMINI_API_KEY: Found ({len(GEMINI_API_KEY)} chars) - {GEMINI_API_KEY[:10]}...")
+    genai.configure(api_key=GEMINI_API_KEY)
+else:
+    print("⚠️  GEMINI_API_KEY: Not found (prompts will use fallback)")
+print("="*60 + "\n")
+
+# Image generation models
+IMAGE_MODELS = {
+    "FLUX.1-dev (High Quality)": "black-forest-labs/FLUX.1-dev",
+    "FLUX.1-schnell (Fast)": "black-forest-labs/FLUX.1-schnell",
+}
+
+# ==========================
+# Negative Prompts by Era (Prevent Anachronisms)
+# ==========================
+
+NEGATIVE_PROMPTS_BY_ERA = {
+    (-5000, 500): "modern clothing, eyeglasses, wristwatches, cars, trains, airplanes, electric lights, smartphones, cameras, plastic, metal zippers, sneakers, jeans, t-shirts, hoodies, sunglasses, baseball caps, medieval armor, Renaissance art style",
+    (500, 1500): "Renaissance art style, modern clothing, eyeglasses, wristwatches, cars, trains, airplanes, electric lights, smartphones, cameras, plastic, metal zippers, sneakers, jeans, t-shirts, hoodies, sunglasses, baseball caps, printing press, gunpowder weapons",
+    (1500, 1800): "cars, motorcycles, airplanes, electric lights, smartphones, modern electronics, plastic materials, synthetic fabrics, LED screens, digital devices, neon signs, concrete buildings, steel skyscrapers, industrial machinery",
+    (1800, 1900): "cars, motorcycles, airplanes, electric lights, smartphones, modern electronics, plastic materials, synthetic fabrics, LED screens, digital devices, neon signs, concrete buildings, steel skyscrapers, modern vehicles",
+    (1900, 1940): "smartphones, laptops, computers, LED lights, jet aircraft, modern cars (post-1940), plastic bottles, digital screens, television, contemporary architecture, synthetic clothing, polyester, atomic age technology",
+    (1940, 1970): "smartphones, tablets, computers, personal electronics, LED billboards, 1980s fashion, digital displays, modern vehicles (post-1970), synthesizers, disco fashion, platform shoes, personal computers",
+    (1970, 2000): "smartphones, tablets, laptops, modern electronics (post-2000), contemporary fashion, LED screens, modern architecture (post-2000), flat screen monitors, wireless devices, social media",
+    (2000, 2100): "futuristic technology, holograms, flying cars, sci-fi elements, unrealistic technology, augmented reality interfaces, cyberpunk aesthetics, AI robots"
+}
+
+# FLUX-specific negative prompts (always included)
+FLUX_NEGATIVE_BASE = "cartoon, illustration, painting, drawing, sketch, low quality, blurry, distorted, watermark, text, signature, jpeg artifacts, pixelated, bad anatomy, deformed, ugly, duplicate, morbid, mutilated, extra fingers, mutated hands, poorly drawn hands, poorly drawn face, mutation, deformed, bad proportions, extra limbs, cloned face, disfigured, gross proportions, malformed limbs, missing arms, missing legs, extra arms, extra legs, fused fingers, too many fingers, long neck"
+
+def get_negative_prompt(year: int) -> str:
+    """Returns negative prompt to prevent anachronisms for the given year."""
+    era_negatives = ""
+    for (start, end), negatives in NEGATIVE_PROMPTS_BY_ERA.items():
+        if start <= year < end:
+            era_negatives = negatives
+            break
+    if not era_negatives:
+        era_negatives = NEGATIVE_PROMPTS_BY_ERA[(1970, 2000)]  # Default
+    
+    # Combine era-specific and FLUX base negatives
+    return f"{FLUX_NEGATIVE_BASE}, {era_negatives}"
+
+# ==========================
+# AI Prompt Generation
+# ==========================
+
+def generate_historical_prompt(
+    lat: float,
+    lon: float,
+    year: int,
+    month: int,
+    day: int,
+    hour: int,
+    mood: str = "Documentary",
+) -> Tuple[str, str]:
+    """Finds historical events and builds a prompt for image generation."""
+
+    # Find events near the coordinates, prioritizing exact year matches
+    events = get_events_by_coordinates(
+        lat, lon, year,
+        radius_km=400,
+        limit=4,
+        include_wikidata=True,
+        year_weight=1.5,
+    )
+    time_desc = describe_time_of_day(hour)
+    season_desc = describe_season(lat, month)
+
+    if events:
+        focus_event = events[0]
+        sections = build_event_sections(focus_event, time_desc, season_desc, mood)
+        # Style-appropriate quality tags
+        if mood in ["Cartoon", "Minecraft", "Retro", "Glitch"]:
+            quality_map = {
+                "Cartoon": "cartoon illustration style, vibrant colors, bold outlines, historically inspired",
+                "Minecraft": "minecraft blocky style, pixelated, cubic forms, historically themed",
+                "Retro": "retro vintage style, film grain, nostalgic color grading, historically accurate",
+                "Glitch": "digital glitch art style, cyberpunk aesthetic, data corruption effects, historically themed"
+            }
+            quality = quality_map.get(mood, f"{mood} style, historically inspired")
+        else:
+            quality = f"{mood} style, historically accurate, photorealistic, 8K"
+        prompt = assemble_prompt_from_sections(sections, quality)
+
+        # Show where the event came from
+        source = focus_event.get("source", "curated")
+        source_badge = "📚 Curated" if source == "curated" else "🌐 Wikidata"
+        qid = focus_event.get("qid", "")
+        source_info = f"{source_badge}"
+        if qid:
+            source_info += f" ({qid})"
+        
+        # Show how close the year match is
+        year_delta = focus_event.get("year_delta", 0)
+        if year_delta == 0:
+            year_match = "🎯 Exact year match!"
+        elif year_delta <= 2:
+            year_match = f"📅 ±{year_delta} year(s)"
+        elif year_delta <= 5:
+            year_match = f"📅 ~{year_delta} years"
+        elif year_delta <= 10:
+            year_match = f"📅 ~{year_delta} years apart"
+        else:
+            year_match = f"⚠️ {year_delta} years apart"
+
+        hint_lines = [
+            f"📍 {lat:.4f}, {lon:.4f} | 📅 {year}-{month:02d}-{day:02d} {hour:02d}:00",
+            (
+                f"🎯 Focus event: {focus_event['name']} ({focus_event.get('year')}) · "
+                f"{focus_event.get('distance_km')}km · {year_match} · {source_info}"
+            ),
+        ]
+        summary = focus_event.get("summary") or focus_event.get("narrative") or focus_event.get("description")
+        if summary:
+            hint_lines.append(f"📝 {summary[:200]}{'...' if len(summary) > 200 else ''}")
+        
+        # Show participants if available
+        participants = focus_event.get("actors") or focus_event.get("participants") or []
+        if participants:
+            hint_lines.append(f"👥 Participants: {', '.join(participants[:5])}")
+        
+        if len(events) > 1:
+            hint_lines.append("📚 Related possibilities:")
+            for related in events[1:]:
+                rel_source = "📚" if related.get("source") == "curated" else "🌐"
+                hint_lines.append(
+                    f"- {rel_source} {related['name']} ({related.get('year')}) · {related.get('distance_km')}km · "
+                    f"conf {related.get('match_confidence', 0):.2f}"
+                )
+        hint = "\n".join(hint_lines)
+        return prompt, hint
+
+    # Fallback when no curated event is close enough
+    return build_fallback_prompt(lat, lon, year, month, day, hour, mood)
+
+# ==========================
+# Image Generation
+# ==========================
+
+def generate_image(prompt: str, model_key: str, year: int = None, negative_prompt: str = None) -> Tuple[Optional[Image.Image], str]:
+    """Generates image using FLUX via Hugging Face API. Auto-generates negative prompts based on year if not provided."""
+    
+    if not HF_TOKEN:
+        error_msg = """❌ Hugging Face API token not configured!
+
+Please set one of these environment variables:
+• HUGGINGFACE_API_TOKEN='your_token_here'
+• HF_TOKEN='your_token_here'
+
+Get your token at: https://huggingface.co/settings/tokens"""
+        return None, error_msg
+    
+    model_id = IMAGE_MODELS.get(model_key, IMAGE_MODELS["FLUX.1-dev (High Quality)"])
+    
+    # Generate negative prompt if not provided and year is available
+    if negative_prompt is None and year is not None:
+        negative_prompt = get_negative_prompt(year)
+    
+    try:
+        client = InferenceClient(token=HF_TOKEN)
+        
+        start_time = datetime.now()
+        
+        # Build parameters
+        params = {
+            "prompt": prompt,
+            "model": model_id,
+            "width": 1024,
+            "height": 768,
+        }
+        
+        # Add negative prompt if available (FLUX supports it)
+        if negative_prompt:
+            params["negative_prompt"] = negative_prompt
+        
+        image = client.text_to_image(**params)
+        elapsed = (datetime.now() - start_time).total_seconds()
+        
+        status = f"✅ Generated in {elapsed:.1f}s using {model_key}"
+        if negative_prompt:
+            status += " (with era-appropriate exclusions)"
+        return image, status
+        
+    except Exception as e:
+        error_msg = f"❌ Generation failed: {str(e)}"
+        # Add helpful context for common errors
+        if "rate limit" in str(e).lower():
+            error_msg += "\n\n💡 Tip: Try FLUX.1-schnell (faster) or wait a few minutes."
+        elif "timeout" in str(e).lower():
+            error_msg += "\n\n💡 Tip: Model loading. Try again in 30 seconds."
+        return None, error_msg
+
+# ==========================
+# Main Workflow
+# ==========================
+
+def process_coordinates(lat: float, lon: float, year: int, month: int, day: int, hour: int, mood: str, model_key: str, custom_prompt: str = None):
+    """Main workflow: takes coordinates and date, generates prompt and image."""
+    
+    # Generate prompt or use custom one
+    status_parts = []
+    if custom_prompt and custom_prompt.strip():
+        prompt = custom_prompt.strip()
+        hint = f"📍 {lat:.4f}, {lon:.4f} | 📅 {year}-{month:02d}-{day:02d} {hour}:00 (Custom prompt)"
+        status_parts.append("✅ Using custom prompt")
+    else:
+        status_parts.append("🔍 Searching historical events...")
+        prompt, hint = generate_historical_prompt(lat, lon, year, month, day, hour, mood)
+        status_parts.append("✅ Prompt generated")
+    
+    # Generate the image
+    status_parts.append(f"🎨 Generating image with {model_key}...")
+    image, gen_status = generate_image(prompt, model_key, year=year)
+    status_parts.append(gen_status)
+    
+    # Build timeline of nearby events
+    status_parts.append("📚 Building historical timeline...")
+    events = get_events_by_coordinates(
+        lat, lon, year,
+        radius_km=500,
+        limit=5,
+        include_wikidata=True,
+        year_weight=1.5,
+    )
+    status_parts.append(f"✅ Found {len(events)} nearby events")
+    
+    status = " | ".join(status_parts)
+    
+    timeline_md = "### Nearby Historical Events\n\n"
+    if events:
+        for event in events:
+            source = event.get("source", "curated")
+            source_icon = "📚" if source == "curated" else "🌐"
+            qid = event.get("qid", "")
+            qid_link = f" [[{qid}](https://www.wikidata.org/wiki/{qid})]" if qid else ""
+            
+            # Year match indicator
+            year_delta = event.get("year_delta", 0)
+            if year_delta == 0:
+                year_badge = "🎯"
+            elif year_delta <= 5:
+                year_badge = "📅"
+            else:
+                year_badge = "⏳"
+            
+            timeline_md += (
+                f"**{event.get('year')}** {year_badge} — {source_icon} {event.get('name')}{qid_link} "
+                f"({event.get('distance_km')}km"
+            )
+            if year_delta > 0:
+                timeline_md += f" · ±{year_delta}yr"
+            timeline_md += f")\n\n"
+            
+            summary = event.get("summary") or event.get("narrative") or event.get("description")
+            if summary:
+                timeline_md += f"> {summary[:180]}{'...' if len(summary) > 180 else ''}\n\n"
+            
+            # Show participants for Wikidata events
+            participants = event.get("actors") or event.get("participants") or []
+            if participants and source == "wikidata":
+                timeline_md += f"_Participants: {', '.join(participants[:4])}_\n\n"
+    else:
+        timeline_md += "_No specific events found in database or Wikidata. Scene generated from era-appropriate context._"
+    
+    return image, prompt, hint, status, timeline_md
+
+# ==========================
+# Gradio UI
+# ==========================
+
+def create_app():
+    """Sets up the Gradio UI."""
+    
+    # Initialize history dataset and store
+    initialize_history()
+    
+    # Hybrid Theme: Warm Hero + Clean Readable Content
+    # Hero uses Peach/Lavender/Sky Blue gradient
+    # Content areas use high-contrast, professional styling
+    custom_css = """
+    :root {
+        /* Hero colors (warm palette) */
+        --peach: #ffad7a;
+        --peach-dark: #e8935c;
+        --lavender: #b8a9d9;
+        --sky-blue: #7ACCFF;
+        
+        /* Content colors (high contrast, professional) */
+        --bg-light: #f9fafb;
+        --surface: #ffffff;
+        --text-primary: #1f2937;
+        --text-secondary: #4b5563;
+        --text-muted: #6b7280;
+        --border-default: #e5e7eb;
+        --border-subtle: #f3f4f6;
+        
+        /* Accent (peach for interactive elements) */
+        --accent: #ffad7a;
+        --accent-hover: #e8935c;
+        --accent-subtle: rgba(255, 173, 122, 0.1);
+        
+        /* Shadows */
+        --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+        --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
+        --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.12);
+    }
+    
+    /* Base - Clean, readable */
+    body {
+        background: var(--bg-light) !important;
+        color: var(--text-primary) !important;
+        font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Display', 'Segoe UI', Roboto, sans-serif !important;
+        -webkit-font-smoothing: antialiased;
+    }
+    
+    .gradio-container {
+        max-width: 100% !important;
+        background: var(--bg-light) !important;
+    }
+    
+    /* ========== HERO - Warm gradient (kept from new design) ========== */
+    .hero {
+        text-align: center;
+        padding: 2.5rem 2rem;
+        background: linear-gradient(135deg, var(--peach) 0%, var(--lavender) 50%, var(--sky-blue) 100%);
+        border-radius: 20px;
+        margin: 1rem;
+        box-shadow: var(--shadow-lg), 0 0 30px rgba(255, 173, 122, 0.2);
+        position: relative;
+        overflow: hidden;
+    }
+    
+    .hero::before {
+        content: '';
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background: radial-gradient(ellipse at 30% 20%, rgba(255,255,255,0.35) 0%, transparent 50%);
+        pointer-events: none;
+    }
+    
+    .hero h1 {
+        font-size: 2.75rem;
+        font-weight: 700;
+        color: #ffffff;
+        margin-bottom: 0.5rem;
+        text-shadow: 0 2px 8px rgba(0,0,0,0.15);
+        letter-spacing: -0.02em;
+        position: relative;
+    }
+    
+    .hero p {
+        color: rgba(255, 255, 255, 0.95);
+        font-size: 1.1rem;
+        font-weight: 450;
+        position: relative;
+    }
+    
+    /* ========== CONTENT AREAS - Clean, high contrast ========== */
+    
+    /* Layout */
+    .main-grid {
+        display: grid;
+        grid-template-columns: 320px 1fr;
+        gap: 1.5rem;
+        padding: 1rem;
+    }
+    
+    /* Sidebar - Clean white */
+    .sidebar {
+        background: var(--surface);
+        border-radius: 12px;
+        padding: 1.5rem;
+        border: 1px solid var(--border-default);
+        box-shadow: var(--shadow-md);
+        height: fit-content;
+        position: sticky;
+        top: 1rem;
+    }
+    
+    /* Main Panel - Clean white */
+    .main-panel {
+        background: var(--surface);
+        border-radius: 12px;
+        padding: 1.5rem;
+        border: 1px solid var(--border-default);
+        box-shadow: var(--shadow-md);
+    }
+    
+    /* Inputs - Clean with peach focus */
+    input, select, textarea {
+        background: var(--bg-light) !important;
+        border: 1px solid var(--border-default) !important;
+        color: var(--text-primary) !important;
+        border-radius: 8px !important;
+        transition: all 0.15s ease !important;
+    }
+    
+    input:focus, select:focus, textarea:focus {
+        border-color: var(--accent) !important;
+        box-shadow: 0 0 0 3px var(--accent-subtle) !important;
+        outline: none !important;
+    }
+    
+    /* Buttons - Peach gradient (elegant touch) */
+    button {
+        background: linear-gradient(135deg, var(--accent) 0%, var(--accent-hover) 100%) !important;
+        color: #ffffff !important;
+        font-weight: 600 !important;
+        border: none !important;
+        border-radius: 10px !important;
+        padding: 0.75rem 1.5rem !important;
+        transition: all 0.2s ease !important;
+        box-shadow: 0 2px 8px rgba(255, 173, 122, 0.3) !important;
+    }
+    
+    button:hover {
+        background: linear-gradient(135deg, var(--accent-hover) 0%, #d67d45 100%) !important;
+        transform: translateY(-1px) !important;
+        box-shadow: 0 4px 16px rgba(255, 173, 122, 0.4) !important;
+    }
+    
+    /* Labels - High contrast */
+    label {
+        color: var(--text-secondary) !important;
+        font-weight: 500 !important;
+        font-size: 0.875rem !important;
+    }
+    
+    /* Section headers - Clear hierarchy */
+    .markdown-text h3, h3 {
+        color: var(--text-primary) !important;
+        font-weight: 600 !important;
+        font-size: 1rem !important;
+        margin-bottom: 0.5rem !important;
+    }
+    
+    /* All markdown text - Ensure readability */
+    .markdown-text, .markdown-text p, .markdown-text span {
+        color: var(--text-primary) !important;
+    }
+    
+    .markdown-text strong {
+        color: var(--text-primary) !important;
+        font-weight: 600 !important;
+    }
+    
+    /* Image container - Enhanced with animations */
+    .gr-image {
+        border-radius: 12px !important;
+        border: 1px solid var(--border-default) !important;
+        box-shadow: var(--shadow-md) !important;
+        transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1) !important;
+        opacity: 0;
+        animation: fadeInImage 0.6s ease-out forwards !important;
+    }
+    
+    @keyframes fadeInImage {
+        from {
+            opacity: 0;
+            transform: translateY(10px) scale(0.98);
+        }
+        to {
+            opacity: 1;
+            transform: translateY(0) scale(1);
+        }
+    }
+    
+    .gr-image:hover {
+        border-color: var(--accent) !important;
+        box-shadow: 0 8px 24px rgba(255, 173, 122, 0.3) !important;
+        transform: translateY(-2px) scale(1.01) !important;
+    }
+    
+    /* Hint/status text - Subtle background, readable text with smooth transitions */
+    .hint-text {
+        font-size: 0.9rem;
+        color: var(--text-secondary);
+        padding: 0.875rem 1rem;
+        background: var(--bg-light);
+        border-radius: 8px;
+        border: 1px solid var(--border-default);
+        margin-top: 0.5rem;
+        line-height: 1.6;
+        transition: all 0.3s ease !important;
+        animation: slideInHint 0.4s ease-out !important;
+    }
+    
+    @keyframes slideInHint {
+        from {
+            opacity: 0;
+            transform: translateX(-10px);
+        }
+        to {
+            opacity: 1;
+            transform: translateX(0);
+        }
+    }
+    
+    /* Accordion */
+    .gr-accordion {
+        background: var(--surface) !important;
+        border: 1px solid var(--border-default) !important;
+        border-radius: 8px !important;
+    }
+    
+    /* Blockquotes - Subtle lavender touch */
+    blockquote, .markdown-text blockquote {
+        border-left: 3px solid var(--lavender) !important;
+        background: #faf9fc !important;
+        padding: 0.75rem 1rem !important;
+        margin: 0.5rem 0 !important;
+        border-radius: 0 6px 6px 0 !important;
+        color: var(--text-secondary) !important;
+    }
+    
+    /* Links - Sky blue */
+    a {
+        color: #2563eb !important;
+        text-decoration: none !important;
+    }
+    
+    a:hover {
+        color: var(--accent-hover) !important;
+        text-decoration: underline !important;
+    }
+    
+    /* Slider */
+    input[type="range"] {
+        accent-color: var(--accent) !important;
+    }
+    
+    /* Loading states - Enhanced */
+    .generating {
+        position: relative;
+        overflow: hidden;
+    }
+
+    .generating::after {
+        content: '';
+        position: absolute;
+        top: 0;
+        left: -100%;
+        width: 100%;
+        height: 100%;
+        background: linear-gradient(90deg, transparent, rgba(255,173,122,0.2), transparent);
+        animation: loading 1.5s infinite;
+    }
+
+    @keyframes loading {
+        0% { left: -100%; }
+        100% { left: 100%; }
+    }
+
+    /* Skeleton loader for image placeholder */
+    .image-skeleton {
+        width: 100%;
+        height: 600px;
+        background: linear-gradient(90deg, 
+            var(--bg-light) 0%, 
+            var(--border-subtle) 50%, 
+            var(--bg-light) 100%);
+        background-size: 200% 100%;
+        border-radius: 12px;
+        animation: skeleton-loading 1.5s ease-in-out infinite;
+    }
+
+    @keyframes skeleton-loading {
+        0% { background-position: 200% 0; }
+        100% { background-position: -200% 0; }
+    }
+
+    /* Progress indicator */
+    .progress-bar {
+        height: 4px;
+        background: linear-gradient(90deg, var(--accent), var(--lavender));
+        border-radius: 2px;
+        animation: progress 2s ease-in-out infinite;
+        margin: 1rem 0;
+    }
+
+    @keyframes progress {
+        0%, 100% { transform: scaleX(0.3); transform-origin: left; }
+        50% { transform: scaleX(1); transform-origin: left; }
+    }
+
+    /* Status text with pulse animation */
+    .status-generating {
+        color: var(--accent) !important;
+        font-weight: 500 !important;
+        animation: pulse 2s ease-in-out infinite !important;
+    }
+
+    @keyframes pulse {
+        0%, 100% { opacity: 1; }
+        50% { opacity: 0.7; }
+    }
+
+    /* Button active state */
+    button:active {
+        transform: translateY(0) scale(0.98) !important;
+        transition: transform 0.1s ease !important;
+    }
+
+    /* Panel entrance animation */
+    .main-panel, .sidebar {
+        animation: fadeInPanel 0.5s ease-out !important;
+    }
+
+    @keyframes fadeInPanel {
+        from {
+            opacity: 0;
+            transform: translateY(20px);
+        }
+        to {
+            opacity: 1;
+            transform: translateY(0);
+        }
+    }
+
+    /* Smooth text transitions */
+    .markdown-text {
+        transition: opacity 0.3s ease !important;
+    }
+
+    /* Footer */
+    footer {
+        display: none !important;
+    }
+    
+    /* Responsive */
+    @media (max-width: 768px) {
+        .main-grid {
+            grid-template-columns: 1fr;
+        }
+        
+        .sidebar {
+            position: static;
+        }
+        
+        .hero h1 {
+            font-size: 2rem;
+        }
+    }
+    """
+    
+    with gr.Blocks(title="Meridian — Historical Image Generator", css=custom_css) as demo:
+        
+        # Hero
+        gr.HTML("""
+        <div class="hero">
+            <h1>🌍 Meridian</h1>
+            <p>Generate historically accurate scenes from geospatial coordinates and date/time inputs</p>
+        </div>
+        """)
+        
+        with gr.Row(elem_classes="main-grid"):
+            
+            # Left Sidebar: Inputs
+            with gr.Column(scale=1, elem_classes="sidebar"):
+                gr.Markdown("### ✍️ Custom Prompt")
+                prompt_override = gr.Textbox(
+                    label="Describe the scene (optional)",
+                    placeholder="Create an image at 31.7785° N, 35.2296° E, April 3, 33 CE, 15:00 hours",
+                    lines=4,
+                )
+                gr.Markdown("_When filled, coordinate inputs are locked so the prompt takes precedence._")
+
+                gr.Markdown("### 📍 Coordinates")
+                latitude = gr.Number(label="Latitude", value=52.5163, step=0.0001)
+                longitude = gr.Number(label="Longitude", value=13.3777, step=0.0001)
+                
+                gr.Markdown("### 📅 Date & Time")
+                year = gr.Number(label="Year", value=1989, precision=0)
+                month = gr.Number(label="Month (1-12)", value=11, precision=0, minimum=1, maximum=12)
+                day = gr.Number(label="Day (1-31)", value=9, precision=0, minimum=1, maximum=31)
+                hour = gr.Slider(label="Hour (0-23)", minimum=0, maximum=23, value=23, step=1)
+                
+                gr.Markdown("### 🎨 Style")
+                mood = gr.Dropdown(
+                    label="Mood/Style",
+                    choices=["Documentary", "Cinematic", "Photojournalistic", "Dramatic", "Cartoon", "Minecraft", "Retro", "Glitch"],
+                    value="Documentary"
+                )
+                
+                model_choice = gr.Dropdown(
+                    label="Model",
+                    choices=list(IMAGE_MODELS.keys()),
+                    value="FLUX.1-dev (High Quality)"
+                )
+                
+                generate_btn = gr.Button("🎬 Generate Image", variant="primary", size="lg")
+            
+            # Right Main Panel: Outputs
+            with gr.Column(scale=3, elem_classes="main-panel"):
+                
+                hint_display = gr.Markdown(
+                    "Enter coordinates and date/time *or* supply a custom prompt, then click Generate.",
+                    elem_classes="hint-text",
+                )
+                
+                gr.Markdown("### 📝 Scene Description")
+                gr.Markdown("_Generated prompt (appears after image generation, editable for regeneration):_")
+                prompt_box = gr.Textbox(
+                    label="",
+                    lines=6,
+                    placeholder="Prompt will appear here after generation. You can edit it and regenerate.",
+                    show_label=False
+                )
+                
+                gr.Markdown("### 🖼️ Generated Image")
+                image_output = gr.Image(
+                    label="", 
+                    show_label=False, 
+                    height=600,
+                    type="pil"
+                )
+                
+                status_display = gr.Markdown("_Ready to generate_", elem_classes="status-display")
+                
+                # How It Works - Full width section (same spacing as Generated Image section above)
+                gr.Markdown("### 💡 How It Works")
+                gr.Markdown("""
+                Meridian transforms geographic coordinates and dates into historically accurate visual scenes through a unique three-step process:
+                
+                1. **Historical Event Discovery**: When you provide coordinates and a date, Meridian searches through curated historical databases and Wikidata to find events that occurred near that location and time. Using Haversine distance calculations (which account for Earth's curvature), the system identifies the most relevant historical events, prioritizing those that match your exact year.
+                
+                2. **Intelligent Prompt Generation**: Once a historical event is identified, Meridian creates a focused, detailed description that emphasizes the event name, location, and year—the three most critical elements for accurate image generation. The system considers time of day (affecting lighting), season, regional architecture, and key participants to build a vivid scene description.
+                
+                3. **Photorealistic Image Creation**: The generated prompt is sent to FLUX.1-dev, an advanced image generation model, which creates a historically accurate scene. Negative prompts automatically prevent anachronisms (like modern technology appearing in ancient scenes), ensuring period-appropriate results.
+                
+                All of this happens automatically—you simply enter coordinates and a date, or describe what you're looking for in natural language.
+                """)
+                
+                # Technical Capabilities - Full width section (same spacing as Generated Image section)
+                gr.Markdown("### ⚙️ Technical Capabilities")
+                gr.Markdown("""
+                **Solving the Geospatial Challenge**: Traditional image generation models struggle with coordinates because they tokenize numbers like "52.5163" as separate symbols rather than understanding them as geographic locations. Meridian bridges this gap by maintaining a structured geospatial-historical database that maps precise coordinates to historical events, then translating those events into rich semantic descriptions that image models understand.
+                
+                **Dual Data Sources**: Meridian combines a curated database of pivotal historical events with real-time Wikidata queries, providing both quality (hand-selected events with rich metadata) and breadth (comprehensive coverage of global history). Events are scored by geographic proximity, temporal accuracy, and source reliability.
+                
+                **Year-Weighted Matching**: The system prioritizes events that match your exact year over nearby events from different time periods. This ensures that when you request "Rome, 44 BCE," you get Julius Caesar's assassination, not a medieval event that happened at the same coordinates centuries later.
+                
+                **Period-Accurate Generation**: Negative prompts automatically exclude anachronistic elements based on the event's era. For example, ancient scenes won't include modern clothing or technology, while 19th-century scenes exclude digital devices. The system also adapts architectural styles, clothing, and technology to match the historical period.
+                
+                **Time-Aware Details**: Meridian considers the specific hour you provide (affecting lighting—dawn, midday, dusk, or night) and the month/latitude combination (determining season and atmospheric conditions) to create scenes that feel authentic to the moment in history.
+                
+                **MCP Integration**: Through Model Context Protocol, Meridian can be called programmatically by AI assistants like Claude, enabling automated historical visualization workflows for education, research, and content creation.
+                """)
+                
+                with gr.Accordion("📜 Historical Timeline", open=False):
+                    timeline_display = gr.Markdown("Nearby events will appear here after generation.")
+        
+        def on_prompt_override_change(text):
+            interactive = not bool(text.strip())
+            update = gr.update(interactive=interactive)
+            return update, update, update, update, update, gr.update(interactive=interactive)
+
+        prompt_override.change(
+            fn=on_prompt_override_change,
+            inputs=[prompt_override],
+            outputs=[latitude, longitude, year, month, day, hour],
+        )
+
+        # Event handler
+        def on_generate(prompt_override_text, lat, lon, yr, mon, dy, hr, mood_val, model_val, prompt_box_text):
+            lat_val = float(lat) if lat is not None else 0.0
+            lon_val = float(lon) if lon is not None else 0.0
+            year_val = int(yr)
+            month_val = int(mon)
+            day_val = int(dy)
+            hour_val = int(hr)
+            custom_text = prompt_box_text
+            derived_note = ""
+
+            if prompt_override_text and prompt_override_text.strip():
+                custom_text = prompt_override_text.strip()
+                parsed: ParsedPrompt = parse_prompt_context(custom_text)
+                if parsed.lat is not None and parsed.lon is not None and parsed.confidence >= 0.35:
+                    lat_val = parsed.lat
+                    lon_val = parsed.lon
+                    if parsed.year is not None:
+                        year_val = parsed.year
+                    if parsed.month is not None:
+                        month_val = parsed.month
+                    if parsed.day is not None:
+                        day_val = parsed.day
+                    if parsed.hour is not None:
+                        hour_val = parsed.hour % 24
+                    derived_note = (
+                        f"🧭 Parsed from prompt (confidence {parsed.confidence:.2f}) · "
+                        f"{lat_val:.4f}, {lon_val:.4f}, year {year_val}"
+                    )
+                else:
+                    derived_note = "⚠️ Could not confidently parse prompt context; using manual inputs."
+
+            image, prompt, hint, status, timeline = process_coordinates(
+                lat_val, lon_val, year_val, month_val, day_val, hour_val, mood_val, model_val, custom_text
+            )
+
+            if derived_note:
+                hint = f"{hint}\n{derived_note}"
+            if derived_note.startswith("⚠️"):
+                status = f"{status}\n{derived_note}"
+            elif derived_note.startswith("🧭"):
+                status = f"{status}\nInterpreted prompt context successfully."
+                timeline = timeline.replace(
+                    "### Nearby Historical Events",
+                    f"### Nearby Historical Events\n\n_Prompt-derived coordinates:_ {lat_val:.4f}, {lon_val:.4f}",
+                    1,
+                )
+
+            return image, prompt, hint, status, timeline
+
+        generate_btn.click(
+            fn=on_generate,
+            inputs=[prompt_override, latitude, longitude, year, month, day, hour, mood, model_choice, prompt_box],
+            outputs=[image_output, prompt_box, hint_display, status_display, timeline_display]
+        )
+    
+    return demo
+
+# ==========================
+# MCP Server Support
+# ==========================
+
+def mcp_generate_from_coordinates(
+    latitude: float,
+    longitude: float,
+    year: int,
+    month: int = 1,
+    day: int = 1,
+    hour: int = 12,
+    mood: str = "Documentary",
+    model: str = "FLUX.1-dev (High Quality)",
+) -> Dict:
+    """MCP tool: generates image from coordinates and date."""
+    try:
+        nearby_events = get_events_by_coordinates(
+            latitude, longitude, year, radius_km=300, limit=5
+        )
+        image, prompt, hint, status, timeline = process_coordinates(
+            latitude,
+            longitude,
+            year,
+            month,
+            day,
+            hour,
+            mood,
+            model,
+        )
+        
+        return {
+            "success": True,
+            "prompt": prompt,
+            "hint": hint,
+            "status": status,
+            "image_generated": image is not None,
+            "events": [format_event_digest(event) for event in nearby_events],
+            "timeline_markdown": timeline,
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+
+def mcp_get_events_by_coordinates(
+    latitude: float,
+    longitude: float,
+    year: int,
+    radius_km: float = 250.0,
+    limit: int = 5,
+) -> Dict:
+    """MCP tool: finds nearby historical events."""
+    try:
+        payload = get_events_response(latitude, longitude, year, radius_km=radius_km, limit=limit)
+        payload["success"] = True
+        return payload
+    except Exception as exc:
+        return {"success": False, "error": str(exc)}
+
+
+def mcp_get_event_context(identifier: str) -> Dict:
+    """MCP tool: gets detailed info about an event by name or slug."""
+    event = get_event_by_slug(identifier)
+    if not event:
+        event = get_event_by_name(identifier)
+    if not event:
+        return {"success": False, "error": f"Event '{identifier}' not found"}
+
+    context = build_event_context(event)
+    context["artifacts"] = get_artifacts_for_year(event.get("year", 0))
+    context["source"] = event.get("source", "curated")
+    return {"success": True, "context": context}
+
+
+def mcp_search_wikidata_events(
+    latitude: float,
+    longitude: float,
+    year: int,
+    radius_km: float = 300.0,
+    limit: int = 10,
+) -> Dict:
+    """MCP tool: searches Wikidata for events at coordinates and year."""
+    if not WIKIDATA_MCP_AVAILABLE:
+        return {
+            "success": False,
+            "error": "Wikidata service not available",
+        }
+    
+    return mcp_search_historical_events(
+        latitude=latitude,
+        longitude=longitude,
+        year=year,
+        radius_km=radius_km,
+        limit=limit,
+    )
+
+
+def mcp_get_wikidata_event(qid: str) -> Dict:
+    """MCP tool: gets Wikidata event details by QID."""
+    if not WIKIDATA_MCP_AVAILABLE:
+        return {
+            "success": False,
+            "error": "Wikidata service not available",
+        }
+    
+    return mcp_get_event_by_qid(qid)
+
+
+def mcp_search_events_globally(
+    latitude: float,
+    longitude: float,
+    year: int,
+    radius_km: float = 500.0,
+    limit: int = 10,
+) -> Dict:
+    """MCP tool: searches for events with wider radius, combining curated and Wikidata data."""
+    try:
+        events = search_events_globally(
+            lat=latitude,
+            lon=longitude,
+            year=year,
+            radius_km=radius_km,
+            limit=limit,
+        )
+        return {
+            "success": True,
+            "query": {
+                "latitude": latitude,
+                "longitude": longitude,
+                "year": year,
+                "radius_km": radius_km,
+            },
+            "count": len(events),
+            "events": [format_event_digest(e) for e in events],
+            "sources": list(set(e.get("source", "curated") for e in events)),
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+# ==========================
+# Launch
+# ==========================
+
+def find_available_port(start_port=7860, max_attempts=10):
+    """Find an available port starting from start_port"""
+    import socket
+    for i in range(max_attempts):
+        port = start_port + i
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            sock.bind(('0.0.0.0', port))
+            sock.close()
+            return port
+        except OSError:
+            sock.close()
+            continue
+    return None  # Fall back to Gradio's auto port selection
+
+if __name__ == "__main__":
+    app = create_app()
+    # Allow port override via environment variable
+    default_port = int(os.getenv("GRADIO_SERVER_PORT", "7860"))
+    port = find_available_port(default_port)
+    
+    if port is None:
+        print(f"⚠️  Port {default_port} and nearby ports are in use. Using auto port selection.")
+        app.launch(
+            server_name="0.0.0.0",
+            share=False
+        )
+    else:
+        if port != default_port:
+            print(f"ℹ️  Port {default_port} was in use. Using port {port} instead.")
+        app.launch(
+            server_name="0.0.0.0",
+            server_port=port,
+            share=False
+        )
+
+=======
 import gradio as gr
 
 def greet(name):
@@ -5,3 +1363,4 @@ def greet(name):
 
 demo = gr.Interface(fn=greet, inputs="text", outputs="text")
 demo.launch()
+>>>>>>> 10b576d913b770a8ef9e28663b846f8cecc5a3fc

history_service.py

@@ -0,0 +1,969 @@
+from __future__ import annotations
+
+import json
+import math
+import sqlite3
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+# Import Wikidata service for remote lookups
+try:
+    from services.wikidata_service import (
+        search_events_by_geo_time as wikidata_search,
+        get_event_detail as wikidata_get_detail,
+        search_events_by_name as wikidata_search_by_name,
+    )
+    WIKIDATA_AVAILABLE = True
+except ImportError:
+    WIKIDATA_AVAILABLE = False
+    print("[history_service] Wikidata service not available, using curated data only")
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+DATA_DIR = ROOT_DIR / "data"
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+DB_PATH = DATA_DIR / "meridian_history.db"
+
+# Wikidata settings
+ENABLE_WIKIDATA_FALLBACK = True
+WIKIDATA_CONFIDENCE_THRESHOLD = 0.5
+
+EVENT_SCHEMA_VERSION = 2
+EVENT_EXTRA_COLUMNS: Dict[str, str] = {
+    "slug": "TEXT",
+    "summary": "TEXT",
+    "narrative": "TEXT",
+    "start_year": "INTEGER",
+    "end_year": "INTEGER",
+    "month": "INTEGER",
+    "day": "INTEGER",
+    "themes": "TEXT",
+    "actors": "TEXT",
+    "artifacts": "TEXT",
+    "visual_motifs": "TEXT",
+    "facets": "TEXT",
+    "sources": "TEXT",
+    "time_range": "TEXT",
+    "geo_anchor": "TEXT",
+    "confidence": "REAL",
+    "relationships": "TEXT",
+}
+
+
+def _get_connection() -> sqlite3.Connection:
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def _serialize(value: object) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _deserialize(value: Optional[str], default):
+    if value is None or value == "":
+        return default
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        return default
+
+
+def ensure_schema() -> None:
+    conn = _get_connection()
+    cursor = conn.cursor()
+
+    cursor.execute(
+        """
+        CREATE TABLE IF NOT EXISTS events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT UNIQUE,
+            year INTEGER,
+            lat REAL,
+            lon REAL
+        )
+        """
+    )
+
+    cursor.execute(
+        """
+        CREATE TABLE IF NOT EXISTS schema_meta (
+            key TEXT PRIMARY KEY,
+            value TEXT
+        )
+        """
+    )
+
+    # Add new columns if missing
+    cursor.execute("PRAGMA table_info(events)")
+    existing_columns = {row["name"] for row in cursor.fetchall()}
+    for column, column_type in EVENT_EXTRA_COLUMNS.items():
+        if column not in existing_columns:
+            cursor.execute(f"ALTER TABLE events ADD COLUMN {column} {column_type}")
+
+    # Update schema version
+    cursor.execute(
+        """
+        INSERT INTO schema_meta(key, value)
+        VALUES('event_schema_version', ?)
+        ON CONFLICT(key) DO UPDATE SET value=excluded.value
+        """,
+        (str(EVENT_SCHEMA_VERSION),),
+    )
+
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_events_year ON events(year)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_events_coordinates ON events(lat, lon)")
+
+    conn.commit()
+    conn.close()
+
+
+def seed_curated_events(force_refresh: bool = False) -> None:
+    conn = _get_connection()
+    cursor = conn.cursor()
+
+    if force_refresh:
+        cursor.execute("DELETE FROM events")
+
+    for event in CURATED_EVENTS:
+        cursor.execute(
+            """
+            INSERT OR IGNORE INTO events (
+                name, slug, year, start_year, end_year, month, day,
+                lat, lon, summary, narrative, themes, actors, artifacts,
+                visual_motifs, facets, sources, time_range, geo_anchor,
+                confidence, relationships
+            ) VALUES (
+                :name, :slug, :year, :start_year, :end_year, :month, :day,
+                :lat, :lon, :summary, :narrative, :themes, :actors, :artifacts,
+                :visual_motifs, :facets, :sources, :time_range, :geo_anchor,
+                :confidence, :relationships
+            )
+            """,
+            {
+                "name": event["name"],
+                "slug": event.get("slug") or event["name"].lower().replace(" ", "_"),
+                "year": event.get("year"),
+                "start_year": event.get("start_year", event.get("year")),
+                "end_year": event.get("end_year", event.get("year")),
+                "month": event.get("month"),
+                "day": event.get("day"),
+                "lat": event.get("lat"),
+                "lon": event.get("lon"),
+                "summary": event.get("summary"),
+                "narrative": event.get("narrative"),
+                "themes": _serialize(event.get("themes", [])),
+                "actors": _serialize(event.get("actors", [])),
+                "artifacts": _serialize(event.get("artifacts", [])),
+                "visual_motifs": _serialize(event.get("visual_motifs", [])),
+                "facets": _serialize(event.get("facets", {})),
+                "sources": _serialize(event.get("sources", [])),
+                "time_range": _serialize(event.get("time_range", {})),
+                "geo_anchor": _serialize(event.get("geo_anchor", {})),
+                "confidence": event.get("confidence", 0.85),
+                "relationships": _serialize(event.get("relationships", {})),
+            },
+        )
+
+    conn.commit()
+    conn.close()
+
+
+def initialize_history(force_refresh: bool = False) -> None:
+    ensure_schema()
+    seed_curated_events(force_refresh=force_refresh)
+
+
+def load_events_from_db() -> List[dict]:
+    conn = _get_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT * FROM events")
+    rows = cursor.fetchall()
+    conn.close()
+
+    events = []
+    for row in rows:
+        event = dict(row)
+        event["themes"] = _deserialize(event.get("themes"), [])
+        event["actors"] = _deserialize(event.get("actors"), [])
+        event["artifacts"] = _deserialize(event.get("artifacts"), [])
+        event["visual_motifs"] = _deserialize(event.get("visual_motifs"), [])
+        event["facets"] = _deserialize(event.get("facets"), {})
+        event["sources"] = _deserialize(event.get("sources"), [])
+        event["time_range"] = _deserialize(event.get("time_range"), {})
+        event["geo_anchor"] = _deserialize(event.get("geo_anchor"), {})
+        event["relationships"] = _deserialize(event.get("relationships"), {})
+        events.append(event)
+
+    return events
+
+
+def haversine_distance(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    radius = 6371.0
+    phi1, phi2 = math.radians(lat1), math.radians(lat2)
+    delta_phi = math.radians(lat2 - lat1)
+    delta_lambda = math.radians(lon2 - lon1)
+
+    a = (
+        math.sin(delta_phi / 2) ** 2
+        + math.cos(phi1) * math.cos(phi2) * math.sin(delta_lambda / 2) ** 2
+    )
+    c = 2 * math.atan2(math.sqrt(a), math.sqrt(max(0.0, 1 - a)))
+    return radius * c
+
+
+def _compute_match_score(
+    event: dict,
+    lat: float,
+    lon: float,
+    year: int,
+    year_weight: float = 1.0,
+) -> Tuple[float, float, float, float]:
+    """
+    Compute match score for an event based on distance and year.
+    
+    Args:
+        event: Event dictionary
+        lat: Query latitude
+        lon: Query longitude
+        year: Query year
+        year_weight: Weight for year matching (0.0-2.0)
+            - 0.0 = distance only
+            - 1.0 = balanced (default)
+            - 2.0 = strongly prefer year matches
+    
+    Returns:
+        Tuple of (distance_km, year_delta, confidence, match_score)
+    """
+    event_year = event.get("year") or year
+    event_lat = event.get("lat") or lat
+    event_lon = event.get("lon") or lon
+    
+    distance = haversine_distance(lat, lon, event_lat, event_lon)
+    year_delta = abs(event_year - year)
+    base_confidence = event.get("confidence", 0.8)
+    
+    # Year-weighted scoring:
+    # - Exact year match (delta=0): massive bonus
+    # - Within 5 years: strong bonus
+    # - Within 10 years: moderate bonus
+    # - Beyond 10 years: penalty increases
+    
+    if year_delta == 0:
+        year_score = -50 * year_weight  # Big bonus for exact year
+    elif year_delta <= 2:
+        year_score = -30 * year_weight  # Strong bonus for ±2 years
+    elif year_delta <= 5:
+        year_score = -15 * year_weight  # Good bonus for ±5 years
+    elif year_delta <= 10:
+        year_score = 0  # Neutral for ±10 years
+    else:
+        year_score = year_delta * 3 * year_weight  # Penalty for distant years
+    
+    # Distance scoring (normalized):
+    # - Within 50km: strong bonus
+    # - Within 200km: moderate bonus
+    # - Beyond 500km: penalty
+    if distance < 50:
+        distance_score = -20 * (1 - year_weight * 0.3)  # Bonus, reduced if year-weighted
+    elif distance < 200:
+        distance_score = distance * 0.1
+    else:
+        distance_score = distance * 0.2 * (1 - year_weight * 0.3)  # Reduced penalty if year-weighted
+    
+    # Combined score (lower is better)
+    match_score = distance_score + year_score
+    
+    # Confidence calculation
+    confidence = base_confidence
+    if year_delta == 0:
+        confidence += 0.15
+    elif year_delta <= 5:
+        confidence += 0.08
+    
+    if distance < 100:
+        confidence += 0.1
+    elif distance < 300:
+        confidence += 0.05
+    
+    confidence = max(0.0, min(0.99, confidence))
+    
+    return distance, year_delta, confidence, match_score
+
+
+def get_events_by_coordinates(
+    lat: float,
+    lon: float,
+    year: int,
+    radius_km: float = 250.0,
+    limit: int = 5,
+    include_wikidata: bool = True,
+    year_weight: float = 1.5,
+) -> List[dict]:
+    """
+    Get historical events near coordinates and year.
+    
+    First searches curated local database, then optionally queries Wikidata
+    for additional results if enabled and local results are insufficient.
+    
+    Args:
+        lat: Latitude
+        lon: Longitude
+        year: Target year (negative for BCE)
+        radius_km: Search radius in kilometers
+        limit: Maximum number of results
+        include_wikidata: Whether to include Wikidata results
+        year_weight: How much to prioritize year matches (0.0-2.0)
+            - 0.0 = distance only (ignore year)
+            - 1.0 = balanced
+            - 1.5 = prefer year matches (default)
+            - 2.0 = strongly prefer year matches
+    
+    Returns:
+        List of event dictionaries sorted by relevance
+    """
+    # Step 1: Search curated local database
+    events = load_events_from_db()
+    matches: List[dict] = []
+
+    # Use larger radius when year-weighted to find more year matches
+    effective_radius = radius_km * (1 + year_weight * 0.5) if year_weight > 1.0 else radius_km
+
+    for event in events:
+        distance, year_delta, confidence, match_score = _compute_match_score(
+            event, lat, lon, year, year_weight=year_weight
+        )
+        
+        # Include if within radius OR if year matches closely
+        if distance > effective_radius and year_delta > 10:
+            continue
+        
+        # Always include exact year matches regardless of distance
+        if year_delta > 15 and distance > radius_km:
+            continue
+
+        match = dict(event)
+        match["distance_km"] = round(distance, 2)
+        match["year_delta"] = year_delta
+        match["match_confidence"] = round(confidence, 3)
+        match["match_score"] = match_score
+        match["source"] = "curated"
+        matches.append(match)
+
+    matches.sort(key=lambda item: item["match_score"])
+    curated_results = matches[:limit]
+    
+    # Step 2: If enabled and we have few/no curated results, query Wikidata
+    if (
+        include_wikidata
+        and ENABLE_WIKIDATA_FALLBACK
+        and WIKIDATA_AVAILABLE
+        and len(curated_results) < limit
+    ):
+        try:
+            print(f"[history_service] Querying Wikidata for additional events...")
+            wikidata_results = wikidata_search(
+                lat=lat,
+                lon=lon,
+                year=year,
+                radius_km=radius_km,
+                limit=limit * 2,  # Get extra to filter
+            )
+            
+            # Merge Wikidata results, avoiding duplicates by name
+            curated_names = {m.get("name", "").lower() for m in curated_results}
+            
+            for wd_event in wikidata_results:
+                # Skip if we already have this event from curated data
+                event_name = wd_event.get("name", "").lower()
+                if event_name in curated_names:
+                    continue
+                
+                # Skip low-confidence results
+                confidence = wd_event.get("match_confidence", wd_event.get("confidence", 0))
+                if confidence < WIKIDATA_CONFIDENCE_THRESHOLD:
+                    continue
+                
+                # Add source marker and compute year-weighted score
+                wd_event["source"] = "wikidata"
+                wd_year_delta = wd_event.get("year_delta", 99)
+                wd_distance = wd_event.get("distance_km", 999)
+                
+                # Year-weighted scoring for Wikidata results
+                if wd_year_delta == 0:
+                    year_score = -50 * year_weight
+                elif wd_year_delta <= 2:
+                    year_score = -30 * year_weight
+                elif wd_year_delta <= 5:
+                    year_score = -15 * year_weight
+                elif wd_year_delta <= 10:
+                    year_score = 0
+                else:
+                    year_score = wd_year_delta * 3 * year_weight
+                
+                distance_score = wd_distance * 0.1 * (1 - year_weight * 0.3)
+                wd_event["match_score"] = distance_score + year_score - confidence * 10
+                
+                curated_results.append(wd_event)
+                curated_names.add(event_name)
+                
+                if len(curated_results) >= limit:
+                    break
+            
+            # Re-sort combined results
+            curated_results.sort(key=lambda item: item.get("match_score", 999))
+            
+        except Exception as e:
+            print(f"[history_service] Wikidata lookup failed: {e}")
+    
+    return curated_results[:limit]
+
+
+def search_events_globally(
+    lat: float,
+    lon: float,
+    year: int,
+    radius_km: float = 500.0,
+    limit: int = 10,
+    year_weight: float = 1.5,
+) -> List[dict]:
+    """
+    Search for historical events with broader radius, always including Wikidata.
+    
+    This is useful for finding events when the user doesn't have precise coordinates.
+    Uses year-weighted scoring by default to prioritize temporal matches.
+    """
+    return get_events_by_coordinates(
+        lat=lat,
+        lon=lon,
+        year=year,
+        radius_km=radius_km,
+        limit=limit,
+        include_wikidata=True,
+        year_weight=year_weight,
+    )
+
+
+def get_event_by_slug(slug: str) -> Optional[dict]:
+    conn = _get_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT * FROM events WHERE slug = ?", (slug,))
+    row = cursor.fetchone()
+    conn.close()
+
+    if not row:
+        return None
+
+    event = dict(row)
+    event["themes"] = _deserialize(event.get("themes"), [])
+    event["actors"] = _deserialize(event.get("actors"), [])
+    event["artifacts"] = _deserialize(event.get("artifacts"), [])
+    event["visual_motifs"] = _deserialize(event.get("visual_motifs"), [])
+    event["facets"] = _deserialize(event.get("facets"), {})
+    event["sources"] = _deserialize(event.get("sources"), [])
+    event["time_range"] = _deserialize(event.get("time_range"), {})
+    event["geo_anchor"] = _deserialize(event.get("geo_anchor"), {})
+    event["relationships"] = _deserialize(event.get("relationships"), {})
+    return event
+
+
+def get_event_by_name(name: str, include_wikidata: bool = True) -> Optional[dict]:
+    """
+    Get event by name, checking curated data first, then Wikidata.
+    """
+    # Try curated data first
+    event = get_event_by_slug(name.lower().replace(" ", "_"))
+    if event:
+        event["source"] = "curated"
+        return event
+    
+    # Try Wikidata if enabled
+    if include_wikidata and ENABLE_WIKIDATA_FALLBACK and WIKIDATA_AVAILABLE:
+        try:
+            results = wikidata_search_by_name(name, limit=1)
+            if results:
+                results[0]["source"] = "wikidata"
+                return results[0]
+        except Exception as e:
+            print(f"[history_service] Wikidata name search failed: {e}")
+    
+    return None
+
+
+def get_event_by_qid(qid: str) -> Optional[dict]:
+    """
+    Get detailed event information from Wikidata by QID.
+    """
+    if not WIKIDATA_AVAILABLE:
+        return None
+    
+    try:
+        return wikidata_get_detail(qid)
+    except Exception as e:
+        print(f"[history_service] Wikidata QID lookup failed: {e}")
+        return None
+
+
+def get_artifacts_for_year(year: int, limit: int = 4) -> List[dict]:
+    matches: List[dict] = []
+    for artifact in CURATED_ARTIFACTS:
+        era_start, era_end = artifact.get("era", [None, None])
+        if era_start is None or era_end is None:
+            matches.append(artifact)
+            continue
+        if era_start <= year <= era_end:
+            matches.append(artifact)
+    if not matches:
+        matches = CURATED_ARTIFACTS[:]
+    return matches[:limit]
+
+
+def summarize_event(event: dict) -> str:
+    summary = event.get("summary") or event.get("narrative") or event.get("name")
+    return summary
+
+
+def ensure_iterable(value: Optional[Iterable[str]]) -> List[str]:
+    if value is None:
+        return []
+    return list(value)
+
+
+CURATED_EVENTS: List[dict] = [
+    {
+        "name": "Fall of the Berlin Wall",
+        "slug": "fall_of_the_berlin_wall",
+        "year": 1989,
+        "start_year": 1989,
+        "end_year": 1989,
+        "month": 11,
+        "day": 9,
+        "lat": 52.5163,
+        "lon": 13.3777,
+        "summary": "East and West Berliners gather at the Brandenburg Gate as border checkpoints open and the concrete wall begins to fall.",
+        "narrative": (
+            "A sea of Berliners clamber atop graffiti-streaked concrete slabs, cheering as border guards lift the barriers. "
+            "People pass champagne bottles, wield sledgehammers, and chip away fragments while floodlights and television crews illuminate the night."
+        ),
+        "themes": ["political", "reunification", "cold war"],
+        "actors": ["East German civilians", "West Berlin residents", "border guards", "international journalists"],
+        "artifacts": ["Graffiti-covered concrete", "Champagne bottles", "Trabant cars", "Floodlights", "Metal barricades"],
+        "visual_motifs": ["floodlit night sky", "cold autumn breath", "television cameras", "crowded concrete wall"],
+        "facets": {"era": "late 20th century", "region": "western_europe", "type": "political upheaval"},
+        "sources": [{"label": "Wikipedia", "url": "https://en.wikipedia.org/wiki/Fall_of_the_Berlin_Wall"}],
+        "time_range": {"start": "1989-11-09T18:00:00", "end": "1989-11-10T02:00:00"},
+        "geo_anchor": {"lat": 52.5163, "lon": 13.3777, "radius_km": 4},
+        "confidence": 0.96,
+        "relationships": {"consequences": ["German reunification 1990"]},
+    },
+    {
+        "name": "D-Day Landing at Omaha Beach",
+        "slug": "d_day_landing_at_omaha_beach",
+        "year": 1944,
+        "start_year": 1944,
+        "end_year": 1944,
+        "month": 6,
+        "day": 6,
+        "lat": 49.4144,
+        "lon": -0.8322,
+        "summary": "Allied assault troops storm Omaha Beach under heavy German fire at dawn during Operation Overlord.",
+        "narrative": (
+            "Pre-dawn haze lifts as landing craft ramps crash open and American soldiers sprint through waist-high surf toward fortified bluffs. "
+            "Machine-gun tracers stitch the air, artillery craters erupt in wet sand, and medics tend to the wounded beside hedgehog obstacles."
+        ),
+        "themes": ["military", "WWII", "allied victory"],
+        "actors": ["US 1st Infantry Division", "US 29th Infantry Division", "German Atlantic Wall defenders", "Combat medics"],
+        "artifacts": ["Higgins landing craft", "Browning machine guns", "M1 helmets", "Beach obstacles", "Signal flares"],
+        "visual_motifs": ["morning fog", "breaking waves", "artillery smoke", "olive drab uniforms"],
+        "facets": {"era": "mid 20th century", "region": "western_europe", "type": "amphibious assault"},
+        "sources": [{"label": "National WWII Museum", "url": "https://www.nationalww2museum.org"}],
+        "time_range": {"start": "1944-06-06T05:30:00", "end": "1944-06-06T10:00:00"},
+        "geo_anchor": {"lat": 49.4144, "lon": -0.8322, "radius_km": 12},
+        "confidence": 0.94,
+        "relationships": {"parallel": ["Sword Beach landings", "Utah Beach landings"]},
+    },
+    {
+        "name": "Signing of the Declaration of Independence",
+        "slug": "signing_of_the_declaration_of_independence",
+        "year": 1776,
+        "start_year": 1776,
+        "end_year": 1776,
+        "month": 7,
+        "day": 4,
+        "lat": 39.9489,
+        "lon": -75.1500,
+        "summary": "Delegates of the Continental Congress sign the Declaration inside Independence Hall, Philadelphia.",
+        "narrative": (
+            "Sunlight streams through tall sash windows onto polished wood floors as delegates in powdered wigs lean over parchment. "
+            "Quill pens scratch, wax seals glisten, and brass bellows stir a warm July breeze through the Assembly Room."
+        ),
+        "themes": ["political", "founding documents", "revolution"],
+        "actors": ["Thomas Jefferson", "John Hancock", "Continental Congress delegates"],
+        "artifacts": ["Quill pens", "Parchment scrolls", "Wax seals", "Mahogany desks"],
+        "visual_motifs": ["golden afternoon light", "colonial interior", "powder wigs", "rich green drapery"],
+        "facets": {"era": "late 18th century", "region": "north_america", "type": "political charter"},
+        "sources": [{"label": "US National Archives", "url": "https://www.archives.gov/founding-docs/declaration"}],
+        "time_range": {"start": "1776-07-04T10:00:00", "end": "1776-07-04T15:00:00"},
+        "geo_anchor": {"lat": 39.9489, "lon": -75.1500, "radius_km": 1},
+        "confidence": 0.9,
+        "relationships": {"causes": ["Continental Congress debates"], "consequences": ["American Revolutionary War escalation"]},
+    },
+    {
+        "name": "Battle of Waterloo",
+        "slug": "battle_of_waterloo",
+        "year": 1815,
+        "start_year": 1815,
+        "end_year": 1815,
+        "month": 6,
+        "day": 18,
+        "lat": 50.6794,
+        "lon": 4.4125,
+        "summary": "Coalition forces defeat Napoleon Bonaparte near Waterloo, ending the Hundred Days campaign.",
+        "narrative": (
+            "Under rain-darkened skies, British squares brace against French cavalry charges across muddy Belgian fields. "
+            "Cannon smoke drifts low, cuirassiers clash with bayonet lines, and signal flags ripple above the La Haye Sainte farmhouse."
+        ),
+        "themes": ["military", "napoleonic wars"],
+        "actors": ["British infantry", "Dutch-Belgian troops", "French Imperial Guard", "Prussian reinforcements"],
+        "artifacts": ["Cuirass armor", "Sabers", "Field cannon", "Signal flags"],
+        "visual_motifs": ["storm clouds", "muddy terrain", "cavalry charge", "gunpowder smoke"],
+        "facets": {"era": "early 19th century", "region": "western_europe", "type": "decisive battle"},
+        "sources": [{"label": "Waterloo Battlefield", "url": "https://www.waterloo1815.be"}],
+        "time_range": {"start": "1815-06-18T11:30:00", "end": "1815-06-18T20:30:00"},
+        "geo_anchor": {"lat": 50.6794, "lon": 4.4125, "radius_km": 8},
+        "confidence": 0.88,
+        "relationships": {"consequences": ["Exile of Napoleon to Saint Helena"]},
+    },
+    {
+        "name": "Hiroshima Atomic Bombing",
+        "slug": "hiroshima_atomic_bombing",
+        "year": 1945,
+        "start_year": 1945,
+        "end_year": 1945,
+        "month": 8,
+        "day": 6,
+        "lat": 34.3853,
+        "lon": 132.4553,
+        "summary": "The United States detonates an atomic bomb over Hiroshima, Japan, causing widespread destruction.",
+        "narrative": (
+            "Moments after the blinding flash, a mushroom cloud towers above shattered city blocks. "
+            "Wooden houses ignite, survivors stagger through debris-clogged streets, and the iconic Genbaku Dome stands amid the devastation."
+        ),
+        "themes": ["military", "WWII", "nuclear warfare"],
+        "actors": ["Civilians", "First responders", "US bomber crew (distant)"],
+        "artifacts": ["Genbaku Dome", "Debris-laden streets", "Shattered windows", "Charred telegraph poles"],
+        "visual_motifs": ["mushroom cloud", "ashen fallout", "burning skyline", "silhouetted survivors"],
+        "facets": {"era": "mid 20th century", "region": "east_asia", "type": "aerial bombardment"},
+        "sources": [{"label": "Hiroshima Peace Memorial Museum", "url": "https://hpmmuseum.jp/?lang=en"}],
+        "time_range": {"start": "1945-08-06T08:15:00", "end": "1945-08-06T12:00:00"},
+        "geo_anchor": {"lat": 34.3853, "lon": 132.4553, "radius_km": 15},
+        "confidence": 0.87,
+        "relationships": {"consequences": ["Surrender of Japan 1945"]},
+    },
+    {
+        "name": "Tiananmen Square Protests",
+        "slug": "tiananmen_square_protests",
+        "year": 1989,
+        "start_year": 1989,
+        "end_year": 1989,
+        "month": 6,
+        "day": 4,
+        "lat": 39.9042,
+        "lon": 116.4074,
+        "summary": "Chinese citizens hold pro-democracy demonstrations in Beijing's Tiananmen Square before military suppression.",
+        "narrative": (
+            "In early dawn haze, students link arms facing a line of armored vehicles. "
+            "The Goddess of Democracy statue rises above banners, bicycle couriers weave through tents, and the Gate of Heavenly Peace looms in the background."
+        ),
+        "themes": ["political", "protest", "democracy"],
+        "actors": ["Student demonstrators", "People's Liberation Army soldiers", "Beijing residents"],
+        "artifacts": ["Goddess of Democracy statue", "Banners and loudspeakers", "Tents", "Armored personnel carriers"],
+        "visual_motifs": ["morning haze", "stone square", "red flags", "human chain"],
+        "facets": {"era": "late 20th century", "region": "east_asia", "type": "protest movement"},
+        "sources": [{"label": "BBC Timeline", "url": "https://www.bbc.com/news/world-asia-china-12661772"}],
+        "time_range": {"start": "1989-06-03T22:00:00", "end": "1989-06-04T07:00:00"},
+        "geo_anchor": {"lat": 39.9042, "lon": 116.4074, "radius_km": 6},
+        "confidence": 0.88,
+        "relationships": {"parallel": ["1989 global protest movements"]},
+    },
+    {
+        "name": "Apollo 11 Moon Launch",
+        "slug": "apollo_11_moon_launch",
+        "year": 1969,
+        "start_year": 1969,
+        "end_year": 1969,
+        "month": 7,
+        "day": 16,
+        "lat": 28.5729,
+        "lon": -80.6490,
+        "summary": "NASA launches Apollo 11 from Kennedy Space Center, beginning the first crewed mission to land on the Moon.",
+        "narrative": (
+            "Spectators line the Causeway as the Saturn V rockets skyward, engines roaring and painting the morning sky orange. "
+            "Camera crews pan across mission control staff, astronauts in white suits wave before boarding, and the vehicle assembly building looms nearby."
+        ),
+        "themes": ["space exploration", "science", "Cold War"],
+        "actors": ["Neil Armstrong", "Buzz Aldrin", "Michael Collins", "Mission control engineers"],
+        "artifacts": ["Saturn V rocket", "Launch gantry", "Mission patches", "Telemetry consoles"],
+        "visual_motifs": ["plume of fire", "sunrise glow", "American flags", "NASA vehicles"],
+        "facets": {"era": "late 20th century", "region": "north_america", "type": "space mission"},
+        "sources": [{"label": "NASA History", "url": "https://www.nasa.gov/specials/apollo50th/"}],
+        "time_range": {"start": "1969-07-16T09:32:00", "end": "1969-07-16T10:00:00"},
+        "geo_anchor": {"lat": 28.5729, "lon": -80.6490, "radius_km": 10},
+        "confidence": 0.89,
+        "relationships": {"consequences": ["Apollo 11 moon landing"]},
+    },
+    {
+        "name": "Wright Brothers First Flight",
+        "slug": "wright_brothers_first_flight",
+        "year": 1903,
+        "start_year": 1903,
+        "end_year": 1903,
+        "month": 12,
+        "day": 17,
+        "lat": 36.0177,
+        "lon": -75.6694,
+        "summary": "Orville and Wilbur Wright achieve the first powered, sustained flight at Kitty Hawk, North Carolina.",
+        "narrative": (
+            "On windswept dunes, Orville lies prone on the Flyer as Wilbur steadies a wingtip. "
+            "A small crowd of lifesavers braces the launch rail, camera ready, as the biplane lifts into the cold December air for twelve seconds."
+        ),
+        "themes": ["aviation", "innovation"],
+        "actors": ["Orville Wright", "Wilbur Wright", "Kill Devil Hills lifesavers"],
+        "artifacts": ["Wright Flyer", "Launch rail", "Oil-stained overalls", "Box camera"],
+        "visual_motifs": ["wind-scoured dunes", "frosty breath", "canvas wings", "wooden spars"],
+        "facets": {"era": "early 20th century", "region": "north_america", "type": "technological milestone"},
+        "sources": [{"label": "Smithsonian Air & Space", "url": "https://airandspace.si.edu"}],
+        "time_range": {"start": "1903-12-17T10:35:00", "end": "1903-12-17T10:47:00"},
+        "geo_anchor": {"lat": 36.0177, "lon": -75.6694, "radius_km": 3},
+        "confidence": 0.86,
+        "relationships": {"consequences": ["Development of powered flight"]},
+    },
+    {
+        "name": "Grito de Dolores",
+        "slug": "grito_de_dolores",
+        "year": 1810,
+        "start_year": 1810,
+        "end_year": 1810,
+        "month": 9,
+        "day": 16,
+        "lat": 21.1561,
+        "lon": -100.9326,
+        "summary": "Father Miguel Hidalgo y Costilla calls for Mexican independence with the famous Grito de Dolores.",
+        "narrative": (
+            "Before dawn, church bells ring out as Father Hidalgo addresses villagers in the plaza, torchlight illuminating insurgent banners. "
+            "Peasants clutch farming tools turned weapons while women distribute ammunition from woven baskets."
+        ),
+        "themes": ["revolution", "latin america"],
+        "actors": ["Father Miguel Hidalgo", "Town villagers", "Criollo supporters"],
+        "artifacts": ["Church bell rope", "Guadalupe banner", "Torches", "Improvised spears"],
+        "visual_motifs": ["torchlit plaza", "colonial church facade", "Mexican flag colors", "dawn sky"],
+        "facets": {"era": "early 19th century", "region": "central_america", "type": "independence movement"},
+        "sources": [{"label": "Mexican History", "url": "https://www.gob.mx"}],
+        "time_range": {"start": "1810-09-16T05:00:00", "end": "1810-09-16T07:00:00"},
+        "geo_anchor": {"lat": 21.1561, "lon": -100.9326, "radius_km": 5},
+        "confidence": 0.82,
+        "relationships": {"consequences": ["Mexican War of Independence"]},
+    },
+    {
+        "name": "Storming of the Bastille",
+        "slug": "storming_of_the_bastille",
+        "year": 1789,
+        "start_year": 1789,
+        "end_year": 1789,
+        "month": 7,
+        "day": 14,
+        "lat": 48.8530,
+        "lon": 2.3692,
+        "summary": "Parisian revolutionaries seize the Bastille fortress, igniting the French Revolution.",
+        "narrative": (
+            "Parisians wielding pikes and muskets swarm the Bastille's stone courtyard as smoke billows from cannon fire. "
+            "National Guardsmen drag royal cannons into position while prisoners emerge to cheering crowds waving tricolor cockades."
+        ),
+        "themes": ["revolution", "political upheaval"],
+        "actors": ["Parisian crowds", "National Guardsmen", "Royal soldiers"],
+        "artifacts": ["Tricolor cockades", "Iron portcullis", "Cannons", "Stone battlements"],
+        "visual_motifs": ["smoke-filled courtyard", "stormy summer sky", "stone fortress", "crowd surge"],
+        "facets": {"era": "late 18th century", "region": "western_europe", "type": "revolutionary uprising"},
+        "sources": [{"label": "French Archives", "url": "https://www.archives-nationales.culture.gouv.fr"}],
+        "time_range": {"start": "1789-07-14T09:00:00", "end": "1789-07-14T17:00:00"},
+        "geo_anchor": {"lat": 48.8530, "lon": 2.3692, "radius_km": 3},
+        "confidence": 0.84,
+        "relationships": {"consequences": ["Declaration of the Rights of Man"]},
+    },
+    {
+        "name": "Assassination of Julius Caesar",
+        "slug": "assassination_of_julius_caesar",
+        "year": -44,
+        "start_year": -44,
+        "end_year": -44,
+        "month": 3,
+        "day": 15,
+        "lat": 41.8933,
+        "lon": 12.4729,
+        "summary": "Julius Caesar is stabbed by Roman senators inside the Theatre of Pompey during the Ides of March.",
+        "narrative": (
+            "Late morning sunlight filters through the marble portico as Caesar takes his seat. "
+            "Senators in scarlet-trimmed togas encircle him; daggers flash, and the dictator staggers toward the statue of Pompey "
+            "beneath frescoed arches and hanging laurel wreaths."
+        ),
+        "themes": ["political", "assassination", "ancient rome"],
+        "actors": ["Julius Caesar", "Marcus Junius Brutus", "Gaius Cassius Longinus", "Roman senators"],
+        "artifacts": ["Marble curule chair", "Bronze daggers", "Laurel wreaths", "Blood-stained togas"],
+        "visual_motifs": ["marble columns", "sunbeam through smoke", "collapsing laurel crown"],
+        "facets": {"era": "classical antiquity", "region": "western_europe", "type": "political assassination"},
+        "sources": [{"label": "Ancient Rome", "url": "https://en.wikipedia.org/wiki/Assassination_of_Julius_Caesar"}],
+        "time_range": {"start": "-0044-03-15T11:00:00", "end": "-0044-03-15T12:00:00"},
+        "geo_anchor": {"lat": 41.8933, "lon": 12.4729, "radius_km": 2},
+        "confidence": 0.9,
+        "relationships": {"consequences": ["Liberators' civil war"]},
+    },
+]
+
+
+CURATED_ARTIFACTS: List[dict] = [
+    {"title": "Graffiti fragment of the Berlin Wall", "culture": "German", "period": "Cold War", "era": (1961, 1990)},
+    {"title": "Allied M1 Helmet", "culture": "American", "period": "World War II", "era": (1941, 1945)},
+    {"title": "Continental Congress inkwell", "culture": "American", "period": "Revolutionary", "era": (1765, 1783)},
+    {"title": "French cuirassier armor", "culture": "French", "period": "Napoleonic", "era": (1800, 1815)},
+    {"title": "Goddess of Democracy maquette", "culture": "Chinese", "period": "Late 20th century", "era": (1980, 1990)},
+    {"title": "Saturn V mission patch", "culture": "American", "period": "Space Age", "era": (1960, 1975)},
+    {"title": "Wright Flyer blueprint", "culture": "American", "period": "Early Aviation", "era": (1899, 1905)},
+    {"title": "Bastille prison key", "culture": "French", "period": "Revolutionary", "era": (1789, 1799)},
+]
+
+ERA_VISUAL_VOCABULARY: Dict[Tuple[int, int], dict] = {
+    (-5000, 1700): {
+        "architecture": "stone structures, timber framing, open marketplaces",
+        "clothing": "homespun fabrics, cloaks, leather sandals",
+        "technology": "handcrafted tools, smoke from hearth fires, animal-drawn transport",
+        "transport": "horses, carts, foot traffic",
+        "mood": "earthy textures, smoke and torchlight",
+    },
+    (1700, 1850): {
+        "architecture": "Georgian and neoclassical facades, stone avenues, colonial interiors",
+        "clothing": "powdered wigs, waistcoats, breeches, corseted gowns",
+        "technology": "printing presses, quill ink, carronade cannons",
+        "transport": "horse-drawn carriages, sailing ships, infantry columns",
+        "mood": "oil-painted lighting, warm candle glow and shadow",
+    },
+    (1850, 1918): {
+        "architecture": "industrial brick mills, iron train stations, Victorian terraces",
+        "clothing": "bowler hats, uniforms with brass buttons, layered dresses",
+        "technology": "steam locomotives, telegraph poles, gas lanterns",
+        "transport": "steam trains, horse omnibuses, early bicycles",
+        "mood": "coal smoke haze, sepia-toned atmosphere",
+    },
+    (1918, 1950): {
+        "architecture": "art deco facades, reinforced bunkers, concrete civic plazas",
+        "clothing": "military uniforms, flapper dresses, utilitarian workwear",
+        "technology": "radio towers, field telephones, propeller aircraft",
+        "transport": "steel warships, troop trucks, streetcars",
+        "mood": "black-and-white newsreel grit, halation from searchlights",
+    },
+    (1950, 1990): {
+        "architecture": "mid-century modern lines, brutalist government blocks, neon signage",
+        "clothing": "denim jackets, tailored suits, Cold War uniforms",
+        "technology": "cathode-ray cameras, satellite dishes, analog broadcast vans",
+        "transport": "boxy sedans, subway trains, patrol jeeps",
+        "mood": "sodium-vapor glow, vivid chromatic contrasts",
+    },
+    (1990, 2030): {
+        "architecture": "glass high-rises, LED billboards, postmodern cultural centers",
+        "clothing": "synthetic fabrics, streetwear, modern uniforms",
+        "technology": "smart devices, digital screens, drones",
+        "transport": "light rail, electric cars, bicycles with LED lights",
+        "mood": "clean highlights, cinematic depth of field, vibrant color grading",
+    },
+}
+
+REGIONAL_CONTEXT: Dict[str, dict] = {
+    "western_europe": {
+        "architecture": "historic stone plazas, cathedrals, tram-lined boulevards",
+        "climate": "temperate weather with layered clouds and soft rain",
+    },
+    "eastern_europe": {
+        "architecture": "Soviet-era apartment blocks, neoclassical government buildings",
+        "climate": "continental climate with sharp seasonal contrast",
+    },
+    "north_america": {
+        "architecture": "brick row houses, colonial meeting halls, steel skyscrapers",
+        "climate": "varied weather, from humid summers to snowy winters",
+    },
+    "east_asia": {
+        "architecture": "pagoda rooftops, dense urban districts, neon signage",
+        "climate": "humid subtropical seasons with monsoon rains",
+    },
+    "central_america": {
+        "architecture": "stucco plazas, colonial churches, cobblestone streets",
+        "climate": "warm highland mornings with misty horizons",
+    },
+    "western_asia": {
+        "architecture": "stone citadels, market arcades, desert courtyards",
+        "climate": "arid sunlight, dust carried on dry winds",
+    },
+}
+
+
+def get_era_vocabulary(year: int) -> dict:
+    for (start, end), vocab in ERA_VISUAL_VOCABULARY.items():
+        if start <= year < end:
+            return vocab
+    # Default to modern vocabulary
+    return ERA_VISUAL_VOCABULARY[(1950, 1990)]
+
+
+def get_region_context(region_key: Optional[str]) -> dict:
+    if not region_key:
+        return {}
+    return REGIONAL_CONTEXT.get(region_key.lower(), {})
+
+
+def format_event_digest(event: dict) -> dict:
+    return {
+        "name": event.get("name"),
+        "slug": event.get("slug"),
+        "year": event.get("year"),
+        "start_year": event.get("start_year"),
+        "end_year": event.get("end_year"),
+        "month": event.get("month"),
+        "day": event.get("day"),
+        "lat": event.get("lat"),
+        "lon": event.get("lon"),
+        "summary": event.get("summary"),
+        "themes": ensure_iterable(event.get("themes")),
+        "facets": event.get("facets", {}),
+        "distance_km": event.get("distance_km"),
+        "year_delta": event.get("year_delta"),
+        "match_confidence": event.get("match_confidence"),
+        "sources": ensure_iterable(event.get("sources")),
+    }
+
+
+def build_event_context(event: dict) -> dict:
+    return {
+        "event": format_event_digest(event),
+        "narrative": event.get("narrative"),
+        "actors": ensure_iterable(event.get("actors")),
+        "artifacts": ensure_iterable(event.get("artifacts")),
+        "visual_motifs": ensure_iterable(event.get("visual_motifs")),
+        "relationships": event.get("relationships", {}),
+        "time_range": event.get("time_range"),
+        "geo_anchor": event.get("geo_anchor"),
+        "confidence": event.get("match_confidence", event.get("confidence")),
+    }
+
+
+def get_events_response(
+    lat: float,
+    lon: float,
+    year: int,
+    radius_km: float = 250.0,
+    limit: int = 5,
+) -> dict:
+    matches = get_events_by_coordinates(lat, lon, year, radius_km=radius_km, limit=limit)
+    return {
+        "query": {"lat": lat, "lon": lon, "year": year, "radius_km": radius_km, "limit": limit},
+        "count": len(matches),
+        "events": [format_event_digest(event) for event in matches],
+    }
+
+

prompt_parser.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+
+MONTHS = {
+    "january": 1,
+    "february": 2,
+    "march": 3,
+    "april": 4,
+    "may": 5,
+    "june": 6,
+    "july": 7,
+    "august": 8,
+    "september": 9,
+    "sept": 9,
+    "october": 10,
+    "november": 11,
+    "december": 12,
+}
+
+
+HEMISPHERE_MULTIPLIERS = {
+    "n": 1,
+    "s": -1,
+    "e": 1,
+    "w": -1,
+}
+
+
+COORD_PATTERN = re.compile(
+    r"([-+]?\d+(?:\.\d+)?)\s*(?:°|deg|degrees)?\s*([NnSsEeWw])"
+)
+
+LAT_LON_WORD_PATTERN = re.compile(
+    r"(?:latitude|lat)\s*[:=]?\s*([-+]?\d+(?:\.\d+)?)|(?:longitude|lon)\s*[:=]?\s*([-+]?\d+(?:\.\d+)?)",
+    re.IGNORECASE,
+)
+
+DATE_PATTERN = re.compile(
+    r"\b("
+    + "|".join(MONTHS.keys())
+    + r")\s+(\d{1,2})(?:st|nd|rd|th)?(?:,\s*|\s+)(-?\d{1,4})(?:\s*(BCE|BC|CE|AD))?",
+    re.IGNORECASE,
+)
+
+YEAR_ONLY_PATTERN = re.compile(r"\b(-?\d{1,4})\s*(BCE|BC|CE|AD)?\b", re.IGNORECASE)
+
+HOUR_PATTERN = re.compile(r"\b(\d{1,2})(?::(\d{2}))?\s*(?:hours?|h)\b", re.IGNORECASE)
+
+SEASONAL_HOUR_PATTERN = re.compile(
+    r"\b(?:at|around)\s*(\d{1,2})(?::(\d{2}))?\s*(?:am|pm)\b", re.IGNORECASE
+)
+
+
+@dataclass
+class ParsedPrompt:
+    lat: Optional[float] = None
+    lon: Optional[float] = None
+    year: Optional[int] = None
+    month: Optional[int] = None
+    day: Optional[int] = None
+    hour: Optional[int] = None
+    minute: Optional[int] = None
+    confidence: float = 0.0
+    residual_text: str = ""
+
+
+def _apply_hemisphere(value: float, hemisphere: str) -> float:
+    multiplier = HEMISPHERE_MULTIPLIERS.get(hemisphere.lower(), 1)
+    return value * multiplier
+
+
+def _parse_coordinates(text: str) -> tuple[Optional[float], Optional[float], float]:
+    lat = lon = None
+    confidence = 0.0
+
+    matches = COORD_PATTERN.findall(text)
+    lat_candidate = lon_candidate = None
+    for value_str, hemisphere in matches:
+        value = float(value_str)
+        hemi = hemisphere.lower()
+        adjusted = _apply_hemisphere(value, hemi)
+        if hemi in ("n", "s") and lat_candidate is None:
+            lat_candidate = adjusted
+        elif hemi in ("e", "w") and lon_candidate is None:
+            lon_candidate = adjusted
+
+    if lat_candidate is not None and lon_candidate is not None:
+        lat, lon = lat_candidate, lon_candidate
+        confidence += 0.5
+
+    if lat is None or lon is None:
+        word_matches = LAT_LON_WORD_PATTERN.findall(text)
+        lat_words = [float(item[0]) for item in word_matches if item[0]]
+        lon_words = [float(item[1]) for item in word_matches if item[1]]
+        if lat is None and lat_words:
+            lat = lat_words[0]
+            confidence += 0.2
+        if lon is None and lon_words:
+            lon = lon_words[0]
+            confidence += 0.2
+
+    return lat, lon, min(confidence, 0.6)
+
+
+def _convert_year(raw_year: str, era: Optional[str]) -> int:
+    year = int(raw_year)
+    if era:
+        era = era.upper()
+        if era in ("BCE", "BC"):
+            return -abs(year)
+    return year
+
+
+def _parse_date(text: str) -> tuple[Optional[int], Optional[int], Optional[int], float]:
+    match = DATE_PATTERN.search(text)
+    if match:
+        month_name, day_str, year_str, era = match.groups()
+        month = MONTHS.get(month_name.lower())
+        day = int(day_str)
+        year = _convert_year(year_str, era)
+        return year, month, day, 0.4
+
+    # Fallback: year-only pattern
+    for candidate in YEAR_ONLY_PATTERN.finditer(text):
+        year_str, era = candidate.groups()
+        year = _convert_year(year_str, era)
+        if -5000 <= year <= 3000:  # plausible historical range
+            return year, None, None, 0.2
+    return None, None, None, 0.0
+
+
+def _parse_hour(text: str) -> tuple[Optional[int], Optional[int], float]:
+    match = HOUR_PATTERN.search(text)
+    if match:
+        hour = int(match.group(1))
+        minute = int(match.group(2)) if match.group(2) else 0
+        return hour, minute, 0.2
+
+    match = SEASONAL_HOUR_PATTERN.search(text)
+    if match:
+        hour = int(match.group(1))
+        minute = int(match.group(2)) if match.group(2) else 0
+        suffix = match.group(0).lower()
+        if "pm" in suffix and hour < 12:
+            hour += 12
+        if "am" in suffix and hour == 12:
+            hour = 0
+        return hour, minute, 0.15
+
+    return None, None, 0.0
+
+
+def parse_prompt_context(prompt: Optional[str]) -> ParsedPrompt:
+    if not prompt:
+        return ParsedPrompt(residual_text="")
+
+    lat, lon, coord_conf = _parse_coordinates(prompt)
+    year, month, day, date_conf = _parse_date(prompt)
+    hour, minute, hour_conf = _parse_hour(prompt)
+
+    total_conf = coord_conf + date_conf + hour_conf
+    return ParsedPrompt(
+        lat=lat,
+        lon=lon,
+        year=year,
+        month=month,
+        day=day,
+        hour=hour,
+        minute=minute,
+        confidence=min(total_conf, 1.0),
+        residual_text=prompt,
+    )
+
+
+

requirements.txt

@@ -0,0 +1,7 @@
+gradio[mcp]>=5.0
+huggingface_hub>=0.20.0
+google-generativeai>=0.7.0
+requests>=2.31.0
+pillow>=10.0.0
+python-dotenv>=1.0.0
+

wikidata_service.py

@@ -0,0 +1,706 @@
+"""
+Wikidata service for finding historical events.
+
+Queries Wikidata for events at specific coordinates and times.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import ssl
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+import urllib.request
+import urllib.parse
+import urllib.error
+
+# Note: We use urllib with SSL fallback to avoid permission issues with requests/certifi
+USE_REQUESTS = False
+
+# Cache configuration
+ROOT_DIR = Path(__file__).resolve().parent.parent
+CACHE_DIR = ROOT_DIR / "data" / "wikidata_cache"
+CACHE_DIR.mkdir(parents=True, exist_ok=True)
+CACHE_TTL_SECONDS = 86400 * 7  # 7 days
+
+WIKIDATA_SPARQL_ENDPOINT = "https://query.wikidata.org/sparql"
+
+# Rate limiting
+_last_request_time: float = 0.0
+MIN_REQUEST_INTERVAL = 1.5  # seconds between requests
+
+
+@dataclass
+class WikidataEvent:
+    """Represents a historical event from Wikidata."""
+    qid: str
+    name: str
+    description: str = ""
+    year: Optional[int] = None
+    month: Optional[int] = None
+    day: Optional[int] = None
+    lat: Optional[float] = None
+    lon: Optional[float] = None
+    participants: List[str] = field(default_factory=list)
+    location_name: str = ""
+    event_type: str = ""
+    wikipedia_url: str = ""
+    image_url: str = ""
+    distance_km: float = 0.0
+    year_delta: int = 0
+    confidence: float = 0.0
+    source: str = "wikidata"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "qid": self.qid,
+            "name": self.name,
+            "description": self.description,
+            "year": self.year,
+            "month": self.month,
+            "day": self.day,
+            "lat": self.lat,
+            "lon": self.lon,
+            "participants": self.participants,
+            "location_name": self.location_name,
+            "event_type": self.event_type,
+            "wikipedia_url": self.wikipedia_url,
+            "image_url": self.image_url,
+            "distance_km": self.distance_km,
+            "year_delta": self.year_delta,
+            "confidence": self.confidence,
+            "source": self.source,
+            # Compatibility fields for existing code
+            "summary": self.description,
+            "narrative": self.description,
+            "actors": self.participants,
+            "themes": [self.event_type] if self.event_type else [],
+            "artifacts": [],
+            "visual_motifs": [],
+            "facets": {"type": self.event_type},
+            "sources": [{"label": "Wikidata", "url": f"https://www.wikidata.org/wiki/{self.qid}"}],
+            "match_confidence": self.confidence,
+        }
+
+
+def _cache_key(lat: float, lon: float, year: int, radius_km: float) -> str:
+    """Generate a cache key for the query parameters."""
+    raw = f"{lat:.2f}_{lon:.2f}_{year}_{radius_km:.0f}"
+    return hashlib.md5(raw.encode()).hexdigest()
+
+
+def _get_cached(cache_key: str) -> Optional[List[Dict]]:
+    """Retrieve cached results if they exist and aren't expired."""
+    cache_file = CACHE_DIR / f"{cache_key}.json"
+    if not cache_file.exists():
+        return None
+    
+    try:
+        with open(cache_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        
+        cached_time = data.get("timestamp", 0)
+        if time.time() - cached_time > CACHE_TTL_SECONDS:
+            cache_file.unlink(missing_ok=True)
+            return None
+        
+        return data.get("events", [])
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _save_cache(cache_key: str, events: List[Dict]) -> None:
+    """Save results to cache."""
+    cache_file = CACHE_DIR / f"{cache_key}.json"
+    try:
+        with open(cache_file, "w", encoding="utf-8") as f:
+            json.dump({"timestamp": time.time(), "events": events}, f, ensure_ascii=False)
+    except OSError:
+        pass
+
+
+def _rate_limit() -> None:
+    """Ensure we don't exceed Wikidata rate limits."""
+    global _last_request_time
+    elapsed = time.time() - _last_request_time
+    if elapsed < MIN_REQUEST_INTERVAL:
+        time.sleep(MIN_REQUEST_INTERVAL - elapsed)
+    _last_request_time = time.time()
+
+
+def _haversine(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Calculate distance in km between two points."""
+    R = 6371.0
+    phi1, phi2 = math.radians(lat1), math.radians(lat2)
+    dphi = math.radians(lat2 - lat1)
+    dlam = math.radians(lon2 - lon1)
+    a = math.sin(dphi / 2) ** 2 + math.cos(phi1) * math.cos(phi2) * math.sin(dlam / 2) ** 2
+    return R * 2 * math.atan2(math.sqrt(a), math.sqrt(max(0, 1 - a)))
+
+
+def _build_sparql_query(lat: float, lon: float, year: int, radius_km: float, limit: int = 20) -> str:
+    """
+    Build SPARQL query for historical events near coordinates and year.
+    
+    This query searches for:
+    - Events (Q1656682) that occurred at a location
+    - Battles, treaties, revolutions, etc.
+    - Events with point in time or start time within the year range
+    """
+    # Wikidata uses negative years for BCE
+    year_start = year - 15
+    year_end = year + 15
+    
+    # Convert radius to degrees (rough approximation)
+    degree_radius = radius_km / 111.0
+    
+    query = f"""
+    SELECT DISTINCT ?event ?eventLabel ?eventDescription ?date ?coord ?locationLabel ?participantLabel ?typeLabel ?article ?image
+    WHERE {{
+      # Find events with coordinates
+      ?event wdt:P31/wdt:P279* wd:Q1656682 .  # instance of event or subclass
+      
+      # Get coordinates - either direct or via location
+      OPTIONAL {{
+        ?event wdt:P625 ?directCoord .
+      }}
+      OPTIONAL {{
+        ?event wdt:P276 ?location .
+        ?location wdt:P625 ?locationCoord .
+      }}
+      BIND(COALESCE(?directCoord, ?locationCoord) AS ?coord)
+      
+      # Filter by coordinate bounding box
+      FILTER(BOUND(?coord))
+      BIND(geof:latitude(?coord) AS ?lat)
+      BIND(geof:longitude(?coord) AS ?lon)
+      FILTER(?lat >= {lat - degree_radius} && ?lat <= {lat + degree_radius})
+      FILTER(?lon >= {lon - degree_radius} && ?lon <= {lon + degree_radius})
+      
+      # Get date
+      OPTIONAL {{ ?event wdt:P585 ?pointInTime . }}
+      OPTIONAL {{ ?event wdt:P580 ?startTime . }}
+      BIND(COALESCE(?pointInTime, ?startTime) AS ?date)
+      
+      # Filter by year range
+      FILTER(BOUND(?date))
+      FILTER(YEAR(?date) >= {year_start} && YEAR(?date) <= {year_end})
+      
+      # Optional: participants
+      OPTIONAL {{ ?event wdt:P710 ?participant . }}
+      
+      # Optional: event type
+      OPTIONAL {{ ?event wdt:P31 ?type . }}
+      
+      # Optional: Wikipedia article
+      OPTIONAL {{
+        ?article schema:about ?event ;
+                 schema:isPartOf <https://en.wikipedia.org/> .
+      }}
+      
+      # Optional: image
+      OPTIONAL {{ ?event wdt:P18 ?image . }}
+      
+      # Location label
+      OPTIONAL {{ ?event wdt:P276 ?loc . }}
+      
+      SERVICE wikibase:label {{ bd:serviceParam wikibase:language "en,de,fr,es,it" . }}
+    }}
+    ORDER BY ABS(YEAR(?date) - {year})
+    LIMIT {limit}
+    """
+    return query
+
+
+def _build_fallback_query(lat: float, lon: float, year: int, limit: int = 15) -> str:
+    """
+    Simpler fallback query that searches for any notable events in the year range.
+    Uses text search and broader event types.
+    """
+    year_start = year - 20
+    year_end = year + 20
+    
+    query = f"""
+    SELECT DISTINCT ?event ?eventLabel ?eventDescription ?date ?coord ?locationLabel ?article
+    WHERE {{
+      # Broader event types
+      VALUES ?eventType {{
+        wd:Q178561    # battle
+        wd:Q131569    # treaty
+        wd:Q7278      # political revolution
+        wd:Q8076      # assassination
+        wd:Q3882219   # coronation
+        wd:Q1318295   # military offensive
+        wd:Q2001676   # massacre
+        wd:Q18669875  # historical event
+        wd:Q13418847  # historical period
+        wd:Q3024240   # historical event
+      }}
+      ?event wdt:P31 ?eventType .
+      
+      # Date filter
+      OPTIONAL {{ ?event wdt:P585 ?pointInTime . }}
+      OPTIONAL {{ ?event wdt:P580 ?startTime . }}
+      BIND(COALESCE(?pointInTime, ?startTime) AS ?date)
+      FILTER(BOUND(?date))
+      FILTER(YEAR(?date) >= {year_start} && YEAR(?date) <= {year_end})
+      
+      # Get coordinates via location
+      OPTIONAL {{
+        ?event wdt:P276 ?location .
+        ?location wdt:P625 ?coord .
+      }}
+      OPTIONAL {{
+        ?event wdt:P625 ?directCoord .
+      }}
+      BIND(COALESCE(?coord, ?directCoord) AS ?finalCoord)
+      
+      # Wikipedia article
+      OPTIONAL {{
+        ?article schema:about ?event ;
+                 schema:isPartOf <https://en.wikipedia.org/> .
+      }}
+      
+      SERVICE wikibase:label {{ bd:serviceParam wikibase:language "en" . }}
+    }}
+    ORDER BY ABS(YEAR(?date) - {year})
+    LIMIT {limit}
+    """
+    return query
+
+
+def _execute_sparql(query: str) -> Optional[Dict]:
+    """Execute SPARQL query against Wikidata endpoint."""
+    _rate_limit()
+    
+    headers = {
+        "Accept": "application/sparql-results+json",
+        "User-Agent": "Meridian-Historical-App/1.0 (https://github.com/meridian; [email protected])"
+    }
+    
+    # Try using requests library first (better SSL handling)
+    if USE_REQUESTS:
+        try:
+            response = requests.get(
+                WIKIDATA_SPARQL_ENDPOINT,
+                params={"query": query},
+                headers=headers,
+                timeout=30,
+                verify=certifi.where(),
+            )
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            print(f"[Wikidata] SPARQL query failed (requests): {e}")
+            # Fall through to urllib fallback
+    
+    # Fallback to urllib with SSL context
+    params = urllib.parse.urlencode({"query": query})
+    url = f"{WIKIDATA_SPARQL_ENDPOINT}?{params}"
+    
+    try:
+        # Create SSL context that doesn't verify certificates (fallback)
+        ssl_context = ssl.create_default_context()
+        ssl_context.check_hostname = False
+        ssl_context.verify_mode = ssl.CERT_NONE
+        
+        req = urllib.request.Request(url, headers=headers)
+        with urllib.request.urlopen(req, timeout=30, context=ssl_context) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError, TimeoutError) as e:
+        print(f"[Wikidata] SPARQL query failed (urllib): {e}")
+        return None
+
+
+def _parse_wikidata_date(date_str: str) -> Tuple[Optional[int], Optional[int], Optional[int]]:
+    """Parse Wikidata date string to year, month, day."""
+    if not date_str:
+        return None, None, None
+    
+    # Handle BCE dates (negative years)
+    # Wikidata format: -0044-03-15T00:00:00Z for 44 BCE
+    try:
+        if date_str.startswith("-"):
+            # BCE date
+            parts = date_str[1:].split("T")[0].split("-")
+            year = -int(parts[0])
+            month = int(parts[1]) if len(parts) > 1 else None
+            day = int(parts[2]) if len(parts) > 2 else None
+            return year, month, day
+        else:
+            # CE date
+            parts = date_str.split("T")[0].split("-")
+            year = int(parts[0])
+            month = int(parts[1]) if len(parts) > 1 else None
+            day = int(parts[2]) if len(parts) > 2 else None
+            return year, month, day
+    except (ValueError, IndexError):
+        return None, None, None
+
+
+def _parse_coordinates(coord_str: str) -> Tuple[Optional[float], Optional[float]]:
+    """Parse Wikidata coordinate string to lat, lon."""
+    if not coord_str:
+        return None, None
+    
+    # Format: Point(lon lat)
+    try:
+        if coord_str.startswith("Point("):
+            inner = coord_str[6:-1]
+            lon_str, lat_str = inner.split()
+            return float(lat_str), float(lon_str)
+    except (ValueError, IndexError):
+        pass
+    
+    return None, None
+
+
+def _results_to_events(
+    results: Dict,
+    query_lat: float,
+    query_lon: float,
+    query_year: int,
+) -> List[WikidataEvent]:
+    """Convert SPARQL results to WikidataEvent objects."""
+    events_map: Dict[str, WikidataEvent] = {}
+    
+    bindings = results.get("results", {}).get("bindings", [])
+    
+    for binding in bindings:
+        # Extract QID
+        event_uri = binding.get("event", {}).get("value", "")
+        if not event_uri:
+            continue
+        qid = event_uri.split("/")[-1]
+        
+        # Get or create event
+        if qid not in events_map:
+            name = binding.get("eventLabel", {}).get("value", "Unknown Event")
+            description = binding.get("eventDescription", {}).get("value", "")
+            
+            # Parse date
+            date_str = binding.get("date", {}).get("value", "")
+            year, month, day = _parse_wikidata_date(date_str)
+            
+            # Parse coordinates
+            coord_str = binding.get("coord", {}).get("value", "")
+            lat, lon = _parse_coordinates(coord_str)
+            
+            # Location name
+            location_name = binding.get("locationLabel", {}).get("value", "")
+            
+            # Event type
+            event_type = binding.get("typeLabel", {}).get("value", "")
+            
+            # Wikipedia URL
+            wikipedia_url = binding.get("article", {}).get("value", "")
+            
+            # Image URL
+            image_url = binding.get("image", {}).get("value", "")
+            
+            # Calculate distance and confidence
+            distance_km = 0.0
+            if lat is not None and lon is not None:
+                distance_km = _haversine(query_lat, query_lon, lat, lon)
+            
+            year_delta = abs((year or query_year) - query_year)
+            
+            # Confidence scoring
+            confidence = 0.7
+            if distance_km < 50:
+                confidence += 0.15
+            elif distance_km < 150:
+                confidence += 0.1
+            
+            if year_delta == 0:
+                confidence += 0.15
+            elif year_delta <= 5:
+                confidence += 0.1
+            
+            if wikipedia_url:
+                confidence += 0.05
+            
+            confidence = min(confidence, 0.98)
+            
+            events_map[qid] = WikidataEvent(
+                qid=qid,
+                name=name,
+                description=description,
+                year=year,
+                month=month,
+                day=day,
+                lat=lat,
+                lon=lon,
+                location_name=location_name,
+                event_type=event_type,
+                wikipedia_url=wikipedia_url,
+                image_url=image_url,
+                distance_km=round(distance_km, 2),
+                year_delta=year_delta,
+                confidence=round(confidence, 3),
+            )
+        
+        # Add participant if present
+        participant = binding.get("participantLabel", {}).get("value", "")
+        if participant and participant not in events_map[qid].participants:
+            events_map[qid].participants.append(participant)
+    
+    # Sort by relevance (lower distance + year_delta = better)
+    events = list(events_map.values())
+    events.sort(key=lambda e: e.distance_km + e.year_delta * 5 - e.confidence * 20)
+    
+    return events
+
+
+def search_events_by_geo_time(
+    lat: float,
+    lon: float,
+    year: int,
+    radius_km: float = 300.0,
+    limit: int = 10,
+    use_cache: bool = True,
+) -> List[Dict]:
+    """
+    Search Wikidata for historical events near coordinates and year.
+    
+    Args:
+        lat: Latitude
+        lon: Longitude
+        year: Target year (negative for BCE)
+        radius_km: Search radius in kilometers
+        limit: Maximum number of results
+        use_cache: Whether to use cached results
+    
+    Returns:
+        List of event dictionaries compatible with existing code
+    """
+    # Check cache first
+    cache_key = _cache_key(lat, lon, year, radius_km)
+    if use_cache:
+        cached = _get_cached(cache_key)
+        if cached is not None:
+            print(f"[Wikidata] Cache hit for {lat:.2f}, {lon:.2f}, {year}")
+            return cached[:limit]
+    
+    print(f"[Wikidata] Querying for events near {lat:.2f}, {lon:.2f}, year {year}")
+    
+    # Try primary query first
+    query = _build_sparql_query(lat, lon, year, radius_km, limit * 2)
+    results = _execute_sparql(query)
+    
+    events: List[WikidataEvent] = []
+    if results:
+        events = _results_to_events(results, lat, lon, year)
+    
+    # If no results, try fallback query
+    if not events:
+        print("[Wikidata] Primary query returned no results, trying fallback...")
+        fallback_query = _build_fallback_query(lat, lon, year, limit * 2)
+        fallback_results = _execute_sparql(fallback_query)
+        if fallback_results:
+            events = _results_to_events(fallback_results, lat, lon, year)
+    
+    # Convert to dicts and cache
+    event_dicts = [e.to_dict() for e in events[:limit]]
+    
+    if use_cache and event_dicts:
+        _save_cache(cache_key, event_dicts)
+    
+    print(f"[Wikidata] Found {len(event_dicts)} events")
+    return event_dicts
+
+
+def get_event_detail(qid: str) -> Optional[Dict]:
+    """
+    Fetch detailed information about a specific Wikidata event.
+    
+    Args:
+        qid: Wikidata QID (e.g., "Q784")
+    
+    Returns:
+        Event dictionary with full details, or None if not found
+    """
+    query = f"""
+    SELECT ?event ?eventLabel ?eventDescription ?date ?coord ?locationLabel 
+           ?participantLabel ?typeLabel ?article ?image ?causeLabel ?effectLabel
+    WHERE {{
+      BIND(wd:{qid} AS ?event)
+      
+      OPTIONAL {{ ?event wdt:P585 ?pointInTime . }}
+      OPTIONAL {{ ?event wdt:P580 ?startTime . }}
+      BIND(COALESCE(?pointInTime, ?startTime) AS ?date)
+      
+      OPTIONAL {{ ?event wdt:P625 ?coord . }}
+      OPTIONAL {{
+        ?event wdt:P276 ?location .
+        ?location wdt:P625 ?locCoord .
+      }}
+      
+      OPTIONAL {{ ?event wdt:P710 ?participant . }}
+      OPTIONAL {{ ?event wdt:P31 ?type . }}
+      OPTIONAL {{ ?event wdt:P828 ?cause . }}
+      OPTIONAL {{ ?event wdt:P1542 ?effect . }}
+      OPTIONAL {{ ?event wdt:P18 ?image . }}
+      
+      OPTIONAL {{
+        ?article schema:about ?event ;
+                 schema:isPartOf <https://en.wikipedia.org/> .
+      }}
+      
+      SERVICE wikibase:label {{ bd:serviceParam wikibase:language "en" . }}
+    }}
+    LIMIT 50
+    """
+    
+    results = _execute_sparql(query)
+    if not results:
+        return None
+    
+    events = _results_to_events(results, 0, 0, 0)
+    if events:
+        event = events[0]
+        event_dict = event.to_dict()
+        
+        # Extract causes and effects from results
+        bindings = results.get("results", {}).get("bindings", [])
+        causes = set()
+        effects = set()
+        for binding in bindings:
+            cause = binding.get("causeLabel", {}).get("value", "")
+            effect = binding.get("effectLabel", {}).get("value", "")
+            if cause:
+                causes.add(cause)
+            if effect:
+                effects.add(effect)
+        
+        event_dict["causes"] = list(causes)
+        event_dict["effects"] = list(effects)
+        event_dict["relationships"] = {
+            "causes": list(causes),
+            "consequences": list(effects),
+        }
+        
+        return event_dict
+    
+    return None
+
+
+def search_events_by_name(name: str, limit: int = 5) -> List[Dict]:
+    """
+    Search Wikidata for events by name.
+    
+    Args:
+        name: Event name to search for
+        limit: Maximum results
+    
+    Returns:
+        List of matching events
+    """
+    # Escape special characters
+    escaped_name = name.replace('"', '\\"')
+    
+    query = f"""
+    SELECT DISTINCT ?event ?eventLabel ?eventDescription ?date ?coord ?locationLabel ?article
+    WHERE {{
+      ?event wdt:P31/wdt:P279* wd:Q1656682 .
+      ?event rdfs:label ?label .
+      FILTER(LANG(?label) = "en")
+      FILTER(CONTAINS(LCASE(?label), LCASE("{escaped_name}")))
+      
+      OPTIONAL {{ ?event wdt:P585 ?pointInTime . }}
+      OPTIONAL {{ ?event wdt:P580 ?startTime . }}
+      BIND(COALESCE(?pointInTime, ?startTime) AS ?date)
+      
+      OPTIONAL {{ ?event wdt:P625 ?coord . }}
+      OPTIONAL {{
+        ?event wdt:P276 ?location .
+        ?location wdt:P625 ?locCoord .
+      }}
+      
+      OPTIONAL {{
+        ?article schema:about ?event ;
+                 schema:isPartOf <https://en.wikipedia.org/> .
+      }}
+      
+      SERVICE wikibase:label {{ bd:serviceParam wikibase:language "en" . }}
+    }}
+    LIMIT {limit}
+    """
+    
+    results = _execute_sparql(query)
+    if not results:
+        return []
+    
+    events = _results_to_events(results, 0, 0, 0)
+    return [e.to_dict() for e in events]
+
+
+# MCP-compatible function exports
+def mcp_search_historical_events(
+    latitude: float,
+    longitude: float,
+    year: int,
+    radius_km: float = 300.0,
+    limit: int = 10,
+) -> Dict:
+    """
+    MCP tool: Search for historical events by coordinates and year.
+    
+    This queries Wikidata for events that occurred near the specified
+    location and time, returning structured event data suitable for
+    prompt generation.
+    """
+    try:
+        events = search_events_by_geo_time(
+            lat=latitude,
+            lon=longitude,
+            year=year,
+            radius_km=radius_km,
+            limit=limit,
+        )
+        return {
+            "success": True,
+            "query": {
+                "latitude": latitude,
+                "longitude": longitude,
+                "year": year,
+                "radius_km": radius_km,
+            },
+            "count": len(events),
+            "events": events,
+            "source": "wikidata",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+def mcp_get_event_by_qid(qid: str) -> Dict:
+    """
+    MCP tool: Get detailed information about a Wikidata event.
+    """
+    try:
+        event = get_event_detail(qid)
+        if event:
+            return {
+                "success": True,
+                "event": event,
+            }
+        return {
+            "success": False,
+            "error": f"Event {qid} not found",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+