Lore Reconcile

3-way reconciliation system for Database ↔ GitHub ↔ Notion bidirectional sync

Overview

Generic content synchronization infrastructure for bidirectional sync between internal databases and external systems (Notion, GitHub, Jira, Linear). Schema-driven configuration with fuzzy matching and conflict detection.

Features

• ✅ 3-Way Venn Diagram Reconciliation - Visualize sync state across systems
• ✅ Fuzzy Matching - Levenshtein similarity for duplicate detection
• ✅ Explicit Matching - Database sync_state tracking
• ✅ Bidirectional Sync - Database ↔ Notion (full parity)
• ✅ Selective Sync - Database ↔ GitHub (filtered by criteria)
• ✅ Schema-Driven - Field mappings via JSON configuration
• ✅ Conflict Detection - Identify pending changes and duplicates

Quick Start

Installation

# Install from PyPI
pip install lore-reconcile

# With Notion support
pip install lore-reconcile[notion]

# Or install from source
git clone https://github.com/toilville/lore-reconcile.git
cd lore-reconcile
pip install -e .[notion,dev]

Basic Usage

# Set environment
export DATABASE_URL="postgresql://user:pass@localhost:5432/db"
export NOTION_TOKEN="secret_..."
export NOTION_DATABASE_ID="abc123..."

# Run reconciliation
reconcile --schema schemas/default.json

# Show Venn diagram
reconcile venn

# Sync missing items
reconcile sync --to-notion
reconcile sync --from-notion

Architecture

Database (core.frames)
    ↓
Fetchers → Matchers → Reconciler → Sync Actions
    ↑           ↑                        ↓
External    Fuzzy/Explicit         Notion/GitHub
Sync State  Matching               Push Operations

Configuration

Schema File (external_sync_schemas.json)

{
  "notion": {
    "database_id_env_var": "NOTION_DATABASE_ID",
    "field_mappings": [
      {
        "notion_property": "Task name",
        "wish_field": "title",
        "type": "title",
        "required": true
      }
    ]
  },
  "github": {
    "org": "your-org",
    "repos": ["your-repo"],
    "field_mappings": [...]
  },
  "reconciliation": {
    "auto_link_threshold": 0.95,
    "manual_review_threshold": 0.85
  }
}

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
NOTION_TOKEN	No	Notion API token (for Notion sync)
NOTION_DATABASE_ID	No	Notion database ID
GITHUB_TOKEN	No	GitHub API token (uses gh CLI)

Components

Fetchers

• wish_fetcher.py - Fetch frames/wishes from database

Matchers

• explicit.py - Match via external_sync_state table
• fuzzy.py - Levenshtein similarity matching

Sync Actions

• sync_actions.py - Push to Notion/GitHub with field mapping

CLI

• cli.py - 3-way Venn diagram visualization

Database Adapter Pattern

Supports multiple databases via adapter pattern:

from reconcile.adapters import PostgresFrameAdapter

adapter = PostgresFrameAdapter(database_url)
frames = await adapter.fetch_frames(filters={"status": "pending"})

Examples

See examples/ directory for:

• Basic reconciliation workflow
• Custom schema configuration
• Sync parity scripts
• GitHub/Notion adapter usage

Development

# Install dev dependencies
pip install -e .[notion,dev]

# Run tests
pytest

# With coverage
pytest --cov=reconcile --cov-report=html

License

All Rights Reserved - Toilville LLC

For licensing inquiries: legal@toilville.com

Part of Toilville LLC

Built by Toilville LLC - Ethical AI consultancy focused on content governance and workflow automation.