geomend 0.0.1__tar.gz

geomend-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.13'
+      - run: uv sync --frozen --group dev --extra cohort --extra reconcile --extra ontology --extra server
+      - run: uv run ruff check
+      - run: uv run mypy
+      - run: uv run pytest --cov=geomend --cov-branch --cov-report=term-missing --cov-report=xml
+      - run: uv run geomend capabilities --json
+      - run: uv run python scripts/generate_discovery_artifacts.py
+      - run: git diff --exit-code -- docs/schemas
+      - run: uv build
+      - run: uv tool run --from dist/*.whl geomend version --json
+      - run: uv run --python 3.13 --isolated --no-project --with dist/*.whl python -c "from geomend.workspace_materialization import materialize; assert callable(materialize)"
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.13'
+      - run: uv sync --frozen --group docs
+      - run: uv run mkdocs build --strict

geomend-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Documentation
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.13'
+      - run: uv sync --frozen --group docs
+      - run: uv run mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

geomend-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release
+on:
+  push:
+    tags: ['v*']
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.13'
+      - run: test "$GITHUB_REF_NAME" = "v$(uv version --short)"
+      - run: uv sync --frozen --group dev --extra cohort --extra reconcile --extra ontology --extra server
+      - run: uv run ruff check
+      - run: uv run mypy
+      - run: uv run pytest --cov=geomend --cov-branch --cov-report=term-missing --cov-report=xml
+      - run: uv run python scripts/generate_discovery_artifacts.py
+      - run: uv build --no-sources
+      - run: uv run --python 3.13 --isolated --no-project --with "./dist/geomend-$(uv version --short)-py3-none-any.whl" python -c "from geomend.workspace_materialization import materialize; assert callable(materialize)"
+      - run: cp docs/schemas/*.json dist/
+      - run: cd dist && sha256sum * > SHA256SUMS
+      - uses: actions/attest-build-provenance@v2
+        if: ${{ !github.event.repository.private }}
+        with:
+          subject-path: 'dist/*'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/geomend
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist/
+      - run: uv publish dist/*.whl dist/*.tar.gz
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

geomend-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+.geomend/
+geomend-output/
+.venv/
+.pytest_cache/
+__pycache__/
+.coverage
+site/
+dist/
+build/
+*.egg-info/
+*.sqlite
+*.joblib
+*.npz
+.DS_Store

geomend-0.0.1/AGENTS.md

@@ -0,0 +1,23 @@
+# GEOmend repository discovery
+
+Use the same public workflow and decision semantics provided to every reviewer.
+The canonical instructions are in [`docs/reviewer-protocol.md`](docs/reviewer-protocol.md).
+
+Begin with:
+
+```bash
+command -v geomend
+# Installed release:
+geomend capabilities --json
+# Source-checkout fallback (run from the GEOmend repository root only):
+cd /path/to/geomend
+uv run --no-dev geomend capabilities --json
+```
+
+Outside the repository, install the release wheel or invoke the checkout's absolute
+`.venv/bin/geomend` executable. Do not assume `uv run` can discover GEOmend from a
+review-packet directory. Use the same working invocation for later commands.
+
+Never edit workspace SQLite files, review responses, or source metadata directly.
+Use `geomend reconcile plan` before creating a workspace and use the review CLI
+or authenticated API for every decision.

geomend-0.0.1/ARCHITECTURE.md

@@ -0,0 +1,182 @@
+# GEOmend architecture
+
+This document gives a new contributor the shortest complete mental model of the
+system. Statistical rationale and historical design research live in
+[`research-notes/BAYESIAN_MAPPING.md`](research-notes/BAYESIAN_MAPPING.md), while
+the public validation boundary is documented in
+[`docs/validation.md`](docs/validation.md).
+
+The stable product boundary is intentionally smaller than the research engine.
+Users enter through `geomend reconcile`, review through the flat workspace, and
+export only reviewed mappings. Experimental retrieval, ranking, calibration,
+and benchmark commands are isolated under `geomend dev`.
+
+## The decision pipeline
+
+```text
+pinned ontology/registry + dataset manifest
+                  |
+                  v
+        immutable column profiles
+                  |
+                  v
+      fielded lexical candidate union
+                  |
+                  v
+ deterministic evidence + reverse specificity
+                  |
+        +---------+----------+
+        |                    |
+        v                    v
+ lexical shadow    all eligible GEO fields -> local LLM
+        |                    |
+        +---------+----------+
+                  v
+       grouped fitted combiner
+                  |
+                  v
+ preference -> adequacy -> overflow/rescue
+                  |
+                  v
+      flat pending-review workspace
+```
+
+The LLM does not generate a target ID or a final confidence score. It compares
+already retrieved candidates using first-token probabilities. The grouped
+combiner measures whether that semantic residual helps after deterministic
+evidence is already known.
+
+## Two mapping domains
+
+### Registry/CDE mapping
+
+The selectable answer is a registry record such as a caDSR CDE. Ontology nodes
+and NCIt concepts provide semantic anchors and graph context; they are not
+automatically interchangeable with selectable CDEs. DREAM, the synthetic GDC
+regression corpus, and GDC-SM use this path.
+
+### Direct ontology-term mapping
+
+GEO profiles can be mapped against a pinned local ontology whose eligible graph
+nodes are projected into selectable targets. This path has a separate response
+contract because a GEO field-to-term suggestion is not a caDSR CDE assignment.
+
+## Stages and ownership
+
+### 1. Ingestion
+
+`ontology.py` parses graph nodes, typed edges, synonyms, definitions,
+deprecations, replacements, and selectable targets into SQLite. Adapters in
+`dream.py`, `gdc_sm.py`, and `geo_mapping.py` translate source-specific formats.
+Sparse retrieval matrices are stored separately and tied to the ontology hash.
+
+### 2. Profiling
+
+`profile.py` preserves raw names and values while producing normalized retrieval
+views, datatypes, missingness classes, categorical distributions, numeric shape,
+units, and table context. `neighborhood.py` creates compact aggregate
+relationships and semantic neighbors. GEO metadata are public; aggregation is
+used to control prompt noise and size, not to imply confidentiality. Physical
+adjacency is weak fallback evidence, not the definition of relevance.
+
+### 3. Retrieval
+
+`retrieval.py` runs independent header, semantic-facet, acronym, value-domain,
+and low-weight table-context channels. It preserves the top candidates from each
+channel, fuses the remainder deterministically, records the uncapped union, and
+caps the selectable prompt pool. Retrieval recall is evaluated independently of
+ranking.
+
+### 4. Deterministic and reverse evidence
+
+`bayesian.py` and `ranking.py` compute header, value, datatype, unit/range,
+semantic-slot, and contradiction evidence. Each candidate also asks the reverse
+question: if this candidate were correct, is the focal field its best realization
+in the table, or does a semantically comparable column fit better?
+
+### 5. LLM evidence
+
+`prompts.py` builds the versioned generic ontology-mapping prompt contract;
+`geo_inference.py` builds the GEO-specific contract. Both use symmetric,
+equal-budget candidate evidence, permit repeated legitimate mappings, hide
+target IDs, and ask whether observations are better explained by Candidate A or
+Candidate B. GEO inference routes every pairwise-eligible field when enabled;
+verified source bindings remain protected and every result retains its lexical
+shadow. `ollama_client.py` calls only a loopback native Ollama endpoint and
+extracts token log probabilities.
+
+Reciprocal scoring produces one semantic evidence term and an inconsistency
+measure. Missing valid-token mass, unstable reruns, excessive inconsistency, or
+an unavailable model makes the comparison unscorable.
+
+### 6. Grouped combiner
+
+`combiner.py` fits two otherwise identical no-intercept L2 logistic models on
+whole-study folds: deterministic/reverse evidence only, and the same vector plus
+the reciprocal LLM logit. Fold-local imputation, scaling, model selection, and
+out-of-fold calibration prevent information leakage. The augmented model is
+usable only when the LLM coefficient is stable and improves held-out fit and
+ranking.
+
+### 7. Runtime decisions
+
+Candidate preference is aggregated over pairwise comparisons. Adequacy compares
+the tentative winner with an explicit `NOMATCH`. Shortlist sufficiency decides
+whether to examine deterministic overflow and then one-hop graph rescue. These
+heads are not derived from a candidate softmax because one candidate always wins
+a closed-set softmax.
+
+Any unsafe condition restores the original lexical result. A conservative
+table-level second pass may update ambiguous columns once using high-confidence
+anchors; it cannot propagate indefinitely.
+
+An exact source/candidate name is never schema authority. Only a verified,
+pinned source-to-standard binding can protect a mapping from residual reranking.
+Literal disagreement between linked records is recorded for review and becomes
+a negative semantic feature only when normalization establishes incompatible
+propositions.
+
+### 8. Artifacts and review
+
+`storage.py` writes versioned JSONL and model manifests atomically. The public
+review boundary is the flat workspace in `workspace.py`: candidate rankings are
+stored once, opinion sets and reviews are append-only, and snapshots select a
+coherent perspective without copying evidence. `workspace_api.py` provides the
+authenticated loopback API. A run records profiles, candidates, relations,
+probabilities, pairwise features, combiner decisions, suggestions, value
+mappings, and lexical shadows.
+
+Multi-target gold and review assignments are supported. Automatic semantic
+relations such as `co_required` remain disabled until relation-labelled evidence
+is sufficiently powered.
+
+## Releases and benchmarks
+
+`release.py` seals immutable engine bundles and maintains an atomic active
+pointer. A run pins the active release when it is created. `campaign.py` evaluates
+frozen contenders and may activate a hybrid only after every promotion gate
+passes; rollback changes the pointer, never historical artifacts.
+
+Benchmark roles are deliberately different:
+
+- GDC-SM: primary public development and comparison benchmark;
+- independent GEO cohorts: real-data development and prediction-blind
+  promotion evidence maintained outside this product repository;
+- synthetic GDC schema: regression and controlled-ablation asset only;
+- DREAM: independent challenge evaluation when authorized files are available.
+
+Public or previously inspected gold cannot become locked promotion evidence.
+
+## Deliberately unsupported in this release
+
+- remote inference;
+- automatic application of mappings to source tables;
+- recursive graph traversal;
+- raw-row prompt context;
+- a production-default embedding or cross-encoder retriever (local dense
+  retrieval remains an explicitly enabled development channel);
+- global joint table optimization;
+- automatic `co_required` emission.
+
+Additions in these areas require a separate evidence and privacy review rather
+than being slipped into an existing configuration.

geomend-0.0.1/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use GEOmend, cite this software release."
+title: "GEOmend"
+type: software
+version: 0.2.0
+date-released: 2026-09-25
+authors:
+  - family-names: Raab
+    given-names: Preston
+repository-code: "https://github.com/prestonraab/geomend"
+url: "https://prestonraab.github.io/geomend/"
+license: MIT

geomend-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,133 @@
+# Contributing to GEOmend
+
+This guide assumes you have not worked on GEOmend before. The system is designed
+for scientific auditability, so a behavior change is incomplete until its
+evidence contract, test, and documentation agree.
+
+## Development setup
+
+From the `geomend/` directory:
+
+```bash
+uv sync --group dev --extra reconcile --extra ontology --extra server
+uv run ruff check
+uv run mypy
+uv run pytest
+uv run geomend --help
+```
+
+Python 3.13 is required. The ordinary test suite uses mocked model responses and
+does not require network access or Ollama. Run local-model smoke tests only when
+you intentionally have a compatible Ollama server and model.
+
+## Non-negotiable invariants
+
+- Every mapping is a suggestion marked `pending_review`.
+- Model inference is local and loopback-only. Papers and metadata must never be
+  sent to a remote inference endpoint.
+- The lexical decision is retained as a shadow result for every hybrid decision.
+- Missing, malformed, inconsistent, or digest-mismatched model evidence falls
+  back to lexical behavior.
+- LLM token probabilities are evidence, not self-reported confidence and not a
+  calibrated posterior by themselves.
+- Candidate preference, adequacy versus `NOMATCH`, and shortlist sufficiency are
+  separate statistical questions.
+- Raw aligned row tuples never enter prompts. Public GEO values may be retained
+  in evidence artifacts and summarized in prompt cards when relevant;
+  aggregation is for signal quality and token efficiency, not confidentiality.
+- Registry IDs are hidden from model-visible prompts.
+- Explicit qualifier and unit contradictions are hard vetoes.
+- Evaluation splits are by complete study/table. Do not leak schema-local names,
+  target aliases, review labels, or public gold across folds.
+- Serialized artifacts are immutable and hash-linked. Extend Pydantic contracts
+  with safe defaults so older JSONL remains readable.
+
+## Where a change belongs
+
+| Change | Primary locations |
+|---|---|
+| Data contracts | `src/geomend/models.py` and contract tests |
+| Dataset profiling | `profile.py`, `neighborhood.py`, and profile tests |
+| Ontology/registry ingestion | `ontology.py`, `dream.py`, `gdc_sm.py`, or `geo_mapping.py` |
+| Retrieval channel or fusion | `retrieval.py`, configuration, retrieval tests |
+| Prompt/context engineering | `prompts.py`, prompt snapshots and symmetry tests |
+| Ollama protocol | `ollama_client.py`, `model_qualification.py`, mocked contract tests |
+| Fitted residual evidence | `combiner.py`, CLI configuration, grouped-fold tests |
+| Runtime decision/fallback | `pipeline.py`, `ranking.py`, end-to-end tests |
+| Review and adjudication | `review.py`, review round-trip tests |
+| Promotion/release behavior | `campaign.py`, `release.py`, monitor and gate tests |
+| Workspace contracts and persistence | `workspace_models.py`, `workspace_db.py`, `workspace_schema.py` |
+| Workspace review services | focused `workspace_*.py` modules; keep `workspace.py` as a compatibility facade |
+
+## Workspace maintainability gates
+
+Workspace changes must pass three independent checks before the behavior tests:
+
+```bash
+uv run ruff check
+uv run mypy
+uv run pytest tests/test_workspace_architecture.py tests/test_workspace_quality_gates.py
+```
+
+Ruff and strict mypy cover every `workspace*.py` module listed by the glob in
+`pyproject.toml`. The architecture tests cover every extracted workspace
+service. They reject HTTP dependencies in the domain, persistence modules that
+reach upward into services, dependency cycles, and functions over 150 lines or
+complexity 50. Add new workspace modules under the same prefix so they enter
+these gates automatically.
+
+## Changing prompts safely
+
+1. Bump the prompt-template version.
+2. Keep candidate-independent bytes invariant across reciprocal orders.
+3. Give candidates equal budgets and hide real target IDs.
+4. Keep data quoted as untrusted evidence, never as instructions.
+5. Add or update snapshot, ID-hiding, and reciprocal-symmetry tests.
+6. Treat prior model qualification and calibration as incompatible unless the
+   versioned contract proves otherwise.
+7. Document experimental rationale in
+   `research-notes/PROMPT_ENGINEERING.md` and any stable behavior change in the
+   public documentation.
+
+## Changing retrieval safely
+
+Retrieval determines candidate membership and must remain distinguishable from
+LLM reranking gains. Store the full union as well as the capped pool, use stable
+target-ID tie breaking, and report recall before ranking accuracy. Never add a
+held-out source property's name as a target alias.
+
+When comparing an LLM contender with the baseline, freeze candidate membership,
+order, registry release, and retrieval configuration. Otherwise the experiment
+cannot attribute gains to model evidence.
+
+## Working with data and models
+
+The local `data/` directory is ignored. Put downloaded GDC-SM, DREAM, and GEO
+source material there. Do not redistribute controlled DREAM files,
+publisher supplements, model weights, or human review packets unless their terms
+explicitly permit it.
+
+Run workspaces (`.geomend*`), `artifacts/`, `*.sqlite`, `*.joblib`, and `*.npz`
+are ignored. Checked-in configuration must use relative paths and must pin source
+versions and hashes where the workflow supports them.
+
+## Before handing off a change
+
+Run the narrow tests while developing, then the full suite:
+
+```bash
+uv run pytest tests/test_relevant_module.py
+uv run ruff check
+uv run mypy
+uv run pytest
+git diff --check
+```
+
+In the handoff, report:
+
+- the behavior and contract that changed;
+- the tests and benchmark slices that ran;
+- whether Ollama, network access, or non-public data was required;
+- whether the public v0.2 contracts changed and whether regeneration is
+  required (pre-v0.2 workspaces are rejected rather than migrated);
+- whether the change is production-default, canary-only, or experimental.

geomend-0.0.1/LICENSE

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