roborean-storage-sqlalchemy 0.1.2__tar.gz

roborean_storage_sqlalchemy-0.1.2/.gitignore

@@ -0,0 +1,27 @@
+venv/
+venv-qt5/
+venv-qt6/
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+*.tsbuildinfo
+node_modules/
+.pnpm-store/
+.DS_Store
+.idea/
+.vscode/*.local
+playground/
+.e2e-ai/
+**/test-results/
+**/playwright-report/
+research/
+.roborean/
+.roborean-sql-artifacts/
+*.db

roborean_storage_sqlalchemy-0.1.2/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- SQLAlchemy ORM tables and repository adapters for projects and durable
+  runs, mapping to Pydantic domain models.
+
+### Changed
+
+### Fixed
+
+- Lower inter-package dependency pins to `>=0.1.1` to match lockstep
+  release versions.

roborean_storage_sqlalchemy-0.1.2/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: roborean-storage-sqlalchemy
+Version: 0.1.2
+Summary: SQLAlchemy persistence adapter for Roborean
+Project-URL: Homepage, https://github.com/TNick/roborean
+Project-URL: Repository, https://github.com/TNick/roborean
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: roborean-spec>=0.1.1
+Requires-Dist: roborean-storage-base>=0.1.1
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: flake8>=7.0; extra == 'dev'
+Requires-Dist: isort>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# roborean-storage-sqlalchemy
+
+SQLAlchemy adapter for Roborean projects and durable runs. ORM rows map
+to/from Pydantic domain models; the engine depends only on repository ports.
+
+```python
+from roborean_storage_sqlalchemy import (
+    SqlAlchemyProjectRepository,
+    make_engine,
+    make_session_factory,
+    upgrade,
+)
+
+engine = make_engine("sqlite+pysqlite:///./roborean.db")
+upgrade(engine)
+factory = make_session_factory(engine)
+projects = SqlAlchemyProjectRepository(factory)
+```

roborean_storage_sqlalchemy-0.1.2/README.md

@@ -0,0 +1,18 @@
+# roborean-storage-sqlalchemy
+
+SQLAlchemy adapter for Roborean projects and durable runs. ORM rows map
+to/from Pydantic domain models; the engine depends only on repository ports.
+
+```python
+from roborean_storage_sqlalchemy import (
+    SqlAlchemyProjectRepository,
+    make_engine,
+    make_session_factory,
+    upgrade,
+)
+
+engine = make_engine("sqlite+pysqlite:///./roborean.db")
+upgrade(engine)
+factory = make_session_factory(engine)
+projects = SqlAlchemyProjectRepository(factory)
+```

roborean_storage_sqlalchemy-0.1.2/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roborean-storage-sqlalchemy"
+version = "0.1.2"
+description = "SQLAlchemy persistence adapter for Roborean"
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+dependencies = [
+  "SQLAlchemy>=2.0",
+  "roborean-spec>=0.1.1",
+  "roborean-storage-base>=0.1.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "black>=24.0", "isort>=5.0", "flake8>=7.0"]
+
+
+[project.urls]
+Homepage = "https://github.com/TNick/roborean"
+Repository = "https://github.com/TNick/roborean"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roborean_storage_sqlalchemy"]

roborean_storage_sqlalchemy-0.1.2/src/roborean_storage_sqlalchemy/__init__.py

@@ -0,0 +1,18 @@
+"""SQLAlchemy persistence adapter for Roborean."""
+
+from .migrate import SCHEMA_VERSION, upgrade
+from .project_repo import SqlAlchemyProjectRepository
+from .run_repo import SqlAlchemyRunRepository
+from .session import create_all, make_engine, make_session_factory
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "SqlAlchemyProjectRepository",
+    "SqlAlchemyRunRepository",
+    "create_all",
+    "make_engine",
+    "make_session_factory",
+    "upgrade",
+]

roborean_storage_sqlalchemy-0.1.2/src/roborean_storage_sqlalchemy/mappers.py

@@ -0,0 +1,157 @@
+"""Map between ORM rows and Pydantic domain models."""
+
+import json
+from datetime import UTC, datetime
+
+from roborean_spec import (
+    Project,
+    RunDiff,
+    RunError,
+    RunRecord,
+    RunRequest,
+    RunResults,
+    RunStatus,
+    project_from_dict,
+    project_to_dict,
+)
+
+from .models import ProjectRevisionRow, ProjectRow, RunRow
+
+
+def _parse_dt(value: str | None) -> datetime | None:
+    """Parse an ISO timestamp into an aware datetime."""
+    if value is None:
+        return None
+    return datetime.fromisoformat(value)
+
+
+def _fmt_dt(value: datetime | None) -> str | None:
+    """Format a datetime as ISO-8601."""
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=UTC)
+    return value.isoformat()
+
+
+def project_to_row(project: Project, revision: str) -> ProjectRow:
+    """Build a current-project ORM row."""
+    now = datetime.now(UTC)
+    return ProjectRow(
+        id=project.id,
+        revision=revision,
+        name=project.name,
+        schema_version=project.schema_version,
+        body_json=json.dumps(project_to_dict(project), ensure_ascii=False),
+        created_at=now,
+        updated_at=now,
+    )
+
+
+def row_to_project(row: ProjectRow) -> Project:
+    """Restore a project from a current-project row."""
+    return project_from_dict(json.loads(row.body_json))
+
+
+def revision_to_row(
+    project: Project,
+    revision: str,
+    compiled_json: str | None = None,
+) -> ProjectRevisionRow:
+    """Build a revision snapshot row."""
+    return ProjectRevisionRow(
+        project_id=project.id,
+        revision=revision,
+        body_json=json.dumps(project_to_dict(project), ensure_ascii=False),
+        compiled_json=compiled_json,
+        created_at=datetime.now(UTC),
+    )
+
+
+def run_to_row(record: RunRecord) -> RunRow:
+    """Build a run ORM row from a domain record."""
+    return RunRow(
+        run_id=record.run_id,
+        project_id=record.project_id,
+        project_revision=record.project_revision,
+        idempotency_key=record.idempotency_key,
+        status=record.status.value,
+        request_json=json.dumps(
+            record.request.model_dump(
+                mode="json", by_alias=True, exclude_none=True
+            ),
+            ensure_ascii=False,
+        ),
+        results_json=(
+            None
+            if record.results is None
+            else json.dumps(
+                record.results.model_dump(
+                    mode="json", by_alias=True, exclude_none=True
+                ),
+                ensure_ascii=False,
+            )
+        ),
+        diff_json=(
+            None
+            if record.diff is None
+            else json.dumps(
+                record.diff.model_dump(
+                    mode="json", by_alias=True, exclude_none=True
+                ),
+                ensure_ascii=False,
+            )
+        ),
+        attempt=record.attempt,
+        engine_version=record.engine_version,
+        plugin_versions_json=json.dumps(record.plugin_versions),
+        compiled_digest=record.compiled_digest,
+        error_json=(
+            None
+            if record.error is None
+            else json.dumps(
+                record.error.model_dump(
+                    mode="json", by_alias=True, exclude_none=True
+                ),
+                ensure_ascii=False,
+            )
+        ),
+        request_digest=record.request_digest,
+        retry_policy_json=json.dumps(record.retry_policy_snapshot),
+        created_at=_parse_dt(record.created_at) or datetime.now(UTC),
+        started_at=_parse_dt(record.started_at),
+        finished_at=_parse_dt(record.finished_at),
+    )
+
+
+def row_to_run(row: RunRow) -> RunRecord:
+    """Restore a domain run record from an ORM row."""
+    results = None
+    if row.results_json:
+        results = RunResults.model_validate(json.loads(row.results_json))
+    diff = None
+    if row.diff_json:
+        diff = RunDiff.model_validate(json.loads(row.diff_json))
+    error = None
+    if row.error_json:
+        error = RunError.model_validate(json.loads(row.error_json))
+    return RunRecord(
+        runId=row.run_id,
+        idempotencyKey=row.idempotency_key,
+        projectId=row.project_id,
+        projectRevision=row.project_revision,
+        compiledDigest=row.compiled_digest,
+        status=RunStatus(row.status),
+        request=RunRequest.model_validate(json.loads(row.request_json)),
+        results=results,
+        diff=diff,
+        attempt=row.attempt,
+        retryPolicySnapshot=json.loads(row.retry_policy_json),
+        engineVersion=row.engine_version,
+        pluginVersions=json.loads(row.plugin_versions_json),
+        error=error,
+        createdAt=_fmt_dt(row.created_at) or "",
+        startedAt=_fmt_dt(row.started_at),
+        finishedAt=_fmt_dt(row.finished_at),
+        requestDigest=row.request_digest,
+    )

roborean_storage_sqlalchemy-0.1.2/src/roborean_storage_sqlalchemy/migrate.py

@@ -0,0 +1,29 @@
+"""Internal storage schema migrator."""
+
+from sqlalchemy import Engine, select
+from sqlalchemy.orm import Session
+
+from .models import SchemaMetaRow
+from .session import create_all
+
+SCHEMA_VERSION = 1
+
+
+def current_version(engine: Engine) -> int:
+    """Return the installed schema version, or 0 when unset."""
+    create_all(engine)
+    with Session(engine) as session:
+        row = session.scalar(select(SchemaMetaRow).limit(1))
+        return 0 if row is None else row.version
+
+
+def upgrade(engine: Engine) -> None:
+    """Create tables and stamp the schema version."""
+    create_all(engine)
+    with Session(engine) as session:
+        row = session.scalar(select(SchemaMetaRow).limit(1))
+        if row is None:
+            session.add(SchemaMetaRow(id=1, version=SCHEMA_VERSION))
+        else:
+            row.version = SCHEMA_VERSION
+        session.commit()

roborean_storage_sqlalchemy-0.1.2/src/roborean_storage_sqlalchemy/models.py

@@ -0,0 +1,81 @@
+"""ORM storage shapes (not domain models)."""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, String, Text, UniqueConstraint
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    """Declarative base for Roborean storage tables."""
+
+
+class SchemaMetaRow(Base):
+    """Tracks the storage schema version."""
+
+    __tablename__ = "schema_meta"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    version: Mapped[int] = mapped_column(Integer, nullable=False)
+
+
+class ProjectRow(Base):
+    """Current project document storage."""
+
+    __tablename__ = "projects"
+
+    id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    revision: Mapped[str] = mapped_column(String(128), nullable=False)
+    name: Mapped[str] = mapped_column(String(512), nullable=False)
+    schema_version: Mapped[str] = mapped_column(String(32), nullable=False)
+    body_json: Mapped[str] = mapped_column(Text, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class ProjectRevisionRow(Base):
+    """Immutable project revision snapshots."""
+
+    __tablename__ = "project_revisions"
+
+    project_id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    revision: Mapped[str] = mapped_column(String(128), primary_key=True)
+    body_json: Mapped[str] = mapped_column(Text, nullable=False)
+    compiled_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+
+class RunRow(Base):
+    """Durable run records."""
+
+    __tablename__ = "runs"
+    __table_args__ = (
+        UniqueConstraint(
+            "project_id",
+            "idempotency_key",
+            name="uq_runs_project_idempotency",
+        ),
+    )
+
+    run_id: Mapped[str] = mapped_column(String(128), primary_key=True)
+    project_id: Mapped[str] = mapped_column(String(255), nullable=False)
+    project_revision: Mapped[str] = mapped_column(String(128), nullable=False)
+    idempotency_key: Mapped[str] = mapped_column(String(128), nullable=False)
+    status: Mapped[str] = mapped_column(String(32), nullable=False)
+    request_json: Mapped[str] = mapped_column(Text, nullable=False)
+    results_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    diff_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    attempt: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
+    engine_version: Mapped[str] = mapped_column(String(64), nullable=False)
+    plugin_versions_json: Mapped[str] = mapped_column(Text, nullable=False)
+    compiled_digest: Mapped[str] = mapped_column(String(128), nullable=False)
+    error_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    request_digest: Mapped[str] = mapped_column(String(128), nullable=False)
+    retry_policy_json: Mapped[str] = mapped_column(Text, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    started_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    finished_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )

roborean_storage_sqlalchemy-0.1.2/src/roborean_storage_sqlalchemy/project_repo.py

@@ -0,0 +1,80 @@
+"""SQLAlchemy project repository."""
+
+import json
+from datetime import UTC, datetime
+
+from roborean_spec import Project, project_from_dict
+from roborean_storage_base import NotFoundError
+from sqlalchemy import select
+from sqlalchemy.orm import sessionmaker
+
+from .mappers import project_to_row, revision_to_row, row_to_project
+from .models import ProjectRevisionRow, ProjectRow
+
+
+class SqlAlchemyProjectRepository:
+    """Persist projects through SQLAlchemy sessions."""
+
+    def __init__(self, session_factory: sessionmaker) -> None:
+        """Bind to a session factory."""
+        self._session_factory = session_factory
+
+    def get(self, project_id: str) -> Project:
+        """Return the current project document."""
+        with self._session_factory() as session:
+            row = session.get(ProjectRow, project_id)
+            if row is None:
+                raise NotFoundError(project_id)
+            return row_to_project(row)
+
+    def get_revision(self, project_id: str, revision: str) -> Project:
+        """Return a pinned revision document."""
+        with self._session_factory() as session:
+            row = session.get(
+                ProjectRevisionRow,
+                {"project_id": project_id, "revision": revision},
+            )
+            if row is None:
+                raise NotFoundError(f"{project_id}@{revision}")
+            return project_from_dict(json.loads(row.body_json))
+
+    def save(self, project: Project, *, revision: str | None = None) -> str:
+        """Upsert the current project and write a revision snapshot."""
+        rev = revision or "1"
+        with self._session_factory() as session:
+            existing = session.get(ProjectRow, project.id)
+            if existing is None:
+                session.add(project_to_row(project, rev))
+            else:
+                existing.revision = rev
+                existing.name = project.name
+                existing.schema_version = project.schema_version
+                existing.body_json = project_to_row(project, rev).body_json
+                existing.updated_at = datetime.now(UTC)
+            session.merge(revision_to_row(project, rev))
+            session.commit()
+        return rev
+
+    def list_ids(self) -> list[str]:
+        """List stored project identifiers."""
+        with self._session_factory() as session:
+            rows = session.scalars(
+                select(ProjectRow.id).order_by(ProjectRow.id)
+            )
+            return list(rows)
+
+    def delete(self, project_id: str) -> None:
+        """Delete a project and its revisions."""
+        with self._session_factory() as session:
+            row = session.get(ProjectRow, project_id)
+            if row is None:
+                raise NotFoundError(project_id)
+            session.delete(row)
+            revisions = session.scalars(
+                select(ProjectRevisionRow).where(
+                    ProjectRevisionRow.project_id == project_id
+                )
+            )
+            for revision in revisions:
+                session.delete(revision)
+            session.commit()

roborean_storage_sqlalchemy-0.1.2/src/roborean_storage_sqlalchemy/run_repo.py

@@ -0,0 +1,103 @@
+"""SQLAlchemy run repository."""
+
+import logging
+
+from roborean_spec import RunRecord
+from roborean_storage_base import ConflictError, NotFoundError
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError as SAIntegrityError
+from sqlalchemy.orm import sessionmaker
+
+from .mappers import row_to_run, run_to_row
+from .models import RunRow
+
+logger = logging.getLogger(__name__)
+
+
+class SqlAlchemyRunRepository:
+    """Persist durable runs through SQLAlchemy sessions."""
+
+    def __init__(self, session_factory: sessionmaker) -> None:
+        """Bind to a session factory."""
+        self._session_factory = session_factory
+
+    def get(self, run_id: str) -> RunRecord:
+        """Return one run by identifier."""
+        with self._session_factory() as session:
+            row = session.get(RunRow, run_id)
+            if row is None:
+                raise NotFoundError(run_id)
+            return row_to_run(row)
+
+    def get_by_idempotency(
+        self, project_id: str, idempotency_key: str
+    ) -> RunRecord | None:
+        """Return an existing run for an idempotency key, if any."""
+        with self._session_factory() as session:
+            row = session.scalar(
+                select(RunRow).where(
+                    RunRow.project_id == project_id,
+                    RunRow.idempotency_key == idempotency_key,
+                )
+            )
+            return None if row is None else row_to_run(row)
+
+    def save(self, record: RunRecord) -> None:
+        """Insert a new run, mapping unique violations to conflicts."""
+        with self._session_factory() as session:
+            existing = session.scalar(
+                select(RunRow).where(
+                    RunRow.project_id == record.project_id,
+                    RunRow.idempotency_key == record.idempotency_key,
+                )
+            )
+            if existing is not None:
+                if existing.request_digest != record.request_digest:
+                    raise ConflictError(
+                        "idempotency key reused with a different request body"
+                    )
+                raise ConflictError("idempotency key already exists")
+            session.add(run_to_row(record))
+            try:
+                session.commit()
+            except SAIntegrityError as error:
+                session.rollback()
+                logger.debug(
+                    "Unique constraint on run insert for %s",
+                    record.run_id,
+                    exc_info=True,
+                )
+                raise ConflictError("idempotency key already exists") from error
+
+    def update(self, record: RunRecord) -> None:
+        """Replace an existing run row."""
+        with self._session_factory() as session:
+            row = session.get(RunRow, record.run_id)
+            if row is None:
+                raise NotFoundError(record.run_id)
+            mapped = run_to_row(record)
+            row.status = mapped.status
+            row.request_json = mapped.request_json
+            row.results_json = mapped.results_json
+            row.diff_json = mapped.diff_json
+            row.attempt = mapped.attempt
+            row.error_json = mapped.error_json
+            row.compiled_digest = mapped.compiled_digest
+            row.plugin_versions_json = mapped.plugin_versions_json
+            row.retry_policy_json = mapped.retry_policy_json
+            row.started_at = mapped.started_at
+            row.finished_at = mapped.finished_at
+            session.commit()
+
+    def list_for_project(
+        self, project_id: str, *, limit: int = 50
+    ) -> list[RunRecord]:
+        """List recent runs for a project, newest first."""
+        with self._session_factory() as session:
+            rows = session.scalars(
+                select(RunRow)
+                .where(RunRow.project_id == project_id)
+                .order_by(RunRow.created_at.desc())
+                .limit(limit)
+            )
+            return [row_to_run(row) for row in rows]

roborean_storage_sqlalchemy-0.1.2/src/roborean_storage_sqlalchemy/session.py

@@ -0,0 +1,21 @@
+"""Engine and session helpers."""
+
+from sqlalchemy import Engine, create_engine
+from sqlalchemy.orm import sessionmaker
+
+from .models import Base
+
+
+def make_engine(url: str) -> Engine:
+    """Create a SQLAlchemy engine for the given URL."""
+    return create_engine(url, future=True)
+
+
+def make_session_factory(engine: Engine) -> sessionmaker:
+    """Create a session factory bound to ``engine``."""
+    return sessionmaker(bind=engine, expire_on_commit=False, future=True)
+
+
+def create_all(engine: Engine) -> None:
+    """Create ORM tables if they do not exist."""
+    Base.metadata.create_all(engine)

roborean_storage_sqlalchemy-0.1.2/tests/conftest.py

@@ -0,0 +1,36 @@
+"""Shared fixtures for SQLAlchemy storage tests."""
+
+import pytest
+from roborean_spec import project_from_dict
+from roborean_storage_sqlalchemy import (
+    make_engine,
+    make_session_factory,
+    upgrade,
+)
+
+
+@pytest.fixture
+def session_factory(tmp_path):
+    """Return a session factory over a temporary SQLite database."""
+    url = f"sqlite+pysqlite:///{tmp_path / 'test.db'}"
+    engine = make_engine(url)
+    upgrade(engine)
+    return make_session_factory(engine)
+
+
+@pytest.fixture
+def minimal_project():
+    """Return a tiny valid project model."""
+    return project_from_dict(
+        {
+            "schemaVersion": "1.0.0",
+            "id": "example.minimal",
+            "name": "Minimal",
+            "pluginRequirements": [],
+            "workspace": {"variables": []},
+            "bits": [],
+            "documents": [],
+            "templates": [],
+            "metadata": {},
+        }
+    )

roborean_storage_sqlalchemy-0.1.2/tests/repos_test.py

@@ -0,0 +1,53 @@
+"""Integration tests for SQLAlchemy repositories."""
+
+import pytest
+from roborean_spec import (
+    RunRecord,
+    RunRequest,
+    RunStatus,
+    RunTrigger,
+)
+from roborean_storage_base import ConflictError
+from roborean_storage_sqlalchemy import (
+    SqlAlchemyProjectRepository,
+    SqlAlchemyRunRepository,
+)
+
+
+@pytest.mark.integration
+class TestSqlAlchemyRepos:
+    """Project and run persistence through SQLAlchemy."""
+
+    def test_project_roundtrip(self, session_factory, minimal_project) -> None:
+        """Projects save and load."""
+        repo = SqlAlchemyProjectRepository(session_factory)
+        repo.save(minimal_project, revision="1")
+        assert repo.get(minimal_project.id).name == "Minimal"
+        loaded = repo.get_revision(minimal_project.id, "1")
+        assert loaded.id == minimal_project.id
+
+    def test_run_idempotency(self, session_factory) -> None:
+        """Duplicate idempotency keys conflict."""
+        repo = SqlAlchemyRunRepository(session_factory)
+        record = RunRecord(
+            runId="r1",
+            idempotencyKey="k1",
+            projectId="example.minimal",
+            projectRevision="1",
+            compiledDigest="d",
+            status=RunStatus.QUEUED,
+            request=RunRequest(
+                projectId="example.minimal",
+                idempotencyKey="k1",
+                trigger=RunTrigger.TEST,
+            ),
+            attempt=1,
+            engineVersion="0.2.0",
+            pluginVersions={},
+            createdAt="2026-01-01T00:00:00+00:00",
+            requestDigest="abc",
+        )
+        repo.save(record)
+        with pytest.raises(ConflictError):
+            repo.save(record.model_copy(update={"run_id": "r2"}))
+        assert repo.get_by_idempotency("example.minimal", "k1").run_id == "r1"