diff --git a/core/python/cloaked-ai/.gitignore b/core/python/cloaked-ai/.gitignore new file mode 100644 index 0000000..1320f90 --- /dev/null +++ b/core/python/cloaked-ai/.gitignore @@ -0,0 +1 @@ +site diff --git a/core/python/cloaked-ai/.readthedocs.yaml b/core/python/cloaked-ai/.readthedocs.yaml new file mode 100644 index 0000000..ec7b816 --- /dev/null +++ b/core/python/cloaked-ai/.readthedocs.yaml @@ -0,0 +1,18 @@ +# Read the Docs configuration file for MkDocs projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.10" + commands: + # install rust. If we automate/otherwise committing the generated python module we can avoid rust at all and + # only would need to install hatch here. Doc builds would then be a few seconds instead of a few minutes. + - ./core/python/cloaked-ai/rust-toolchain-from-file.sh + - ~/.cargo/bin/cargo b --release + - ~/.cargo/bin/cargo run --bin uniffi-bindgen generate --library ./target/release/libcloaked_ai.so --language python --out-dir core/python/cloaked-ai/cloaked_ai + # actual doc building part + - pip install -v "hatch==1.7.0" + - cd core/python/cloaked-ai && hatch run docs:build --site-dir $READTHEDOCS_OUTPUT/html + + diff --git a/core/python/cloaked-ai/RELEASING.md b/core/python/cloaked-ai/RELEASING.md index 99fc455..fe2f0f3 100644 --- a/core/python/cloaked-ai/RELEASING.md +++ b/core/python/cloaked-ai/RELEASING.md @@ -25,11 +25,15 @@ Once you have a built environment, some common `hatch` commands you may want to ```console hatch build -t wheel # to produce .whl file for release hatch shell # to get a local pyenv with the sdk installed -hatch run test # to run unit tests +hatch run test:test # to run unit tests ``` > Note: the generate step needs debug symbols to work on Linux, don't strip them before running it (they can be stripped afterwards) +## Documentation + +Docs can be previewed with `hatch run docs:serve`, or manually built with `hatch run docs:build`. They'll be automatically built and uploaded by our [readthedocs](https://readthedocs.com) integration. + ## Release ### Manual diff --git a/core/python/cloaked-ai/docs/api-reference.md b/core/python/cloaked-ai/docs/api-reference.md new file mode 100644 index 0000000..de8a40f --- /dev/null +++ b/core/python/cloaked-ai/docs/api-reference.md @@ -0,0 +1,50 @@ +# API Reference + +`CloakedAiError` documentation is not correctly generated. Its definition is included here manually: + +```python +class CloakedAiError(Exception): + """ + Errors related to CloakedAiStandalone + """ + class InvalidConfiguration(CloakedAiError): + """ + Error while loading configuration. + """ + class InvalidKey(CloakedAiError): + """ + Error with key used to initialize CloakedAiStandalone + """ + class InvalidIv(CloakedAiError): + """ + Error during decryption with provided IV + """ + class InvalidAuthHash(CloakedAiError): + """ + Error during decryption with provided authentication hash + """ + class InvalidInput(CloakedAiError): + """ + Error with input vector. Likely due to overflow with large values + """ + class DocumentError(CloakedAiError): + """ + Error when encrypting or decrypting documents + """ + class ProtobufError(CloakedAiError): + """ + Error when parsing encryption headers/metadata + """ + class TenantSecurityError(CloakedAiError): + """ + Error with requests to TSC + """ + class IronCoreDocumentsError(CloakedAiError): + """ + Error with IronCore Documents + """ +``` + +Keep in mind that this manual definition may get out of step with the actual source, and refer to the source if there is any ambiguity. + +::: cloaked_ai.cloaked_ai diff --git a/core/python/cloaked-ai/docs/index.md b/core/python/cloaked-ai/docs/index.md new file mode 100644 index 0000000..1affb4a --- /dev/null +++ b/core/python/cloaked-ai/docs/index.md @@ -0,0 +1,14 @@ +# Home + +This is documentation for the Python API surface. For higher level documentation visit [docs.ironcorelabs.com](https://docs.ironcorelabs.com). + +## Installation + +```toml title="pyproject.toml" +# PEP 621 dependencies declaration +# adapt to your dependencies manager +[project] +dependencies = [ + "ironcore-alloy" +] +``` diff --git a/core/python/cloaked-ai/docs/stylesheets/extra.css b/core/python/cloaked-ai/docs/stylesheets/extra.css new file mode 100644 index 0000000..c68f71e --- /dev/null +++ b/core/python/cloaked-ai/docs/stylesheets/extra.css @@ -0,0 +1,6 @@ +:root { + --md-primary-fg-color: rgb(15, 23, 42); + --md-primary-bg-color: white; + --md-accent-fg-color: rgb(251, 1, 0); + --md-accent-bg-color: rgb(209, 213, 219); +} \ No newline at end of file diff --git a/core/python/cloaked-ai/mkdocs.yml b/core/python/cloaked-ai/mkdocs.yml new file mode 100644 index 0000000..cebd427 --- /dev/null +++ b/core/python/cloaked-ai/mkdocs.yml @@ -0,0 +1,46 @@ +site_name: IronCore Labs Alloy SDK +theme: + name: material + features: + - navigation.tabs + - navigation.sections + - toc.integrate + - navigation.top + - search.suggest + - search.highlight + - content.tabs.link + - content.code.annotation + - content.code.copy + language: en + palette: + # https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss + - scheme: default + primary: custom +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences +plugins: +- search +- mkdocstrings: + default_handler: python + handlers: + python: + options: + show_if_no_docstring: true + merge_init_into_class: true + docstring_section_style: list + docstring_style: numpy + show_category_heading: true + show_root_heading: true + show_root_toc_entry: false + filters: + - "!^_" +extra_css: + - stylesheets/extra.css +copyright: | + © 2023 IronCore Labs, Inc. diff --git a/core/python/cloaked-ai/pyproject.toml b/core/python/cloaked-ai/pyproject.toml index 5f8d0bd..306f1a5 100644 --- a/core/python/cloaked-ai/pyproject.toml +++ b/core/python/cloaked-ai/pyproject.toml @@ -37,10 +37,24 @@ artifacts = ["*.so", "*.dylib"] [tool.hatch.build.targets.wheel.hooks.custom] [tool.hatch.envs.default] -dependencies = ["pytest", "pytest-cov", "pytest-metadata"] python = "3.10" -[tool.hatch.envs.default.scripts] +[tool.hatch.envs.docs] +dependencies = ["mkdocs.material==9.4.8", "mkdocstrings-python==1.7.4"] + +[tool.hatch.envs.docs.scripts] +build = "mkdocs build --clean --strict {args}" +serve = "mkdocs serve --dev-addr localhost:8000 {args}" + +[tool.hatch.envs.test] +dependencies = [ + "pytest==7.4.2", + "pytest-cov==4.1.0", + "pytest-metadata==3.0.0", + "pytest-asyncio==0.21.1", +] + +[tool.hatch.envs.test.scripts] coverage = "pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=cloaked_ai --cov=tests {args}" test = "coverage --no-cov {args}" diff --git a/core/python/cloaked-ai/rust-toolchain-from-file.sh b/core/python/cloaked-ai/rust-toolchain-from-file.sh new file mode 100755 index 0000000..55da73d --- /dev/null +++ b/core/python/cloaked-ai/rust-toolchain-from-file.sh @@ -0,0 +1,26 @@ +#! /usr/bin/env bash +# Used by readthedocs to get the right version of rust installed. Based on our github action that does the same. +# install and source rustup +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none +source "$HOME/.cargo/env" +# download a jq binary and add it somewhere on the path we can write to, install other dependencies +curl -s -L -o /home/docs/.cargo/bin/jq https://github.com/jqlang/jq/releases/download/jq-1.7/jq-linux-amd64 && chmod +x "$HOME"/.cargo/bin/jq +pip install yq tomlq +# pull the rust-toolchain.toml info +for F in rust-toolchain.toml rust-toolchain ; do + if [ -f "$F" ] ; then + TOML_FILE="$F" + break + fi +done +if [ -z "$TOML_FILE" ]; then + echo "rust-toolchain{.toml} not found, expecting explicit inputs" + exit 0 +fi +TOML_TOOLCHAIN=$(tomlq -r '.toolchain.channel | select(. != null)' "$TOML_FILE") +TOML_TARGETS=$(tomlq -r '.toolchain.targets | select(. != null) | @csv' "$TOML_FILE") +TOML_COMPONENTS=$(tomlq -r '.toolchain.components | select(. != null) | @csv' "$TOML_FILE") +# install what we found +rustup toolchain install "$TOML_TOOLCHAIN""$TOML_TARGETS""$TOML_COMPONENTS" --profile minimal --no-self-update +rustup default "$TOML_TOOLCHAIN" +rustup override set "$TOML_TOOLCHAIN"