docs(sdk-python): Sphinx + examples + changelog

.gitignore

@@ -11,3 +11,5 @@ build/
 venv/
 .pytest_cache/
 .mypy_cache/
+docs/_build/
+docs/_autosummary/

CHANGELOG.md

@@ -7,6 +7,28 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [2.1.0] — 2026-04-20
+
+### Added
+
+- **AccessManager**: implemented `verify_consent` and `revoke_consent`.
+- **Sphinx documentation**: autogenerated API reference (`docs/`, `sphinx-rtd-theme`).
+- **CONTRIBUTING.md**: local setup, testing, linting, examples, PR guidelines.
+- **Examples**: split `full_flow.py` into four focused, runnable examples:
+  - `examples/01_create_beo.py`
+  - `examples/02_grant_consent.py`
+  - `examples/03_submit_biorecord.py`
+  - `examples/04_destroy_beo.py`
+- New optional extras: `pip install -e ".[docs]"` and `pip install -e ".[dev]"`.
+
+### Security
+
+- Force `ecdsa>=0.19.2` via uv override to patch CVE-2026-33936.
+
+### Infrastructure
+
+- CodeQL and Dependabot workflows added to the repository.
+
 ## [1.0.0] — 2026-03-24
 
 ### Added

CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to BSP Python SDK
+
+Thanks for your interest in contributing to the Biological Sovereignty Protocol Python SDK.
+
+## Prerequisites
+
+- Python `>=3.10`
+- Git
+- (Optional) [uv](https://github.com/astral-sh/uv) for fast env management
+
+## Local setup (venv + pip)
+
+```bash
+git clone https://github.com/Biological-Sovereignty-Protocol/bsp-sdk-python.git
+cd bsp-sdk-python
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Local setup (uv — recommended)
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev,docs]"
+```
+
+The `uv` path automatically applies the `ecdsa>=0.19.2` override defined in `pyproject.toml` (see `SECURITY.md` for context).
+
+## Run tests
+
+```bash
+pytest
+pytest --cov=bsp_sdk --cov-report=term-missing
+```
+
+## Lint & type-check
+
+```bash
+ruff check .
+mypy bsp_sdk
+```
+
+## Build documentation
+
+Install optional docs extras and build with Sphinx:
+
+```bash
+pip install -e ".[docs]"
+sphinx-build docs docs/_build
+```
+
+Then open `docs/_build/index.html`. The `_build/` folder is git-ignored.
+
+## Run examples
+
+Runnable examples live in `examples/`:
+
+```bash
+python examples/01_create_beo.py
+python examples/02_grant_consent.py
+python examples/03_submit_biorecord.py
+python examples/04_destroy_beo.py
+```
+
+Without `BSP_RELAYER_URL` set, examples run in simulated mode.
+
+## Code style
+
+- Ruff enforces formatting (line-length 100, target py310).
+- Public APIs must have type hints. The project is `mypy --strict` clean.
+- Google-style or NumPy-style docstrings on all public functions/classes (picked up by Sphinx Napoleon).
+- Names follow PEP 8: `snake_case` for functions/variables, `PascalCase` for classes.
+
+## Commit messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(access): add batch revoke API
+fix(crypto): validate Ed25519 signature length
+docs(sdk-python): expand BEOClient usage examples
+```
+
+## Pull requests
+
+1. Fork or branch from `main`: `git checkout -b feat/my-thing`.
+2. Add or update tests. New public functions must ship with coverage.
+3. Run `pytest && ruff check . && mypy bsp_sdk` locally before pushing.
+4. Update `CHANGELOG.md` under the `[Unreleased]` section.
+5. Open a PR against `main` with a clear summary and link to any related issue.
+6. Be responsive to review feedback.
+
+## Security
+
+Do **not** file public issues for security vulnerabilities. See `SECURITY.md` for private disclosure instructions.
+
+## License
+
+By contributing you agree that your contributions are licensed under the project's Apache-2.0 license.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal Sphinx Makefile
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help clean html
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean:
+	rm -rf "$(BUILDDIR)"
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

docs/conf.py

@@ -0,0 +1,66 @@
+# Sphinx configuration for bsp-sdk (Python)
+# Docs: https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from __future__ import annotations
+
+import os
+import sys
+from datetime import datetime
+
+# -- Path setup --------------------------------------------------------------
+
+sys.path.insert(0, os.path.abspath(".."))
+
+# -- Project information -----------------------------------------------------
+
+project = "BSP Python SDK"
+author = "Ambrósio Institute"
+copyright = f"{datetime.now().year}, {author}"
+
+# Read version from pyproject.toml without importing the package
+try:
+    import tomllib  # Python 3.11+
+except ImportError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore
+
+_pyproject = os.path.join(os.path.dirname(__file__), "..", "pyproject.toml")
+with open(_pyproject, "rb") as f:
+    release = tomllib.load(f)["project"]["version"]
+
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+
+autosummary_generate = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pydantic": ("https://docs.pydantic.dev/latest/", None),
+}
+
+# -- HTML output -------------------------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_title = f"{project} {release}"

docs/index.rst

@@ -0,0 +1,58 @@
+BSP Python SDK
+==============
+
+Official Python SDK for the **Biological Sovereignty Protocol** (BSP).
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install bsp-sdk
+
+Quick start
+-----------
+
+.. code-block:: python
+
+   from bsp_sdk import BSPClient
+   import os
+
+   client = BSPClient(
+       ieo_domain  = "fleury.bsp",
+       private_key = os.environ["BSP_IEO_PRIVATE_KEY"],
+       environment = "mainnet",
+   )
+
+See ``examples/`` in the source tree for runnable end-to-end flows.
+
+API reference
+-------------
+
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   bsp_sdk
+
+Modules
+-------
+
+.. toctree::
+   :maxdepth: 2
+
+   modules/client
+   modules/beo
+   modules/ieo
+   modules/biorecord
+   modules/access
+   modules/exchange
+   modules/crypto
+   modules/types
+
+Indices
+-------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/modules/access.rst

@@ -0,0 +1,7 @@
+Access / Consent
+================
+
+.. automodule:: bsp_sdk.access
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/modules/beo.rst

@@ -0,0 +1,7 @@
+BEO
+===
+
+.. automodule:: bsp_sdk.beo
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/modules/biorecord.rst

@@ -0,0 +1,7 @@
+BioRecord
+=========
+
+.. automodule:: bsp_sdk.biorecord
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/modules/client.rst

@@ -0,0 +1,7 @@
+BSPClient
+=========
+
+.. automodule:: bsp_sdk.client
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/modules/crypto.rst

@@ -0,0 +1,7 @@
+Crypto
+======
+
+.. automodule:: bsp_sdk.crypto
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/modules/exchange.rst

@@ -0,0 +1,7 @@
+Exchange
+========
+
+.. automodule:: bsp_sdk.exchange
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/modules/ieo.rst

@@ -0,0 +1,7 @@
+IEO
+===
+
+.. automodule:: bsp_sdk.ieo
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/modules/types.rst

@@ -0,0 +1,7 @@
+Types
+=====
+
+.. automodule:: bsp_sdk.types
+   :members:
+   :undoc-members:
+   :show-inheritance: