groundstore 0.1.0__py3-none-any.whl

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/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/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)

groundstore/engine.py

@@ -0,0 +1,64 @@
+"""Engine and schema helpers, including oa-configurator resolution."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import sqlalchemy as sa
+from oa_configurator import ResolvedDatabase, Resolver
+from sqlalchemy import Engine, event
+from sqlalchemy.engine import URL
+
+from .models import Base
+
+
+def create_groundstore_engine(
+    url: str | URL | None = None,
+    *,
+    resolved_database: ResolvedDatabase | None = None,
+    resolver: Resolver | None = None,
+    database_name: str = "mapping_db",
+    execution_options: Mapping[str, Any] | None = None,
+    **engine_kwargs: Any,
+) -> Engine:
+    """Create a store engine from an explicit URL or OA database resource."""
+    if sum(value is not None for value in (url, resolved_database, resolver)) > 1:
+        raise ValueError("provide only one of url, resolved_database, or resolver")
+
+    if resolved_database is not None:
+        engine = resolved_database.create_engine(**engine_kwargs)
+    elif resolver is not None:
+        engine = resolver.resolve_database(database_name).create_engine(**engine_kwargs)
+    elif url is not None:
+        engine = sa.create_engine(url, **engine_kwargs)
+    else:
+        engine = (
+            Resolver.from_active_config()
+            .resolve_database(database_name)
+            .create_engine(**engine_kwargs)
+        )
+
+    if execution_options:
+        engine = engine.execution_options(**dict(execution_options))
+    if engine.dialect.name == "sqlite":
+        _enable_sqlite_foreign_keys(engine)
+    return engine
+
+
+def create_schema(engine: Engine) -> None:
+    """Create all groundstore tables if they do not already exist."""
+    Base.metadata.create_all(engine)
+
+
+def drop_schema(engine: Engine) -> None:
+    """Drop all groundstore tables; intended for isolated test databases."""
+    Base.metadata.drop_all(engine)
+
+
+def _enable_sqlite_foreign_keys(engine: Engine) -> None:
+    @event.listens_for(engine, "connect")
+    def _set_foreign_keys(dbapi_connection: Any, _connection_record: Any) -> None:
+        cursor = dbapi_connection.cursor()
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.close()

groundstore/models.py

@@ -0,0 +1,219 @@
+"""SQLAlchemy persistence models for the shared mapping contract."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import (
+    JSON,
+    DateTime,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+
+class Base(DeclarativeBase):
+    """Declarative base for groundstore tables."""
+
+
+class MappingRun(Base):
+    __tablename__ = "mapping_runs"
+    __table_args__ = (
+        UniqueConstraint(
+            "source_namespace",
+            "source_fingerprint",
+            "target_system",
+            "target_release",
+            "algorithm_version",
+            "policy_version",
+            name="uq_mapping_run_identity",
+        ),
+        Index("ix_mapping_runs_source_status", "source_namespace", "lifecycle_status"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    source_namespace: Mapped[str] = mapped_column(String(100), nullable=False)
+    source_fingerprint: Mapped[str] = mapped_column(String(128), nullable=False)
+    source_snapshot: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    target_system: Mapped[str] = mapped_column(String(100), nullable=False)
+    target_release: Mapped[str | None] = mapped_column(String(100))
+    algorithm_version: Mapped[str] = mapped_column(String(100), nullable=False)
+    policy_version: Mapped[str] = mapped_column(String(100), nullable=False)
+    lifecycle_status: Mapped[str] = mapped_column(String(20), nullable=False)
+    last_error: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+    inputs: Mapped[list[MappingInput]] = relationship(
+        back_populates="run", cascade="all, delete-orphan"
+    )
+
+
+class MappingInput(Base):
+    __tablename__ = "mapping_inputs"
+    __table_args__ = (
+        UniqueConstraint(
+            "run_id",
+            "source_namespace",
+            "source_kind",
+            "source_key",
+            "source_fingerprint",
+            name="uq_mapping_input_identity",
+        ),
+        Index("ix_mapping_inputs_run_status", "run_id", "lifecycle_status"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    run_id: Mapped[str] = mapped_column(
+        ForeignKey("mapping_runs.id", ondelete="CASCADE"), nullable=False
+    )
+    source_namespace: Mapped[str] = mapped_column(String(100), nullable=False)
+    source_kind: Mapped[str] = mapped_column(String(100), nullable=False)
+    source_key: Mapped[str] = mapped_column(String(255), nullable=False)
+    source_fingerprint: Mapped[str] = mapped_column(String(128), nullable=False)
+    normalized_projection: Mapped[dict[str, Any]] = mapped_column(
+        JSON, nullable=False, default=dict
+    )
+    lifecycle_status: Mapped[str] = mapped_column(String(20), nullable=False)
+    retry_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    last_error: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+    run: Mapped[MappingRun] = relationship(back_populates="inputs")
+    candidates: Mapped[list[MappingCandidate]] = relationship(
+        back_populates="input", cascade="all, delete-orphan"
+    )
+    evidence: Mapped[list[MappingEvidence]] = relationship(
+        back_populates="input", cascade="all, delete-orphan"
+    )
+    decisions: Mapped[list[MappingDecision]] = relationship(
+        back_populates="input", cascade="all, delete-orphan"
+    )
+
+
+class MappingCandidate(Base):
+    __tablename__ = "mapping_candidates"
+    __table_args__ = (
+        UniqueConstraint("input_id", "candidate_key", name="uq_mapping_candidate_key"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    input_id: Mapped[str] = mapped_column(
+        ForeignKey("mapping_inputs.id", ondelete="CASCADE"), nullable=False
+    )
+    candidate_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    target_namespace: Mapped[str] = mapped_column(String(100), nullable=False)
+    target_vocabulary_id: Mapped[str | None] = mapped_column(String(100))
+    target_concept_id: Mapped[str | None] = mapped_column(String(100))
+    target_code: Mapped[str | None] = mapped_column(String(255))
+    target_grain: Mapped[str | None] = mapped_column(String(100))
+    target_role: Mapped[str | None] = mapped_column(String(100))
+    method: Mapped[str] = mapped_column(String(100), nullable=False)
+    rank: Mapped[int] = mapped_column(Integer, nullable=False)
+    score: Mapped[float | None] = mapped_column(Float)
+    confidence: Mapped[float | None] = mapped_column(Float)
+    rationale: Mapped[str | None] = mapped_column(Text)
+    metadata_: Mapped[dict[str, Any]] = mapped_column(
+        "metadata", JSON, nullable=False, default=dict
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+    input: Mapped[MappingInput] = relationship(back_populates="candidates")
+    evidence: Mapped[list[MappingEvidence]] = relationship(back_populates="candidate")
+    decisions: Mapped[list[MappingDecision]] = relationship(
+        secondary="mapping_decision_candidates", back_populates="selected_candidates"
+    )
+
+
+class MappingEvidence(Base):
+    __tablename__ = "mapping_evidence"
+    __table_args__ = (
+        UniqueConstraint("input_id", "evidence_key", name="uq_mapping_evidence_key"),
+        Index("ix_mapping_evidence_candidate", "candidate_id"),
+        Index("ix_mapping_evidence_decision", "decision_id"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    input_id: Mapped[str] = mapped_column(
+        ForeignKey("mapping_inputs.id", ondelete="CASCADE"), nullable=False
+    )
+    candidate_id: Mapped[str | None] = mapped_column(
+        ForeignKey("mapping_candidates.id", ondelete="CASCADE")
+    )
+    decision_id: Mapped[str | None] = mapped_column(
+        ForeignKey("mapping_decisions.id", ondelete="CASCADE")
+    )
+    evidence_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    evidence_type: Mapped[str] = mapped_column(String(100), nullable=False)
+    source_reference: Mapped[str | None] = mapped_column(Text)
+    method: Mapped[str | None] = mapped_column(String(100))
+    payload: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+    input: Mapped[MappingInput] = relationship(back_populates="evidence")
+    candidate: Mapped[MappingCandidate | None] = relationship(back_populates="evidence")
+    decision: Mapped[MappingDecision | None] = relationship(back_populates="evidence")
+
+
+class MappingDecision(Base):
+    __tablename__ = "mapping_decisions"
+    __table_args__ = (
+        UniqueConstraint("input_id", "decision_version", name="uq_mapping_decision_version"),
+    )
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    input_id: Mapped[str] = mapped_column(
+        ForeignKey("mapping_inputs.id", ondelete="CASCADE"), nullable=False
+    )
+    decision_version: Mapped[int] = mapped_column(Integer, nullable=False)
+    decision_status: Mapped[str] = mapped_column(String(20), nullable=False)
+    outcome_code: Mapped[str | None] = mapped_column(String(150))
+    reason_codes: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    decided_by: Mapped[str | None] = mapped_column(String(255))
+    metadata_: Mapped[dict[str, Any]] = mapped_column(
+        "metadata", JSON, nullable=False, default=dict
+    )
+    decided_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+    input: Mapped[MappingInput] = relationship(back_populates="decisions")
+    selected_candidates: Mapped[list[MappingCandidate]] = relationship(
+        secondary="mapping_decision_candidates", back_populates="decisions"
+    )
+    evidence: Mapped[list[MappingEvidence]] = relationship(back_populates="decision")
+    history: Mapped[list[MappingDecisionEvent]] = relationship(
+        back_populates="decision", cascade="all, delete-orphan"
+    )
+
+
+class MappingDecisionCandidate(Base):
+    __tablename__ = "mapping_decision_candidates"
+
+    decision_id: Mapped[str] = mapped_column(
+        ForeignKey("mapping_decisions.id", ondelete="CASCADE"), primary_key=True
+    )
+    candidate_id: Mapped[str] = mapped_column(
+        ForeignKey("mapping_candidates.id", ondelete="CASCADE"), primary_key=True
+    )
+
+
+class MappingDecisionEvent(Base):
+    __tablename__ = "mapping_decision_events"
+    __table_args__ = (Index("ix_mapping_decision_events_decision", "decision_id", "created_at"),)
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    decision_id: Mapped[str] = mapped_column(
+        ForeignKey("mapping_decisions.id", ondelete="CASCADE"), nullable=False
+    )
+    event_type: Mapped[str] = mapped_column(String(100), nullable=False)
+    detail: Mapped[dict[str, Any]] = mapped_column(JSON, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+
+    decision: Mapped[MappingDecision] = relationship(back_populates="history")

groundstore/store.py

@@ -0,0 +1,398 @@
+"""Repository-style persistence API for mapping workflows."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import Counter
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+from oa_configurator import ResolvedDatabase, Resolver
+from sqlalchemy import Engine, select
+from sqlalchemy.orm import sessionmaker
+
+from .contracts import (
+    MappingCandidateSpec,
+    MappingDecisionSpec,
+    MappingEvidenceSpec,
+    MappingInputSpec,
+    MappingRunSpec,
+)
+from .engine import create_groundstore_engine, create_schema
+from .models import (
+    MappingCandidate,
+    MappingDecision,
+    MappingDecisionCandidate,
+    MappingDecisionEvent,
+    MappingEvidence,
+    MappingInput,
+    MappingRun,
+)
+
+
+class MappingStore:
+    """Persist and resume source-independent mapping workflows."""
+
+    def __init__(self, engine: Engine, *, initialize: bool = True) -> None:
+        self.engine = engine
+        self._session_factory = sessionmaker(bind=engine, expire_on_commit=False)
+        if initialize:
+            create_schema(engine)
+
+    @classmethod
+    def from_url(cls, url: str, **engine_kwargs: Any) -> MappingStore:
+        return cls(create_groundstore_engine(url, **engine_kwargs))
+
+    @classmethod
+    def from_database(cls, database: ResolvedDatabase, **engine_kwargs: Any) -> MappingStore:
+        """Create a store from an already-resolved OA database resource."""
+        return cls(create_groundstore_engine(resolved_database=database, **engine_kwargs))
+
+    @classmethod
+    def from_resolver(
+        cls, resolver: Resolver, database_name: str = "mapping_db", **engine_kwargs: Any
+    ) -> MappingStore:
+        engine = create_groundstore_engine(
+            resolver=resolver, database_name=database_name, **engine_kwargs
+        )
+        return cls(engine)
+
+    def get_or_create_run(self, spec: MappingRunSpec) -> MappingRun:
+        """Return the stable run for *spec*, preserving resumable state."""
+        with self._session_factory() as session:
+            run = session.scalar(
+                select(MappingRun).where(
+                    MappingRun.source_namespace == spec.source_namespace,
+                    MappingRun.source_fingerprint == spec.source_fingerprint,
+                    MappingRun.target_system == spec.target_system,
+                    MappingRun.target_release == spec.target_release,
+                    MappingRun.algorithm_version == spec.algorithm_version,
+                    MappingRun.policy_version == spec.policy_version,
+                )
+            )
+            if run is None:
+                now = _now()
+                run = MappingRun(
+                    id=_id(),
+                    **spec.model_dump(exclude={"lifecycle_status"}),
+                    lifecycle_status=spec.lifecycle_status.value,
+                    created_at=now,
+                    updated_at=now,
+                )
+                session.add(run)
+                session.commit()
+            return run
+
+    def update_run(
+        self,
+        run_id: str,
+        *,
+        lifecycle_status: str | None = None,
+        last_error: str | None = None,
+    ) -> MappingRun:
+        with self._session_factory() as session:
+            run = session.get(MappingRun, run_id)
+            if run is None:
+                raise KeyError(f"unknown mapping run: {run_id}")
+            if lifecycle_status is not None:
+                run.lifecycle_status = lifecycle_status
+            run.last_error = last_error
+            run.updated_at = _now()
+            session.commit()
+            return run
+
+    def upsert_input(self, run_id: str, spec: MappingInputSpec) -> MappingInput:
+        """Insert or return an input, retaining candidates and decisions on retry."""
+        with self._session_factory() as session:
+            record = session.scalar(
+                select(MappingInput).where(
+                    MappingInput.run_id == run_id,
+                    MappingInput.source_namespace == spec.source_namespace,
+                    MappingInput.source_kind == spec.source_kind,
+                    MappingInput.source_key == spec.source_key,
+                    MappingInput.source_fingerprint == spec.source_fingerprint,
+                )
+            )
+            if record is None:
+                now = _now()
+                record = MappingInput(
+                    id=_id(),
+                    run_id=run_id,
+                    **spec.model_dump(exclude={"lifecycle_status"}),
+                    lifecycle_status=spec.lifecycle_status.value,
+                    created_at=now,
+                    updated_at=now,
+                )
+                session.add(record)
+                session.commit()
+            return record
+
+    def update_input(
+        self,
+        input_id: str,
+        *,
+        lifecycle_status: str | None = None,
+        retry_count: int | None = None,
+        last_error: str | None = None,
+    ) -> MappingInput:
+        """Update processing state without replacing mapping evidence."""
+        with self._session_factory() as session:
+            record = session.get(MappingInput, input_id)
+            if record is None:
+                raise KeyError(f"unknown mapping input: {input_id}")
+            if lifecycle_status is not None:
+                record.lifecycle_status = lifecycle_status
+            if retry_count is not None:
+                if retry_count < 0:
+                    raise ValueError("retry_count cannot be negative")
+                record.retry_count = retry_count
+            record.last_error = last_error
+            record.updated_at = _now()
+            session.commit()
+            return record
+
+    def get_candidates(self, input_id: str) -> list[MappingCandidate]:
+        """Return candidates for one input in deterministic rank order."""
+        with self._session_factory() as session:
+            return list(
+                session.scalars(
+                    select(MappingCandidate)
+                    .where(MappingCandidate.input_id == input_id)
+                    .order_by(MappingCandidate.rank, MappingCandidate.created_at)
+                )
+            )
+
+    def upsert_candidate(self, input_id: str, spec: MappingCandidateSpec) -> MappingCandidate:
+        """Insert or return a candidate using a deterministic semantic key."""
+        key = _candidate_key(spec)
+        with self._session_factory() as session:
+            candidate = session.scalar(
+                select(MappingCandidate).where(
+                    MappingCandidate.input_id == input_id,
+                    MappingCandidate.candidate_key == key,
+                )
+            )
+            if candidate is None:
+                candidate = MappingCandidate(
+                    id=_id(),
+                    input_id=input_id,
+                    candidate_key=key,
+                    **spec.model_dump(exclude={"metadata"}),
+                    metadata_=spec.metadata,
+                    created_at=_now(),
+                )
+                session.add(candidate)
+                session.commit()
+            return candidate
+
+    def add_evidence(
+        self,
+        input_id: str,
+        spec: MappingEvidenceSpec,
+        *,
+        candidate_id: str | None = None,
+        decision_id: str | None = None,
+    ) -> MappingEvidence:
+        """Insert or return evidence, attached to exactly one candidate or decision."""
+        if (candidate_id is None) == (decision_id is None):
+            raise ValueError("evidence must reference exactly one candidate or decision")
+        with self._session_factory() as session:
+            if candidate_id is not None:
+                candidate = session.scalar(
+                    select(MappingCandidate).where(
+                        MappingCandidate.id == candidate_id,
+                        MappingCandidate.input_id == input_id,
+                    )
+                )
+                if candidate is None:
+                    raise ValueError("candidate must belong to the input")
+            if decision_id is not None:
+                decision = session.scalar(
+                    select(MappingDecision).where(
+                        MappingDecision.id == decision_id,
+                        MappingDecision.input_id == input_id,
+                    )
+                )
+                if decision is None:
+                    raise ValueError("decision must belong to the input")
+            evidence = session.scalar(
+                select(MappingEvidence).where(
+                    MappingEvidence.input_id == input_id,
+                    MappingEvidence.evidence_key == spec.evidence_key,
+                )
+            )
+            if evidence is None:
+                evidence = MappingEvidence(
+                    id=_id(),
+                    input_id=input_id,
+                    candidate_id=candidate_id,
+                    decision_id=decision_id,
+                    **spec.model_dump(),
+                    created_at=_now(),
+                )
+                session.add(evidence)
+                session.commit()
+            return evidence
+
+    def record_decision(self, input_id: str, spec: MappingDecisionSpec) -> MappingDecision:
+        """Append a decision version and its immutable history event."""
+        with self._session_factory() as session:
+            if len(spec.selected_candidate_ids) != len(set(spec.selected_candidate_ids)):
+                raise ValueError("selected candidates must be unique")
+            selected = list(
+                session.scalars(
+                    select(MappingCandidate).where(
+                        MappingCandidate.input_id == input_id,
+                        MappingCandidate.id.in_(spec.selected_candidate_ids),
+                    )
+                )
+            )
+            if len(selected) != len(set(spec.selected_candidate_ids)):
+                raise ValueError("all selected candidates must belong to the input")
+            latest = session.scalar(
+                select(MappingDecision)
+                .where(MappingDecision.input_id == input_id)
+                .order_by(MappingDecision.decision_version.desc())
+            )
+            version = 1 if latest is None else latest.decision_version + 1
+            decision = MappingDecision(
+                id=_id(),
+                input_id=input_id,
+                decision_version=version,
+                decision_status=spec.decision_status.value,
+                outcome_code=spec.outcome_code,
+                reason_codes=spec.reason_codes,
+                decided_by=spec.decided_by,
+                metadata_=spec.metadata,
+                decided_at=_now(),
+            )
+            decision.selected_candidates = selected
+            decision.history.append(
+                MappingDecisionEvent(
+                    id=_id(),
+                    event_type="decision_recorded",
+                    detail={
+                        "decision_status": spec.decision_status.value,
+                        "decision_version": version,
+                    },
+                    created_at=_now(),
+                )
+            )
+            session.add(decision)
+            session.commit()
+            return decision
+
+    def latest_decision(self, input_id: str) -> MappingDecision | None:
+        with self._session_factory() as session:
+            return session.scalar(
+                select(MappingDecision)
+                .where(MappingDecision.input_id == input_id)
+                .order_by(MappingDecision.decision_version.desc())
+            )
+
+    def get_input(self, input_id: str) -> MappingInput | None:
+        """Return one input without relying on lazy relationships."""
+        with self._session_factory() as session:
+            return session.get(MappingInput, input_id)
+
+    def get_evidence(self, input_id: str) -> list[MappingEvidence]:
+        """Return all evidence for an input in insertion order."""
+        with self._session_factory() as session:
+            return list(
+                session.scalars(
+                    select(MappingEvidence)
+                    .where(MappingEvidence.input_id == input_id)
+                    .order_by(MappingEvidence.created_at, MappingEvidence.id)
+                )
+            )
+
+    def get_decision_candidate_ids(self, decision_id: str) -> list[str]:
+        """Return selected candidate IDs in stable candidate order."""
+        with self._session_factory() as session:
+            rows = session.execute(
+                select(MappingDecisionCandidate.candidate_id)
+                .where(MappingDecisionCandidate.decision_id == decision_id)
+                .join(
+                    MappingCandidate,
+                    MappingCandidate.id == MappingDecisionCandidate.candidate_id,
+                )
+                .order_by(MappingCandidate.rank, MappingCandidate.id)
+            )
+            return [candidate_id for (candidate_id,) in rows]
+
+    def get_decision_history(self, decision_id: str) -> list[MappingDecisionEvent]:
+        """Return immutable history events for one decision."""
+        with self._session_factory() as session:
+            return list(
+                session.scalars(
+                    select(MappingDecisionEvent)
+                    .where(MappingDecisionEvent.decision_id == decision_id)
+                    .order_by(MappingDecisionEvent.created_at, MappingDecisionEvent.id)
+                )
+            )
+
+    def coverage(self, run_id: str) -> dict[str, Any]:
+        """Return lifecycle and latest decision counts for a run."""
+        with self._session_factory() as session:
+            inputs = list(
+                session.scalars(select(MappingInput).where(MappingInput.run_id == run_id))
+            )
+            decisions = []
+            for input_record in inputs:
+                decision = session.scalar(
+                    select(MappingDecision)
+                    .where(MappingDecision.input_id == input_record.id)
+                    .order_by(MappingDecision.decision_version.desc())
+                )
+                if decision is not None:
+                    decisions.append(decision)
+            return {
+                "input_count": len(inputs),
+                "lifecycle_status": dict(Counter(item.lifecycle_status for item in inputs)),
+                "decision_status": dict(Counter(item.decision_status for item in decisions)),
+            }
+
+    def get_run(self, run_id: str) -> MappingRun | None:
+        with self._session_factory() as session:
+            return session.get(MappingRun, run_id)
+
+    def get_inputs(self, run_id: str) -> list[MappingInput]:
+        with self._session_factory() as session:
+            return list(session.scalars(select(MappingInput).where(MappingInput.run_id == run_id)))
+
+    def latest_successful_run(
+        self, source_namespace: str, *, target_system: str | None = None
+    ) -> MappingRun | None:
+        """Return the newest complete run for a source and target system."""
+        with self._session_factory() as session:
+            query = select(MappingRun).where(
+                MappingRun.source_namespace == source_namespace,
+                MappingRun.lifecycle_status == "complete",
+            )
+            if target_system is not None:
+                query = query.where(MappingRun.target_system == target_system)
+            return session.scalar(query.order_by(MappingRun.updated_at.desc()))
+
+
+def _id() -> str:
+    return str(uuid4())
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _candidate_key(spec: MappingCandidateSpec) -> str:
+    payload = {
+        "target_namespace": spec.target_namespace,
+        "target_vocabulary_id": spec.target_vocabulary_id,
+        "target_concept_id": spec.target_concept_id,
+        "target_code": spec.target_code,
+        "target_grain": spec.target_grain,
+        "target_role": spec.target_role,
+        "method": spec.method,
+    }
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

groundstore-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+groundstore/__init__.py,sha256=wAvMCygyd7SqddIq8vzvRt71QC2RIIxs-F1Iry5qZn8,791
+groundstore/context.py,sha256=d9RnKhFT4fk7Dx-1L9UqHwo2BQcqRauWNEWemEoThzI,8829
+groundstore/contracts.py,sha256=WPn-5RAdmEZDy7JkW08949Wm04sbVYbFKXXFDrF_gaI,3524
+groundstore/engine.py,sha256=plYQ0xhZv2RtI-kFFBiL8Djf625fT2iXUa7Lggp20U4,2171
+groundstore/models.py,sha256=OrCfQiUN1yYSOGOgopZbruB2eWX_Rx7yJNO3miQ3QhA,9466
+groundstore/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundstore/store.py,sha256=WCOffVJuhaePsPvcPrPGd3wub7Ce7qqZ_2oJcM38Ffw,16076
+groundstore-0.1.0.dist-info/METADATA,sha256=oT-0XBcbcYb72egA4ERSzQQHKrNH5kfA6iakFkBPLrI,490
+groundstore-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+groundstore-0.1.0.dist-info/RECORD,,

groundstore-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any