ccrt 0.1.0__py3-none-any.whl

ccrt/tui.py

@@ -0,0 +1,349 @@
+"""Optional full-screen terminal dashboard for reviewing candidate links.
+
+The module uses only the standard-library curses package and can be removed
+without changing the matching or review data formats.
+"""
+
+from __future__ import annotations
+
+import sys
+import textwrap
+from collections import defaultdict
+
+from ccrt.interactive import _coordinates, _date
+
+try:
+    import curses as _curses
+except ImportError:  # Optional on platforms without curses.
+    _curses = None
+
+
+class ReviewDashboard:
+    """Navigation and decisions, independent of the terminal renderer."""
+
+    def __init__(self, result, review, *, reviewer, save, left_id=None):
+        review.validate(result)
+        if not reviewer.strip():
+            raise ValueError("--reviewer needs a nonempty name")
+        self.result = result
+        self.review = review
+        self.reviewer = reviewer
+        self.save = save
+        self.groups = defaultdict(list)
+        for candidate in result.candidates:
+            self.groups[candidate.left.source_id].append(candidate)
+        if left_id is not None and left_id not in self.groups:
+            raise ValueError(f"no candidate group for left source ID {left_id}")
+        self.decisions = {decision.candidate_id: decision for decision in review.decisions}
+        self.show_all = False
+        self.group_ids = []
+        self.group_index = 0
+        self.candidate_index = 0
+        self.detail_scroll = 0
+        self.message = "Arrows: groups/candidates  a/r/u: decide  e: note  f: filter  g: jump  q: quit"
+        self.refresh(start=left_id)
+
+    def refresh(self, *, start=None):
+        current = start or (self.group_ids[self.group_index] if self.group_ids else None)
+        self.group_ids = sorted(
+            (
+                key
+                for key, items in self.groups.items()
+                if key == current
+                or self.show_all
+                or any(self.decisions[c.candidate_id].status == "unresolved" for c in items)
+            ),
+            key=lambda key: (-self.groups[key][0].score, key),
+        )
+        self.group_index = self.group_ids.index(current) if current in self.group_ids else 0
+        self.candidate_index = 0
+        self.detail_scroll = 0
+
+    @property
+    def candidates(self):
+        return self.groups[self.group_ids[self.group_index]] if self.group_ids else []
+
+    @property
+    def candidate(self):
+        return self.candidates[self.candidate_index] if self.candidates else None
+
+    def move_group(self, delta):
+        if self.group_ids:
+            self.group_index = (self.group_index + delta) % len(self.group_ids)
+            self.candidate_index = 0
+            self.detail_scroll = 0
+
+    def move_candidate(self, delta):
+        if self.candidates:
+            self.candidate_index = (self.candidate_index + delta) % len(self.candidates)
+            self.detail_scroll = 0
+
+    def jump(self, left_id):
+        if left_id not in self.groups:
+            self.message = f"No candidate group for {left_id}"
+            return
+        self.refresh(start=left_id)
+        self.message = f"Jumped to {left_id}"
+
+    def toggle_filter(self):
+        self.show_all = not self.show_all
+        self.refresh()
+        self.message = "Showing all groups" if self.show_all else "Showing unresolved groups"
+
+    def decide(self, status, *, note=None):
+        candidate = self.candidate
+        if candidate is None:
+            return
+        old = self.decisions[candidate.candidate_id]
+        updated = self.review.decide(
+            candidate.candidate_id,
+            status,
+            reviewer=self.reviewer,
+            note=old.note if note is None else note,
+        )
+        self.save(updated)
+        self.review = updated
+        self.decisions[candidate.candidate_id] = next(
+            decision for decision in updated.decisions if decision.candidate_id == candidate.candidate_id
+        )
+        self.message = f"Saved {status}: {candidate.left.source_id}/{candidate.right.source_id}"
+
+    def set_note(self, note):
+        candidate = self.candidate
+        if candidate is not None:
+            self.decide(self.decisions[candidate.candidate_id].status, note=note)
+
+
+def _put(screen, y, x, value, width, attr=0):
+    if width < 1 or y < 0 or x < 0:
+        return
+    try:
+        screen.addnstr(y, x, str(value).replace("\n", " "), width, attr)
+    except Exception as exc:
+        # curses.error is raised when a terminal rejects a bottom-right write.
+        if _curses is None or not isinstance(exc, _curses.error):
+            raise
+
+
+def _field(lines, label, value, width):
+    value = " ".join(str("not supplied" if value is None or value == "" else value).split())
+    prefix = f"{label}: "
+    lines.extend(textwrap.wrap(prefix + value, width=max(12, width), subsequent_indent="  ") or [prefix])
+
+
+def _account_lines(lines, record, width):
+    raw = record.raw
+    lines.append(f"{record.source.upper()} {record.source_id}")
+    _field(lines, "Date", _date(record), width)
+    _field(lines, "Place", raw.get("where_description") or raw.get("location"), width)
+    _field(lines, "Coordinates", _coordinates(record), width)
+    _field(lines, "Actor 1", record.actor1, width)
+    _field(lines, "Actor 2", record.actor2, width)
+    _field(lines, "Deaths", record.total_deaths_best, width)
+    _field(lines, "Location precision", record.geo_precision, width)
+    for label, key in (
+        ("Notes", "notes"),
+        ("Source articles", "source_article"),
+        ("Original sources", "source_original"),
+    ):
+        if raw.get(key):
+            _field(lines, label, raw[key], width)
+    lines.append("")
+
+
+def detail_lines(dashboard, width):
+    candidate = dashboard.candidate
+    if candidate is None:
+        return ["No candidate groups in this view. Press f to show all groups."]
+    decision = dashboard.decisions[candidate.candidate_id]
+    lines = []
+    _account_lines(lines, candidate.left, width)
+    _account_lines(lines, candidate.right, width)
+    lines.append("COMPARISON")
+    _field(
+        lines,
+        "Distance",
+        f"{candidate.distance_km:.3f} km (limit {dashboard.result.config.max_km:g} km)",
+        width,
+    )
+    _field(
+        lines,
+        "Date gap",
+        f"{candidate.days_apart} days (limit {dashboard.result.config.max_days} days)",
+        width,
+    )
+    _field(lines, "Proximity score", f"{candidate.score:.3f} (ranking only)", width)
+    _field(lines, "Warnings", ", ".join(candidate.warnings) or "none", width)
+    _field(lines, "Decision", decision.status, width)
+    _field(lines, "Reviewer note", decision.note, width)
+    lines.append("")
+    lines.extend(
+        textwrap.wrap(
+            "Events can share coordinates. Check the dates, actors, and notes.",
+            width=max(12, width),
+        )
+    )
+    return lines
+
+
+def _draw(screen, dashboard, curses):
+    height, width = screen.getmaxyx()
+    screen.erase()
+    if height < 20 or width < 95:
+        _put(screen, 0, 0, "CCRT review dashboard", width - 1, curses.A_BOLD)
+        _put(screen, 2, 0, "Resize terminal to at least 95 columns x 20 rows. Press q to quit.", width - 1)
+        screen.refresh()
+        return
+    left_width = 23
+    middle_width = 39
+    detail_x = left_width + middle_width + 2
+    detail_width = width - detail_x - 1
+    visible = height - 6
+    counts = defaultdict(int)
+    for decision in dashboard.review.decisions:
+        counts[decision.status] += 1
+    accent = curses.color_pair(1) if curses.has_colors() else 0
+    _put(screen, 0, 0, " CCRT/Review ", width - 1, curses.A_REVERSE | curses.A_BOLD | accent)
+    _put(
+        screen,
+        1,
+        1,
+        f"Reviewer {dashboard.reviewer}  |  {counts['accepted']} accepted  {counts['rejected']} rejected"
+        f"  {counts['unresolved']} unresolved  |  {len(dashboard.group_ids)} groups",
+        width - 2,
+    )
+    _put(screen, 3, 1, "UCDP EVENTS", left_width - 2, curses.A_BOLD)
+    _put(screen, 3, left_width + 1, "ACLED CANDIDATES", middle_width - 2, curses.A_BOLD)
+    _put(screen, 3, detail_x, "SOURCE ACCOUNTS", detail_width, curses.A_BOLD)
+    for y in range(3, height - 2):
+        _put(screen, y, left_width, "|", 1)
+        _put(screen, y, detail_x - 1, "|", 1)
+    if dashboard.group_ids:
+        start = max(0, dashboard.group_index - visible // 2)
+        start = min(start, max(0, len(dashboard.group_ids) - visible))
+        for offset, index in enumerate(range(start, min(start + visible, len(dashboard.group_ids)))):
+            group_id = dashboard.group_ids[index]
+            pending = sum(
+                dashboard.decisions[c.candidate_id].status == "unresolved" for c in dashboard.groups[group_id]
+            )
+            marker = ">" if index == dashboard.group_index else " "
+            value = f"{marker} {group_id}  ({pending} open)"
+            attr = curses.A_REVERSE if index == dashboard.group_index else 0
+            _put(screen, 4 + offset, 1, value, left_width - 2, attr)
+        candidates = dashboard.candidates
+        start = max(0, dashboard.candidate_index - visible // 2)
+        start = min(start, max(0, len(candidates) - visible))
+        for offset, index in enumerate(range(start, min(start + visible, len(candidates)))):
+            candidate = candidates[index]
+            status = dashboard.decisions[candidate.candidate_id].status
+            code = {"accepted": "A", "rejected": "R", "unresolved": "?"}[status]
+            marker = ">" if index == dashboard.candidate_index else " "
+            value = (
+                f"{marker} {code} {candidate.right.source_id}  {candidate.score:.3f}"
+                f"  {candidate.distance_km:.1f}km"
+            )
+            attr = curses.A_REVERSE if index == dashboard.candidate_index else 0
+            if curses.has_colors() and index != dashboard.candidate_index:
+                attr = curses.color_pair({"accepted": 2, "rejected": 3, "unresolved": 4}[status])
+            _put(screen, 4 + offset, left_width + 1, value, middle_width - 2, attr)
+    lines = detail_lines(dashboard, detail_width)
+    max_scroll = max(0, len(lines) - visible)
+    dashboard.detail_scroll = min(dashboard.detail_scroll, max_scroll)
+    for offset, line in enumerate(lines[dashboard.detail_scroll : dashboard.detail_scroll + visible]):
+        _put(screen, 4 + offset, detail_x, line, detail_width)
+    _put(
+        screen,
+        height - 2,
+        0,
+        " Left/Right group  Up/Down candidate  PgUp/PgDn scroll  a/r/u decide  e note  f filter  g jump  q quit ",
+        width - 1,
+        curses.A_REVERSE,
+    )
+    _put(screen, height - 1, 1, dashboard.message, width - 2)
+    screen.refresh()
+
+
+def _prompt(screen, curses, label):
+    height, width = screen.getmaxyx()
+    screen.move(height - 1, 0)
+    screen.clrtoeol()
+    _put(screen, height - 1, 0, label, width - 1)
+    screen.refresh()
+    curses.echo()
+    try:
+        curses.curs_set(1)
+    except curses.error:
+        pass
+    try:
+        value = screen.getstr(height - 1, min(len(label), width - 2), 1000)
+        return value.decode("utf-8", errors="replace").strip()
+    finally:
+        curses.noecho()
+        try:
+            curses.curs_set(0)
+        except curses.error:
+            pass
+
+
+def _loop(screen, dashboard, curses):
+    if curses.has_colors():
+        curses.start_color()
+        try:
+            curses.use_default_colors()
+            background = -1
+        except curses.error:
+            background = curses.COLOR_BLACK
+        for number, foreground in (
+            (1, curses.COLOR_CYAN),
+            (2, curses.COLOR_GREEN),
+            (3, curses.COLOR_RED),
+            (4, curses.COLOR_YELLOW),
+        ):
+            curses.init_pair(number, foreground, background)
+    try:
+        curses.curs_set(0)
+    except curses.error:
+        pass
+    screen.keypad(True)
+    while True:
+        _draw(screen, dashboard, curses)
+        key = screen.getch()
+        if key in (ord("q"), ord("Q")):
+            return
+        if key in (curses.KEY_LEFT, ord("h")):
+            dashboard.move_group(-1)
+        elif key in (curses.KEY_RIGHT, ord("l")):
+            dashboard.move_group(1)
+        elif key in (curses.KEY_UP, ord("k")):
+            dashboard.move_candidate(-1)
+        elif key in (curses.KEY_DOWN, ord("j")):
+            dashboard.move_candidate(1)
+        elif key == curses.KEY_PPAGE:
+            dashboard.detail_scroll = max(0, dashboard.detail_scroll - 8)
+        elif key == curses.KEY_NPAGE:
+            dashboard.detail_scroll += 8
+        elif key in (ord("a"), ord("r"), ord("u")):
+            dashboard.decide({ord("a"): "accepted", ord("r"): "rejected", ord("u"): "unresolved"}[key])
+        elif key == ord("e") and dashboard.candidate is not None:
+            dashboard.set_note(_prompt(screen, curses, "Reviewer note (blank clears): "))
+        elif key == ord("f"):
+            dashboard.toggle_filter()
+        elif key == ord("g"):
+            value = _prompt(screen, curses, "UCDP/source ID: ")
+            if value:
+                dashboard.jump(value)
+
+
+def run_tui(result, review, *, reviewer, save, left_id=None):
+    """Start the optional dashboard in an interactive terminal."""
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        raise ValueError("review-tui needs an interactive terminal; use review-interactive for pipes")
+    if _curses is None:
+        raise ValueError("review-tui requires a terminal with Python curses support") from None
+    dashboard = ReviewDashboard(result, review, reviewer=reviewer, save=save, left_id=left_id)
+    try:
+        _curses.wrapper(lambda screen: _loop(screen, dashboard, _curses))
+    except KeyboardInterrupt:
+        return
+    except _curses.error as exc:
+        raise ValueError(f"terminal could not start review-tui: {exc}") from exc

ccrt-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: ccrt
+Version: 0.1.0
+Summary: Experimental toolkit for reviewing candidate links between conflict incident records
+Author: Fabian Figueroa
+License-Expression: MIT
+Project-URL: Repository, https://github.com/FabianFig/ccrt
+Project-URL: Issues, https://github.com/FabianFig/ccrt/issues
+Keywords: conflict,record-linkage,ucdp,acled,research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: python-dotenv<2,>=1
+Provides-Extra: tables
+Requires-Dist: pandas>=2.2; extra == "tables"
+Requires-Dist: pyarrow>=15; extra == "tables"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Requires-Dist: nbformat>=5.10; extra == "dev"
+Requires-Dist: nbclient>=0.10; extra == "dev"
+Requires-Dist: ipykernel>=6; extra == "dev"
+Dynamic: license-file
+
+# Conflict Casualty Reconciliation Toolkit (CCRT)
+
+CCRT compares source accounts of conflict incidents. It imports UCDP GED and ACLED
+records, proposes possible links, supports human review, and exports results while
+preserving each source's original claims.
+
+**Status:** `0.1.0` is an experimental research library.
+
+## Installation
+
+CCRT supports Python 3.10–3.14. To install a published release:
+
+```bash
+python -m pip install ccrt
+```
+
+Install `ccrt[tables]` for pandas and Parquet support. From a checkout, use
+`python -m pip install -e .`, or `python -m pip install -e '.[tables,dev]'` for the
+project's development checks.
+
+## Quickstart
+
+The example files contain invented incidents in Exampleland. From the repository
+root, with an unused `work/` directory:
+
+```bash
+mkdir -p work
+ccrt import ucdp examples/ucdp_synthetic.csv work/ucdp.json --version 26.1
+ccrt import acled examples/acled_synthetic.csv work/acled.json --version synthetic-2026-09-24
+ccrt match work/ucdp.json work/acled.json work/matches
+ccrt report work/matches/run.json --review work/matches/review.json
+```
+
+The match run contains three candidate links and four unlinked source records.
+Inspect `work/matches/candidates.csv`, then use the [usage guide](docs/usage.md) to
+record decisions and export reviewed results. CCRT does not overwrite existing
+outputs.
+
+## Python API
+
+```python
+from ccrt import MatchConfig, load_acled_csv, load_ucdp_csv, reconcile
+
+ucdp = load_ucdp_csv("examples/ucdp_synthetic.csv", version="26.1")
+acled = load_acled_csv("examples/acled_synthetic.csv", version="synthetic-2026-09-24")
+result = reconcile(ucdp, acled, config=MatchConfig(max_days=3, max_km=25))
+
+for candidate in result.candidates:
+    print(candidate.left.source_id, candidate.right.source_id, candidate.score)
+```
+
+The [API reference](docs/api.md) covers review decisions, saved runs, reports, and
+exports.
+
+## Sources and capabilities
+
+- UCDP GED 25.1 and 26.1 CSV files with modern field names, and authenticated GED
+  API access.
+- ACLED event CSV exports with current lowercase field names. The supplied version
+  is a label for the exact export snapshot.
+- Source-preserving JSON bundles, candidate generation, CSV and terminal review,
+  review reports, CSV export, and optional Parquet export.
+
+See [source mappings](docs/source-mappings.md) for supported fields, precision
+handling, and provenance. The [teaching notebook](examples/reconciliation_walkthrough.ipynb)
+provides another offline example.
+
+## Limitations
+
+CCRT compares source accounts; it does not establish objective incident identity.
+Candidate scores are uncalibrated proximity rankings, and generating a candidate
+does not confirm correspondence. Real-world linkage accuracy has not been
+independently evaluated. CCRT does not reconcile casualty totals or estimate
+underreporting. See [validation notes](docs/validation.md) for software checks and
+research limits.
+
+## Contributing and licence
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), the [changelog](CHANGELOG.md), and the
+[release procedure](docs/releasing.md). The code and synthetic examples are under
+the [MIT licence](LICENSE). UCDP and ACLED data have separate access, attribution,
+and redistribution terms; obtain source access and check the terms for your snapshot.

ccrt-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+ccrt/__init__.py,sha256=uFFoUQpSU5orZCnTh37Wq1dGL7aXbp4QaXH_8ulHdk8,1045
+ccrt/__main__.py,sha256=S0BYDZBiP__Qc2xpoQCvXphAZERBBVWnJuiDpP1Fu3s,52
+ccrt/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+ccrt/cli.py,sha256=oe_Hvy98BB5X_Q8P1wrE4w5joEB9erupm_sIihIWLmQ,10654
+ccrt/client.py,sha256=xGdfjFlehAq5Zkl6434uG6O2iBAqqTW0iTB3a8H7p-A,7467
+ccrt/config.py,sha256=krGpm8JVF4Jris-S41e3DESnBFoAQwMaalZ256Z9Deo,821
+ccrt/evaluation.py,sha256=GYkhkFQ64t0_ywqzo-FhXpSrbjSsyoGOXGMm1IvmyGs,1182
+ccrt/export.py,sha256=AbY4MNtJkwWxCmMwtch3Pu0MdBLDIwG3SN8HYLoA7HY,5854
+ccrt/interactive.py,sha256=TV9a4eGyKU_zeJRUI1DWIkFYXEqaW-2kHg_WrycMI5U,6893
+ccrt/merge.py,sha256=hsqb9Z_FagH3Gz5sls295DILW-T7LlB0epbMF-hc29Q,6826
+ccrt/report.py,sha256=fLjYf6gTfPjYjvWFNxCX-a7hSPguYl8hjPz4Dtoy7Dw,7246
+ccrt/review.py,sha256=mWwdtBIm4D8HxHyRb8oDAQpVYBnDZ3tE5sQQS05S-O0,2208
+ccrt/schema.py,sha256=xv7CPAQAhoyO4pTi5VFNHWKZB0K7FqurKugjbtqnAdY,6086
+ccrt/storage.py,sha256=C7bjhUOD_1q0LoQPiuzwnekFydaXBsGCxsQglEbNnd8,5646
+ccrt/tui.py,sha256=HEQXAmvkUUl0DnZvu_Nigmb92vHQtb287KfwMvjoEtc,13777
+ccrt/loaders/__init__.py,sha256=w3QJVZn_aAah7TRRdTi50hMy5ccwgUBr7LSM5BZ8S-s,224
+ccrt/loaders/acled.py,sha256=TR2j1E0rYLoDv6xdFHd6kM9wJb6s6VFrMjTGeMgTFYk,2231
+ccrt/loaders/base.py,sha256=j8WAtTUMl9jpJGqQXzKCs4KaQvX_h80IFmVu9bL60gg,5406
+ccrt/loaders/ucdp.py,sha256=c1WdSaOvF3pI03BkD76BJtpKpSOHiJZbSdp4cYQemE8,2619
+ccrt-0.1.0.dist-info/licenses/LICENSE,sha256=9YcilvTlVUEkAU2AGRryIa5Cm8ifuarTcJNnJysqPgk,1072
+ccrt-0.1.0.dist-info/METADATA,sha256=ogoB2_DPetdbQouA-twn20GGbqD6-Q6zO__plsak2lU,4691
+ccrt-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+ccrt-0.1.0.dist-info/entry_points.txt,sha256=AuzMBnYrcAv0YiFeALcmq5KGG1bk8XuF27hDlS6IXYU,39
+ccrt-0.1.0.dist-info/top_level.txt,sha256=Le69kL4hkte_9YHyXhkdW3ZpK75LnHDyvhKQ5GkQBTk,5
+ccrt-0.1.0.dist-info/RECORD,,

ccrt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ccrt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ccrt = ccrt.cli:main

ccrt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabian Figueroa
+
+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.

ccrt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ccrt