Kinsaga

A family chronicle library and CLI for managing timestamped, categorized life events.

Overview

Kinsaga (kin + saga) provides data structures and utilities for creating and managing family chronicles where life events are:

• Timestamped with flexible date precision (year, month, day, or uncertain with ? suffix)
• Categorized into customizable life themes (education, family, travel, hobbies, etc.)
• Person-centric - each family member has their own timeline
• Location-aware - optional GPS coordinates with Nominatim geocoding support
• Attachment-friendly - link photos, documents, and other media to events

Installation

cargo build --release

Quick Start

# Set your chronicle file
export KINSAGA_INPUT=examples/sample-chronicle.json

# List all persons
kinsaga list

# View someone's timeline
kinsaga timeline alice

# Search across all persons
kinsaga search "Tokyo"

# Search with regex
kinsaga search "Tokyo|Kyoto" --regex

# Validate chronicle structure
kinsaga validate

# Validate GPS coordinates against Nominatim
kinsaga validate --gps

# Add a new fact
kinsaga add-fact alice -d 2024-07-15 -c travel -t "Trip to Paris" --country France --place Paris

Features

CLI Commands

Output Formats

All query commands support --format / -f with: text (default), csv, md, json

GPS Validation

Validate and enrich location data using OpenStreetMap's Nominatim:

# Check existing coordinates match stored country/place
kinsaga validate --gps

# Suggest coordinates for locations without GPS
kinsaga validate --gps --suggest

# Apply top suggestions to chronicle
kinsaga validate --gps --suggest --apply --in-place

Supports ISO country codes (CH, JP, US, etc.) and native language names (Schweiz, 日本, etc.).

Chronicle Format

{
  "version": "1.0",
  "title": "Family Chronicle",
  "categories": [
    { "id": "travel", "label": "Travels", "color": "#81C784" }
  ],
  "persons": [
    {
      "id": "alice",
      "name": "Alice Smith",
      "facts": [
        {
          "id": "uuid-here",
          "date": "2024-07-15",
          "category": "travel",
          "text": "Trip to Paris",
          "location": {
            "country": "France",
            "place": "Paris",
            "coordinates": { "lat": 48.8566, "lon": 2.3522 }
          }
        }
      ]
    }
  ]
}

Date Formats

Documentation

See STATUS.md for detailed documentation including:

• Complete CLI reference with all options
• Library API documentation
• Validation checks
• Project roadmap

License

Licensed under GPL-3.0-or-later.