rhizodat 0.1.0__tar.gz

rhizodat-0.1.0/.env.test

@@ -0,0 +1,6 @@
+# DSNs of the stores in compose.yaml. A variable set in the environment overrides its line.
+RHIZODAT_TEST_PG_DSN=postgresql://postgres:rhizodat@127.0.0.1:55440/rhizodat
+RHIZODAT_TEST_DREVO_BOLT=drevo+bolt://127.0.0.1:57687
+RHIZODAT_TEST_CLICKHOUSE_DSN=clickhouse://rhizodat:rhizodat@127.0.0.1:58123/rhizodat
+RHIZODAT_TEST_ICEBERG_REST_DSN=iceberg+rest://127.0.0.1:58181/?s3.endpoint=http://127.0.0.1:59000&s3.access-key-id=rhizodat&s3.secret-access-key=rhizodat-secret&s3.region=us-east-1&s3.path-style-access=true
+RHIZODAT_TEST_TOXIPROXY=http://127.0.0.1:58474

rhizodat-0.1.0/.github/ISSUE_TEMPLATE/feedback.yml

@@ -0,0 +1,39 @@
+name: Feedback on the proof of concept
+description: You tried rhizodat 0.1.0a1 — what worked, what did not, what is missing for you.
+title: "Feedback: "
+labels: ["feedback"]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: Version and install
+      description: "`pip show rhizodat rhizodat-native`, or the commit."
+      placeholder: "rhizodat 0.1.0a1, rhizodat-native 0.1.0a1, Python 3.13, macOS"
+    validations:
+      required: true
+  - type: dropdown
+    id: stores
+    attributes:
+      label: Stores you used
+      multiple: true
+      options: [PostgreSQL, ClickHouse, drevo, Iceberg]
+  - type: textarea
+    id: scenario
+    attributes:
+      label: What you tried to build
+      description: The use case in a few lines — the data model and the writes/reads.
+    validations:
+      required: true
+  - type: textarea
+    id: worked
+    attributes:
+      label: What worked
+  - type: textarea
+    id: failed
+    attributes:
+      label: What did not work, or was confusing
+      description: Error text in a code block, please; the shortest script that shows it is ideal.
+  - type: textarea
+    id: missing
+    attributes:
+      label: What is missing before you would use it

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

@@ -0,0 +1,118 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv lock --check
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+
+  docs:
+    # The documentation site builds with no broken link, anchor or API reference.
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked --group docs
+      - run: uv run --group docs mkdocs build --strict
+
+  rust:
+    # rhizodat-core: the same conformance vectors as the Python reference.
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        toolchain: [stable, "1.94"]
+    steps:
+      - uses: actions/checkout@v5
+      - run: rustup toolchain install ${{ matrix.toolchain }} --profile minimal --component clippy,rustfmt
+      - run: rustup default ${{ matrix.toolchain }}
+      - uses: Swatinem/rust-cache@v2
+      # The adapter crates' tests run against the compose PostgreSQL, drevo, ClickHouse and
+      # Iceberg REST catalog; the exported DSNs make a store that is down fail the run
+      # instead of skipping.
+      - name: Start PostgreSQL, drevo, ClickHouse and the Iceberg REST catalog
+        run: |
+          docker compose --profile clickhouse --profile iceberg up -d --wait postgres drevo clickhouse iceberg-rest
+          grep -E '^RHIZODAT_TEST_(PG_DSN|DREVO_BOLT|CLICKHOUSE_DSN|ICEBERG_REST_DSN)=' .env.test >> "$GITHUB_ENV"
+      - if: matrix.toolchain == 'stable'
+        run: cargo fmt --check
+      - if: matrix.toolchain == 'stable'
+        run: cargo clippy --locked --all-targets --all-features -- -D warnings
+      # --all-features includes embedded drevo (rhizodat-drevo/embedded), built from the
+      # pinned drevo commit.
+      - run: cargo test --locked --all-features
+
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python: "3.12"
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      # The stores from compose.yaml. Exporting .env.test makes the DSNs explicit, so a
+      # store that is down fails the run instead of skipping its tests. macOS runners have
+      # no Docker: there the store-backed tests skip.
+      - name: Start the test stores
+        if: runner.os == 'Linux'
+        run: |
+          docker compose --profile clickhouse --profile iceberg --profile faults up -d --wait
+          grep -v '^#' .env.test >> "$GITHUB_ENV"
+      - run: uv sync --locked
+      - run: uv run pytest
+
+  drevo-embedded:
+    # The full suite with every store and embedded drevo, where nothing may skip: a skip
+    # here means a test silently stopped running. drevo-py is not on PyPI yet: it is
+    # built from the pinned commit (Rust), cached by uv.
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      RHIZODAT_TEST_NO_SKIPS: "1"
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - name: Start the test stores
+        run: |
+          docker compose --profile clickhouse --profile iceberg --profile faults up -d --wait
+          grep -v '^#' .env.test >> "$GITHUB_ENV"
+      # native: the Rust core's Python module (crates/rhizodat-py), so its vectors run here.
+      - run: uv sync --locked --group drevo --group native
+      # Coverage of src/rhizodat with branches; below 92 % the job fails.
+      - run: uv run --group drevo --group native pytest --cov --cov-report=term-missing:skip-covered

rhizodat-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+# Publishes the documentation site to GitHub Pages on every push to main.
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked --group docs
+      - run: uv run --group docs mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

rhizodat-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,113 @@
+name: Release
+
+# A tag `vX.Y.Z` (or a pre-release like `v0.1.0a1`) builds the `rhizodat` package and
+# the `rhizodat-native` wheels (abi3, one per platform), attaches them to a GitHub
+# release and publishes both to PyPI through trusted publishing (the `pypi`
+# environment; PyPI must list this workflow as the publisher of both projects).
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  package:
+    # rhizodat (pure Python: sdist + wheel) and the rhizodat-native sdist.
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv build --out-dir dist
+      - run: uvx maturin sdist --manifest-path crates/rhizodat-py/Cargo.toml --out dist
+      - name: The tag is the package version
+        if: github.ref_type == 'tag'
+        run: |
+          version=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          test "v$version" = "${{ github.ref_name }}" || { echo "tag ${{ github.ref_name }} != v$version"; exit 1; }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package
+          path: dist/*
+
+  native:
+    # rhizodat-native wheels: abi3 (one wheel serves every CPython >= 3.12).
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64
+          - os: ubuntu-24.04-arm
+            target: aarch64
+          - os: macos-latest
+            target: aarch64
+          - os: macos-15-intel
+            target: x86_64
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: auto
+          working-directory: crates/rhizodat-py
+          args: --release --locked --out ../../dist --interpreter python3.12
+          sccache: true
+      - name: The wheel imports from a clean environment
+        run: |
+          python -m venv smoke
+          smoke/bin/pip install --no-index --find-links dist rhizodat-native
+          smoke/bin/python -c "import rhizodat_native as n; print(n.__version__, n.new_id())"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: native-${{ matrix.os }}-${{ matrix.target }}
+          path: dist/*.whl
+
+  github-release:
+    needs: [package, native]
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Create the release with the distributions attached
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          flags=(--generate-notes)
+          case "$TAG" in *a*|*b*|*rc*) flags+=(--prerelease);; esac
+          gh release create "$TAG" --repo "$GITHUB_REPOSITORY" "${flags[@]}" dist/*
+
+  pypi:
+    needs: [package, native]
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/rhizodat/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

rhizodat-0.1.0/.gitignore

@@ -0,0 +1,210 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# mkdocs build output
+/site/

rhizodat-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.1.0 — the MVP
+
+The v0.1 roadmap is complete. Since 0.1.0a1:
+
+- **Five end-to-end scenarios** in `tests/scenarios/` (a CBT journal, a bug
+  tracker, an ERP with valid time, an IT task manager, a story editor), each run
+  on the Python facade and on the native facade and closed with the same data
+  worked from both in turn. They are the reference for how an application uses
+  the package.
+- **The shipped stores and their limits**: one documentation page per store and
+  per facade with every known limit (`docs/adapters/stores.md`).
+- Packaging: `rhizodat[native]` pins the Rust core to the package version;
+  the `Release` workflow builds the wheels for Linux and macOS on x86_64 and
+  arm64 from a `v*` tag.
+
+## 0.1.0a1 — proof of concept
+
+The first public pre-release. One API over PostgreSQL, ClickHouse,
+[drevo](https://github.com/ice1x/drevo) and Apache Iceberg:
+
+- **Meta-transactions**: a Unit of Work across several stores commits atomically
+  (two-phase commit where the store has it, journaled one-phase application
+  after the decision where it does not), with retries and crash recovery.
+- **Bitemporal repositories**: every version of an entity is kept, with
+  transaction time and valid time; reads `as_of` / `known_at`, history.
+- **Entities over several stores**: an entity's parts may live in different
+  stores and are written in one meta-transaction.
+- **Migrations**: one TOML format for every store, the history in the journal.
+- **Imports**: files into stores with schema inference (`rhizodat import`).
+- **An MCP server** (`rhizodat-mcp`) and an adapter contract kit
+  (`rhizodat[testing]`) for adapter authors.
+- **The core in Rust**, opt-in: `pip install 'rhizodat[native]'` adds
+  `rhizodat_native`, whose stores, journal, coordinator and recovery run the
+  same protocol with no Python on the path; the Python package stays the
+  executable specification, and both pass one conformance suite.
+
+Known limits are listed per adapter in the documentation. Feedback on this
+release: open an issue with the "Feedback on the proof of concept" template.