groundstore 0.1.0__tar.gz

groundstore-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What does this PR do? This text becomes the changelog entry. Leave blank for chore PRs. -->
+
+## Checklist
+
+- [ ] Applied exactly one label (`breaking`, `feature`, `fix`, `dependencies`, or `chore`)
+- [ ] Tests pass locally (`uv run pytest -q`)
+- [ ] Type checking passes (`uv run ty check src/`)
+- [ ] Lint passes (`uv run ruff check .`)

groundstore-0.1.0/.github/release-drafter.yml

@@ -0,0 +1,31 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+commitish: main
+
+categories:
+  - title: Breaking Changes
+    labels: ['breaking']
+  - title: Features
+    labels: ['feature']
+  - title: Fixes
+    labels: ['fix']
+  - title: Dependencies
+    labels: ['dependencies']
+
+template: |
+  $CHANGES
+
+change-template: '- **$TITLE** (#$NUMBER) @$AUTHOR'
+
+version-resolver:
+  major:
+    labels: ['breaking']
+  minor:
+    labels: ['feature']
+  patch:
+    labels: ['fix', 'dependencies']
+  default: patch
+
+exclude-labels: ['chore']
+
+autolabeler: []

groundstore-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+jobs:
+  label-gate:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/label-gate.yml@main
+
+  build-test:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test.yml@main

groundstore-0.1.0/.github/workflows/merge.yml

@@ -0,0 +1,12 @@
+name: Release Update
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  draft:
+    if: github.event.pull_request.merged == true
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/release-drafter.yml@main
+    secrets: inherit

groundstore-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/publish.yml@main
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/groundstore
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

groundstore-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python bytecode and local tooling
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.tox/
+.nox/
+.hypothesis/
+
+# Build and distribution artefacts
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+.coverage
+.coverage.*
+htmlcov/
+
+# Local configuration and credentials
+.env
+.env.*
+!.env.example
+*.local.toml
+*.local.yaml
+
+# Local databases and generated application data
+*.db
+*.db-*
+data/
+site/
+_design/
+
+# Editors and operating-system files
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo

groundstore-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+## Development setup
+
+```bash
+uv sync --all-extras --dev
+uv run ty check src/
+uv run ruff check .
+uv run pytest -q
+```
+
+Pull requests should carry exactly one of the repository labels:
+`breaking`, `feature`, `fix`, `dependencies`, or `chore`. Public API changes
+are breaking changes; compatible functionality is a feature; CI, refactoring,
+tests, and documentation are chore changes.
+
+Package versions are derived from Git tags. Releases are published from a
+maintainer-approved `vX.Y.Z` tag through the repository's PyPI environment.

groundstore-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: groundstore
+Version: 0.1.0
+Summary: Shared mapping-task contracts for Groundworkers workflows.
+Requires-Python: >=3.12
+Requires-Dist: oa-configurator<2,>=1.3.0
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: sqlalchemy<3,>=2.0.45
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.4; extra == 'dev'
+Requires-Dist: ty>=0.0.59; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'postgres'

groundstore-0.1.0/README.md

@@ -0,0 +1,34 @@
+# groundstore
+
+Shared mapping-task contracts and persistence for Groundworkers-adjacent
+mapping workflows.
+
+## Current status
+
+The package provides source-independent Pydantic contracts, SQLAlchemy models,
+and a resumable `MappingStore` for runs, inputs, candidates, separate evidence
+records, versioned decisions, decision history, provenance, and lifecycle
+state. It can use an explicit SQLAlchemy URL for tests or resolve a named
+database resource through `oa-configurator` for consuming packages.
+
+`MappingReadContext` exposes common read-only status, coverage, evidence-packet,
+and review-handoff operations. Packets are JSON-safe and carry the full run,
+input, candidate, evidence, and decision-history lineage, so Groundworkers or a
+standalone reviewer can consume the same handoff without importing SQLAlchemy
+models.
+
+Representative contract fixtures under `tests/fixtures/` cover one-to-one,
+one-to-many, ambiguous, redirected/incomplete, unmappable, and retryable
+failure outcomes.
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run ty check src/
+uv run ruff check .
+uv run pytest -q
+```
+
+The package version is derived from a `vX.Y.Z` or `X.Y.Z` Git tag, with a
+`0.1.0` fallback when Git metadata is unavailable.

groundstore-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "groundstore"
+dynamic = ["version"]
+description = "Shared mapping-task contracts for Groundworkers workflows."
+requires-python = ">=3.12"
+dependencies = [
+    "oa-configurator>=1.3.0,<2",
+    "pydantic>=2,<3",
+    "sqlalchemy>=2.0.45,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<9",
+    "ruff>=0.4,<1",
+    "ty>=0.0.59",
+]
+
+postgres = [
+    "psycopg[binary]>=3.1,<4",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.1.0"
+raw-options = { tag_regex = '^v?(?P<version>[0-9]+\.[0-9]+\.[0-9]+)$' }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/groundstore"]
+
+[tool.uv]
+cache-keys = [
+    { file = "pyproject.toml" },
+    { git = { commit = true, tags = true } },
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

groundstore-0.1.0/src/groundstore/__init__.py

@@ -0,0 +1,30 @@
+"""Shared mapping-task contracts and persistence for Groundworkers workflows."""
+
+from .context import MappingEvidencePacket, MappingReadContext, MappingReviewHandoff
+from .contracts import (
+    DecisionStatus,
+    LifecycleStatus,
+    MappingCandidateSpec,
+    MappingDecisionSpec,
+    MappingEvidenceSpec,
+    MappingInputSpec,
+    MappingRunSpec,
+)
+from .engine import create_groundstore_engine, create_schema
+from .store import MappingStore
+
+__all__ = [
+    "DecisionStatus",
+    "LifecycleStatus",
+    "MappingCandidateSpec",
+    "MappingDecisionSpec",
+    "MappingEvidencePacket",
+    "MappingEvidenceSpec",
+    "MappingInputSpec",
+    "MappingReadContext",
+    "MappingReviewHandoff",
+    "MappingRunSpec",
+    "MappingStore",
+    "create_groundstore_engine",
+    "create_schema",
+]

groundstore-0.1.0/src/groundstore/context.py

@@ -0,0 +1,245 @@
+"""Read-only views over persisted mapping work.
+
+The persistence API remains useful to standalone writers.  This module adds
+the small, transport-neutral packet that a host or review client can consume
+without depending on SQLAlchemy model instances or lazy relationships.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .models import (
+    MappingCandidate,
+    MappingDecision,
+    MappingDecisionEvent,
+    MappingEvidence,
+    MappingInput,
+    MappingRun,
+)
+from .store import MappingStore
+
+
+class MappingEvidencePacket(BaseModel):
+    """Stable JSON contract for reviewing one persisted mapping input."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: str = "groundstore.mapping-evidence-packet.v1"
+    run: dict[str, Any]
+    input: dict[str, Any]
+    candidates: list[dict[str, Any]] = Field(default_factory=list)
+    evidence: list[dict[str, Any]] = Field(default_factory=list)
+    decision: dict[str, Any] | None = None
+    warnings: list[str] = Field(default_factory=list)
+
+
+class MappingReviewHandoff(BaseModel):
+    """Review-task reference carrying a self-contained evidence packet."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: str = "groundstore.mapping-review-handoff.v1"
+    task_id: str = Field(min_length=1)
+    task_type: str = "mapping_review"
+    source_namespace: str = Field(min_length=1)
+    input_id: str = Field(min_length=1)
+    decision_status: str = "needs_review"
+    packet: MappingEvidencePacket
+    requested_by: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class MappingReadContext:
+    """Read-only Groundstore façade for host tools and review consumers."""
+
+    store: MappingStore
+
+    def status(
+        self,
+        source_namespace: str,
+        *,
+        target_system: str | None = None,
+    ) -> dict[str, Any]:
+        """Return the latest complete run and its common coverage summary."""
+
+        run = self.store.latest_successful_run(source_namespace, target_system=target_system)
+        if run is None:
+            return {
+                "source_namespace": source_namespace,
+                "target_system": target_system,
+                "latest_run": None,
+                "coverage": None,
+            }
+        return {
+            "source_namespace": source_namespace,
+            "target_system": target_system,
+            "latest_run": _run_payload(run),
+            "coverage": self.store.coverage(run.id),
+        }
+
+    def evidence_packet(self, input_id: str) -> MappingEvidencePacket:
+        """Build a detached packet with candidates, evidence, and decision history."""
+
+        input_record = self.store.get_input(input_id)
+        if input_record is None:
+            raise KeyError(f"unknown mapping input: {input_id}")
+        run = self.store.get_run(input_record.run_id)
+        if run is None:  # pragma: no cover - protected by the database FK
+            raise KeyError(f"unknown mapping run: {input_record.run_id}")
+
+        candidates = self.store.get_candidates(input_id)
+        evidence = self.store.get_evidence(input_id)
+        decision = self.store.latest_decision(input_id)
+        selected_ids = (
+            self.store.get_decision_candidate_ids(decision.id) if decision is not None else []
+        )
+        events = self.store.get_decision_history(decision.id) if decision is not None else []
+        evidence_by_candidate: dict[str, list[dict[str, Any]]] = {}
+        unattached: list[dict[str, Any]] = []
+        for item in evidence:
+            payload = _evidence_payload(item)
+            if item.candidate_id is None:
+                unattached.append(payload)
+            else:
+                evidence_by_candidate.setdefault(item.candidate_id, []).append(payload)
+
+        candidate_payloads = []
+        for candidate in candidates:
+            payload = _candidate_payload(candidate)
+            payload["evidence"] = evidence_by_candidate.get(candidate.id, [])
+            candidate_payloads.append(payload)
+
+        decision_payload = None
+        if decision is not None:
+            decision_payload = _decision_payload(decision)
+            decision_payload["selected_candidate_ids"] = selected_ids
+            decision_payload["history"] = [_event_payload(event) for event in events]
+
+        return MappingEvidencePacket(
+            run=_run_payload(run),
+            input=_input_payload(input_record),
+            candidates=candidate_payloads,
+            evidence=unattached,
+            decision=decision_payload,
+        )
+
+    def review_handoff(
+        self,
+        input_id: str,
+        *,
+        requested_by: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> MappingReviewHandoff:
+        """Return a deterministic review reference without mutating the store."""
+
+        packet = self.evidence_packet(input_id)
+        decision_status = (
+            packet.decision.get("decision_status", "needs_review")
+            if packet.decision
+            else "needs_review"
+        )
+        return MappingReviewHandoff(
+            task_id=f"mapping-review:{input_id}",
+            source_namespace=packet.input["source_namespace"],
+            input_id=input_id,
+            decision_status=str(decision_status),
+            packet=packet,
+            requested_by=requested_by,
+            metadata=metadata or {},
+        )
+
+
+def _run_payload(run: MappingRun) -> dict[str, Any]:
+    return {
+        "id": run.id,
+        "source_namespace": run.source_namespace,
+        "source_fingerprint": run.source_fingerprint,
+        "source_snapshot": run.source_snapshot,
+        "target_system": run.target_system,
+        "target_release": run.target_release,
+        "algorithm_version": run.algorithm_version,
+        "policy_version": run.policy_version,
+        "lifecycle_status": run.lifecycle_status,
+        "last_error": run.last_error,
+        "created_at": run.created_at.isoformat(),
+        "updated_at": run.updated_at.isoformat(),
+    }
+
+
+def _input_payload(input_record: MappingInput) -> dict[str, Any]:
+    return {
+        "id": input_record.id,
+        "run_id": input_record.run_id,
+        "source_namespace": input_record.source_namespace,
+        "source_kind": input_record.source_kind,
+        "source_key": input_record.source_key,
+        "source_fingerprint": input_record.source_fingerprint,
+        "normalized_projection": input_record.normalized_projection,
+        "lifecycle_status": input_record.lifecycle_status,
+        "retry_count": input_record.retry_count,
+        "last_error": input_record.last_error,
+        "created_at": input_record.created_at.isoformat(),
+        "updated_at": input_record.updated_at.isoformat(),
+    }
+
+
+def _candidate_payload(candidate: MappingCandidate) -> dict[str, Any]:
+    return {
+        "id": candidate.id,
+        "target_namespace": candidate.target_namespace,
+        "target_vocabulary_id": candidate.target_vocabulary_id,
+        "target_concept_id": candidate.target_concept_id,
+        "target_code": candidate.target_code,
+        "target_grain": candidate.target_grain,
+        "target_role": candidate.target_role,
+        "method": candidate.method,
+        "rank": candidate.rank,
+        "score": candidate.score,
+        "confidence": candidate.confidence,
+        "rationale": candidate.rationale,
+        "metadata": candidate.metadata_,
+        "created_at": candidate.created_at.isoformat(),
+    }
+
+
+def _evidence_payload(evidence: MappingEvidence) -> dict[str, Any]:
+    return {
+        "id": evidence.id,
+        "candidate_id": evidence.candidate_id,
+        "decision_id": evidence.decision_id,
+        "evidence_key": evidence.evidence_key,
+        "evidence_type": evidence.evidence_type,
+        "source_reference": evidence.source_reference,
+        "method": evidence.method,
+        "payload": evidence.payload,
+        "created_at": evidence.created_at.isoformat(),
+    }
+
+
+def _decision_payload(decision: MappingDecision) -> dict[str, Any]:
+    return {
+        "id": decision.id,
+        "input_id": decision.input_id,
+        "decision_version": decision.decision_version,
+        "decision_status": decision.decision_status,
+        "outcome_code": decision.outcome_code,
+        "reason_codes": decision.reason_codes,
+        "decided_by": decision.decided_by,
+        "metadata": decision.metadata_,
+        "decided_at": decision.decided_at.isoformat(),
+    }
+
+
+def _event_payload(event: MappingDecisionEvent) -> dict[str, Any]:
+    return {
+        "id": event.id,
+        "decision_id": event.decision_id,
+        "event_type": event.event_type,
+        "detail": event.detail,
+        "created_at": event.created_at.isoformat(),
+    }

groundstore-0.1.0/src/groundstore/contracts.py

@@ -0,0 +1,108 @@
+"""Source-independent contracts for mapping workflows."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class LifecycleStatus(StrEnum):
+    """Processing state for a run or input."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETE = "complete"
+    INCOMPLETE = "incomplete"
+    FAILED = "failed"
+
+
+class DecisionStatus(StrEnum):
+    """Mapping outcome independent of the processing lifecycle."""
+
+    MAPPED = "mapped"
+    AMBIGUOUS = "ambiguous"
+    UNMAPPABLE = "unmappable"
+    NEEDS_REVIEW = "needs_review"
+
+
+class MappingRunSpec(BaseModel):
+    """Stable identity and metadata for one mapping run."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    source_namespace: str = Field(min_length=1)
+    source_fingerprint: str = Field(min_length=1, max_length=128)
+    source_snapshot: dict[str, Any] = Field(default_factory=dict)
+    target_system: str = Field(min_length=1)
+    target_release: str | None = None
+    algorithm_version: str = Field(min_length=1)
+    policy_version: str = Field(min_length=1)
+    lifecycle_status: LifecycleStatus = LifecycleStatus.PENDING
+
+
+class MappingInputSpec(BaseModel):
+    """Source item presented to a mapping workflow."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    source_namespace: str = Field(min_length=1)
+    source_kind: str = Field(min_length=1)
+    source_key: str = Field(min_length=1)
+    source_fingerprint: str = Field(min_length=1, max_length=128)
+    normalized_projection: dict[str, Any] = Field(default_factory=dict)
+    lifecycle_status: LifecycleStatus = LifecycleStatus.PENDING
+    retry_count: int = Field(default=0, ge=0)
+    last_error: str | None = None
+
+
+class MappingCandidateSpec(BaseModel):
+    """One candidate target for a mapping input."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    target_namespace: str = Field(min_length=1)
+    target_vocabulary_id: str | None = None
+    target_concept_id: str | None = None
+    target_code: str | None = None
+    target_grain: str | None = None
+    target_role: str | None = None
+    method: str = Field(min_length=1)
+    rank: int = Field(default=1, ge=1)
+    score: float | None = None
+    confidence: float | None = Field(default=None, ge=0, le=1)
+    rationale: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("target_vocabulary_id", "target_concept_id", "target_code")
+    @classmethod
+    def reject_blank_identifiers(cls, value: str | None) -> str | None:
+        if value is not None and not value.strip():
+            raise ValueError("target identifiers cannot be blank")
+        return value
+
+
+class MappingEvidenceSpec(BaseModel):
+    """Evidence attached to a candidate or decision."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    evidence_key: str = Field(min_length=1, max_length=128)
+    evidence_type: str = Field(min_length=1)
+    source_reference: str | None = None
+    method: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class MappingDecisionSpec(BaseModel):
+    """Versioned decision for one mapping input."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    decision_status: DecisionStatus
+    selected_candidate_ids: list[str] = Field(default_factory=list)
+    outcome_code: str | None = None
+    reason_codes: list[str] = Field(default_factory=list)
+    decided_by: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)