Metadata-Version: 2.4
Name: lore-reconcile
Version: 1.0.2
Summary: 3-way reconciliation for Database ↔ GitHub ↔ Notion sync
Home-page: https://github.com/toilville/lore-reconcile
Author: Toilville LLC
Author-email: engineering@toilville.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: python-Levenshtein>=0.21.1
Provides-Extra: notion
Requires-Dist: notion-client>=2.0.0; extra == "notion"
Requires-Dist: requests>=2.31.0; extra == "notion"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.3; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Lore Reconcile

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

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: All Rights Reserved](https://img.shields.io/badge/License-All%20Rights%20Reserved-red.svg)](LICENSE)

## 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

```bash
# 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

```bash
# 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)

```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:

```python
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

```bash
# 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](https://toilville.com) - Ethical AI consultancy focused on content governance and workflow automation.
