{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Hawksight-AI/semantica/blob/main/cookbook/advanced/10_Temporal_Knowledge_Graphs.ipynb)\n",
    "\n",
    "# Temporal Knowledge Graphs\n",
    "\n",
    "## Overview\n",
    "\n",
    "This notebook demonstrates advanced temporal knowledge graph capabilities using TemporalGraphQuery, TemporalPatternDetector, TemporalVersionManager, and TemporalVisualizer.\n",
    "\n",
    "\n",
    "**Documentation**: [API Reference](https://semantica.readthedocs.io/reference/kg/)\n",
    "\n",
    "### Learning Objectives\n",
    "\n",
    "- Use TemporalGraphQuery for time-aware queries\n",
    "- Use TemporalPatternDetector to detect temporal patterns\n",
    "- Use TemporalVersionManager for temporal versioning and snapshots\n",
    "- Use TemporalVisualizer to visualize temporal data\n",
    "\n",
    "## Installation\n",
    "\n",
    "Install Semantica from PyPI:\n",
    "\n",
    "```bash\n",
    "pip install semantica\n",
    "# Or with all optional dependencies:\n",
    "pip install semantica[all]\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "## Workflow: Build Temporal KG → Time-Aware Queries → Pattern Detection → Version Management → Visualization\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.kg import GraphBuilder, TemporalGraphQuery, TemporalPatternDetector, TemporalVersionManager\n",
    "from semantica.visualization import TemporalVisualizer\n",
    "from datetime import datetime\n",
    "\n",
    "builder = GraphBuilder()\n",
    "\n",
    "entities = [\n",
    "    {\"id\": \"e1\", \"type\": \"Organization\", \"name\": \"Apple Inc.\", \"properties\": {\"founded\": \"1976\"}},\n",
    "    {\"id\": \"e2\", \"type\": \"Person\", \"name\": \"Steve Jobs\", \"properties\": {\"born\": \"1955\"}}\n",
    "]\n",
    "\n",
    "relationships = [\n",
    "    {\"source\": \"e2\", \"target\": \"e1\", \"type\": \"founded\", \"properties\": {\"timestamp\": \"1976-04-01\"}}\n",
    "]\n",
    "\n",
    "temporal_kg = builder.build(entities, relationships)\n",
    "\n",
    "print(f\"Built temporal knowledge graph with {len(entities)} entities\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Time-Aware Queries\n",
    "\n",
    "Query the graph at specific time points.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temporal_query = TemporalGraphQuery()\n",
    "\n",
    "query_result = temporal_query.query_time_range(\n",
    "    graph=temporal_kg,\n",
    "    query=\"Find entities founded in 1976\",\n",
    "    start_time=\"1976-01-01\",\n",
    "    end_time=\"1976-12-31\"\n",
    ")\n",
    "\n",
    "print(f\"Time-aware query returned {len(query_result.get('entities', []))} entities\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Temporal Pattern Detection\n",
    "\n",
    "Detect temporal patterns in the graph.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pattern_detector = TemporalPatternDetector()\n",
    "\n",
    "patterns = pattern_detector.detect_temporal_patterns(\n",
    "    temporal_kg,\n",
    "    pattern_type=\"sequence\",\n",
    "    min_frequency=1\n",
    ")\n",
    "\n",
    "print(f\"Detected {len(patterns)} temporal patterns\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Version Management\n",
    "\n",
    "Manage temporal versions and snapshots.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "version_manager = TemporalVersionManager()\n",
    "\n",
    "snapshot = version_manager.create_snapshot(temporal_kg, timestamp=datetime.now())\n",
    "\n",
    "print(f\"Created temporal snapshot at {snapshot.get('timestamp', 'N/A')}\")\n",
    "print(f\"Snapshot contains {len(snapshot.get('entities', []))} entities\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 5: Temporal Visualization\n",
    "\n",
    "Visualize temporal data.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temporal_visualizer = TemporalVisualizer()\n",
    "\n",
    "visualization = temporal_visualizer.visualize_timeline(temporal_kg, output=\"interactive\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "You've learned advanced temporal knowledge graph capabilities:\n",
    "\n",
    "- **TemporalGraphQuery**: Time-aware graph querying\n",
    "- **TemporalPatternDetector**: Temporal pattern detection\n",
    "- **TemporalVersionManager**: Temporal versioning and snapshots\n",
    "- **TemporalVisualizer**: Temporal data visualization\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Snapshot Comparison and Version History\n",
    "\n",
    "Compare graph snapshots across time and visualize version history."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create multiple versions\n",
    "version_manager = TemporalVersionManager()\n",
    "version_2020 = version_manager.create_version(temporal_kg, timestamp=\"2020-01-01\", version_label=\"v2020\")\n",
    "# Simulate changes for 2023\n",
    "temporal_kg_updated = {\n",
    "    \"entities\": temporal_kg.get(\"entities\", []),\n",
    "    \"relationships\": temporal_kg.get(\"relationships\", []) + [\n",
    "        {\"source\": \"e1\", \"target\": \"e2\", \"type\": \"collaborated_with\", \"valid_from\": \"2023-01-01\"}\n",
    "    ]\n",
    "}\n",
    "version_2023 = version_manager.create_version(temporal_kg_updated, timestamp=\"2023-01-01\", version_label=\"v2023\")\n",
    "\n",
    "# Build snapshots dict for comparison\n",
    "snapshots = {\n",
    "    version_2020[\"timestamp\"]: version_2020,\n",
    "    version_2023[\"timestamp\"]: version_2023\n",
    "}\n",
    "\n",
    "# Visualize snapshot comparison\n",
    "fig_snapshots = temporal_visualizer.visualize_snapshot_comparison(snapshots, output=\"interactive\")\n",
    "\n",
    "# Build version history list\n",
    "version_history = [\n",
    "    {\"version\": version_2020.get(\"label\", \"v2020\"), \"timestamp\": version_2020.get(\"timestamp\"), \"changes\": f\"Entities: {len(version_2020.get('entities', []))}, Relationships: {len(version_2020.get('relationships', []))}\"},\n",
    "    {\"version\": version_2023.get(\"label\", \"v2023\"), \"timestamp\": version_2023.get(\"timestamp\"), \"changes\": f\"Entities: {len(version_2023.get('entities', []))}, Relationships: {len(version_2023.get('relationships', []))}\"}\n",
    "]\n",
    "\n",
    "# Visualize version history\n",
    "fig_versions = temporal_visualizer.visualize_version_history(version_history, output=\"interactive\")\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
