Add babel-explorer: a CLI for querying Babel cross-references via DuckDB and NodeNorm

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 17 * * 2"  # Tuesdays at 12pm EST (17:00 UTC); 1pm during EDT
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      # `uv run` uses the ruff pinned in uv.lock, so CI lints with the same version
+      # developers have locally. --output-format github annotates the PR diff inline.
+      # Paths come from [tool.ruff] in pyproject.toml rather than being repeated here.
+      - run: uv run ruff check --output-format github
+      - run: uv run ruff format --check
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run pytest -v -m "not integration"
+
+  integration-test:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group dev
+      - run: uv run pytest -v -m "integration and not slow"

.gitignore

@@ -1,3 +1,10 @@
+# Ignore data files.
+/data
+
+# Node dependencies, wherever they are installed (e.g. web/node_modules).
+# Deliberately not /web, so frontend source under it is still tracked.
+node_modules/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]
@@ -14,8 +21,9 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
+# Python distribution lib directories (not web/src/lib/)
+/lib/
+/lib64/
 parts/
 sdist/
 var/
@@ -135,7 +143,11 @@ celerybeat.pid
 *.sage.py
 
 # Environments
+# .env.* as well as .env: a .env.backup or .env.local holding the Translator-specific
+# releases URL is exactly what must never be committed, and a blanket `git add` would
+# take it. env.default does not match this pattern and stays tracked.
 .env
+.env.*
 .envrc
 .venv
 env/
@@ -173,7 +185,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
 # Abstra
 # Abstra is an AI-powered process automation framework.

.python-version

@@ -0,0 +1 @@
+3.11

CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to babel-explorer are documented here. This project follows
+[semantic versioning](https://semver.org/).
+
+## 0.1.0 — 2026-09-01
+
+First release. A Click CLI for querying Babel intermediate files through DuckDB, with optional
+label enrichment from NodeNorm.
+
+### Added
+
+- `xrefs` — cross-references for one or more CURIEs, with `--recurse` for transitive expansion
+  (a single `WITH RECURSIVE` DuckDB query), `--paths` for the shortest paths connecting the given
+  CURIEs, and `--labels` for NodeNorm labels and Biolink types.
+- `ids` — identifier records from `Identifiers.parquet`, with `--labels`.
+- `test-concord` — compare a proposed concordance change against NodeNorm's current cliques.
+- `--format json|tsv|csv` on `xrefs` and `ids` for machine-readable output.
+- `BabelDownloader`: streaming downloads with ETag-based freshness checking, resumable retries,
+  and a cache that holds one Babel release at a time and refreshes itself when that release
+  changes.
+- Configuration from `.env` or the environment — `BABEL_RELEASES_URL`, `BABEL_VERSION`,
+  `BABEL_LOCAL_DIR`, `BABEL_CHECK_DOWNLOAD`, `NODENORM_URL`, `BABEL_ALLOW_VERSION_MISMATCH` —
+  with `env.default` as the committed template. Precedence: flag > environment > `.env` > default.
+- A version-skew check that refuses to mix labels from one Babel release with cross-references
+  from another, overridable with `--allow-version-mismatch`.
+
+### Known limitations
+
+- **The shipped defaults cannot query data yet.** Public Babel releases do not publish
+  `duckdb/Concord.parquet` or `duckdb/Identifiers.parquet`. Translator team members can set
+  `BABEL_RELEASES_URL` to an internal releases URL; everyone else gets a clear error rather than
+  results. Tracked in [#16](https://github.com/TranslatorSRI/babel-explorer/issues/16).
+- **`--labels` fails against the public defaults.** NodeNorm dev reports Babel `2025sep1` while
+  public `latest` is `2025dec11`, so the skew check fires. Pin `BABEL_VERSION` to the release
+  NodeNorm was built from, or pass `--allow-version-mismatch`. Tracked in
+  [#17](https://github.com/TranslatorSRI/babel-explorer/issues/17).
+- The integration tests skip without a Babel release publishing the Parquet files, so a default
+  run exercises only the unit suite. Tracked in
+  [#18](https://github.com/TranslatorSRI/babel-explorer/issues/18).