prisma-flow 0.1.1__py3-none-any.whl

prisma_flow-0.1.1.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: prisma-flow
+Version: 0.1.1
+Summary: Lightweight Python tools for generating PRISMA-style flow diagrams without system dependencies.
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: prisma,systematic-review,scoping-review,evidence-synthesis,literature-review,svg,python,open-science
+Author: Open Science Labs Incubator contributors
+Requires-Python: >=3.10,<4
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: png
+Provides-Extra: yaml
+Requires-Dist: douki (>=0.12.1) ; extra == "dev"
+Requires-Dist: makim (==1.29.0) ; extra == "dev"
+Requires-Dist: mypy (>=1.10) ; extra == "dev"
+Requires-Dist: pre-commit (>=3) ; extra == "dev"
+Requires-Dist: pydantic (>=2)
+Requires-Dist: pytest (>=8) ; extra == "dev"
+Requires-Dist: pytest-cov (>=5) ; extra == "dev"
+Requires-Dist: pyyaml (>=6) ; extra == "yaml"
+Requires-Dist: resvg (>=0.1.2) ; extra == "png"
+Requires-Dist: ruff (>=0.6) ; extra == "dev"
+Project-URL: Documentation, https://osl-incubator.github.io/prisma-flow/
+Project-URL: Homepage, https://github.com/osl-incubator/prisma-flow
+Project-URL: Issues, https://github.com/osl-incubator/prisma-flow/issues
+Project-URL: Repository, https://github.com/osl-incubator/prisma-flow
+Description-Content-Type: text/markdown
+
+# prisma-flow
+
+![CI](https://img.shields.io/github/actions/workflow/status/osl-incubator/prisma-flow/ci.yml?logo=github&label=CI)
+[![Python Versions](https://img.shields.io/pypi/pyversions/prisma-flow)](https://pypi.org/project/prisma-flow/)
+[![Package Version](https://img.shields.io/pypi/v/prisma-flow?color=blue)](https://pypi.org/project/prisma-flow/)
+![License](https://img.shields.io/pypi/l/prisma-flow?color=blue)
+
+`prisma-flow` is a lightweight Python package for generating PRISMA-style flow
+diagrams for evidence synthesis workflows.
+
+Unlike Graphviz-based tools, `prisma-flow` does not require system-level graph
+layout binaries. Unlike Mermaid-based tools, it does not require Node or Mermaid
+CLI. The default renderer is a pure-Python, template-based SVG generator.
+
+The project is designed for systematic reviews, scoping reviews, evidence
+syntheses, and literature review workflows.
+
+## Features
+
+- Pure-Python SVG rendering by default
+- Standalone HTML export
+- Mermaid text export without Mermaid CLI
+- JSON input/output in the base install
+- Optional YAML input/output via `prisma-flow[yaml]`
+- Optional PNG method that clearly reports the missing optional dependency
+- Python API and `prisma-flow` command-line interface
+- PRISMA count validation with errors and warnings
+
+## Installation
+
+```bash
+pip install prisma-flow
+```
+
+or:
+
+```bash
+uv add prisma-flow
+```
+
+Optional YAML support:
+
+```bash
+uv add "prisma-flow[yaml]"
+```
+
+Optional PNG support, when a supported backend is added:
+
+```bash
+uv add "prisma-flow[png]"
+```
+
+## Python API
+
+```python
+from prismaflow import PrismaFlow
+
+flow = PrismaFlow.new_review(
+    records_identified_databases=1240,
+    records_identified_registers=50,
+    records_removed_duplicates=210,
+    records_removed_automation=0,
+    records_removed_other=0,
+    records_screened=1080,
+    records_excluded=950,
+    reports_sought=130,
+    reports_not_retrieved=10,
+    reports_assessed=120,
+    reports_excluded={
+        "Wrong population": 30,
+        "Wrong intervention": 20,
+        "Wrong outcome": 15,
+        "Not primary research": 15,
+    },
+    studies_included=40,
+)
+
+report = flow.validate()
+print(report.format_text())
+
+flow.to_svg("prisma.svg")
+flow.to_html("prisma.html")
+flow.to_mermaid("prisma.mmd")
+flow.to_json("review.json")
+```
+
+## CLI usage
+
+Validate input data:
+
+```bash
+prisma-flow validate examples/basic_new_review.json
+```
+
+Render SVG:
+
+```bash
+prisma-flow render examples/basic_new_review.json -o prisma.svg
+```
+
+Render other base-install formats:
+
+```bash
+prisma-flow render examples/basic_new_review.json --format html -o prisma.html
+prisma-flow render examples/basic_new_review.json --format mermaid -o prisma.mmd
+```
+
+If validation fails, the CLI prints a report and exits with a non-zero status:
+
+```text
+Validation failed:
+- records_screened should equal identified records minus removed records. Expected: 1080 Found: 1090
+```
+
+## Data model
+
+The v0.1 implementation supports the PRISMA 2020 new-review databases/registers
+template:
+
+```python
+from prismaflow import (
+    EligibilityStage,
+    IdentificationStage,
+    IncludedStage,
+    PrismaFlow,
+    PrismaTemplate,
+    ScreeningStage,
+)
+
+flow = PrismaFlow(
+    template=PrismaTemplate.PRISMA_2020_NEW_DATABASES_REGISTERS,
+    identification=IdentificationStage(
+        records_identified_databases=1240,
+        records_identified_registers=50,
+    ),
+    screening=ScreeningStage(
+        records_removed_duplicates=210,
+        records_removed_automation=0,
+        records_removed_other=0,
+        records_screened=1080,
+        records_excluded=950,
+    ),
+    eligibility=EligibilityStage(
+        reports_sought=130,
+        reports_not_retrieved=10,
+        reports_assessed=120,
+        reports_excluded={"Wrong population": 30},
+    ),
+    included=IncludedStage(studies_included=40),
+)
+```
+
+## Dependency policy
+
+SVG, HTML, Mermaid, and JSON work with the base install. YAML is optional. PNG
+is intentionally optional and not implemented as a required renderer in v0.1.
+
+The package does **not** require Graphviz, Cairo, CairoSVG, Node, Mermaid CLI,
+Inkscape, Playwright, browser engines, Matplotlib, or Plotly.
+
+## Development
+
+```bash
+conda env create -f conda/dev.yaml
+conda activate prismaflow
+poetry config virtualenvs.create false
+poetry install --extras "dev yaml"
+```
+
+Run the same workflow through Makim:
+
+```bash
+makim tests.linter
+makim tests.unit
+makim package.build
+makim docs.build
+makim all.ci
+```
+
+## Documentation
+
+The documentation site is built with Quarto:
+
+```bash
+quarto render docs
+```
+
+Preview locally:
+
+```bash
+quarto preview docs
+```
+
+## License
+
+BSD-3-Clause.
+

prisma_flow-0.1.1.dist-info/RECORD

@@ -0,0 +1,28 @@
+prismaflow/__init__.py,sha256=899hbwyttDc5loJRvFGwzphxCKlmQMcOPN-TZdO4C2E,912
+prismaflow/cli.py,sha256=gQqb42DbN7nr-SAKVvAzW36wxgfB_2fVvUILmFgHv84,5778
+prismaflow/enums.py,sha256=OVrVv0viAyCe0yTw6c9HULmR1LeNASrsKD3Qzzyj27E,575
+prismaflow/exceptions.py,sha256=ErfXBgK7UXuzkz1Hfy0ckHhjLRH0RZNDsOMKiAQqYVs,541
+prismaflow/io/__init__.py,sha256=dEy96FtJNwnAp5sUw-NMBVXEKD84PaRRwxSDXMqBwRE,206
+prismaflow/io/json.py,sha256=A5yNY7FEXtCgRjehL7M7oOp7KJD3-dDcujWxwKW4lsc,1632
+prismaflow/io/yaml.py,sha256=QpK-uYr-AkjClW44EmfDBJzNrBlnOk1lShhc0waPn_s,3244
+prismaflow/layout/__init__.py,sha256=bpd8kq8lK3-4412XWb0R0Cr7BatyAY-lXpEpeg_xB1A,448
+prismaflow/layout/engine.py,sha256=T933eQCp4ugiIjFJNZtOpaYwwM_El0XR-ZlJqNmNB7Y,4026
+prismaflow/layout/geometry.py,sha256=igOLToIzG3aIj8Y48mn93tP5s4UcL_wueDwGYnPaJnM,3529
+prismaflow/layout/overlap.py,sha256=DFX6F2uUmEAp-VCjMffQI3s7Ynhda1jDiaFBb_tEGo4,1455
+prismaflow/layout/text.py,sha256=oIJ1WrWyBMKIrv0E2vQ1vA4gyrlVJ3EaUqklQLBOMPo,849
+prismaflow/models.py,sha256=rOggTlHZuvJo58JBQrZd-5wruLl-c7f0Y8-PXVivKf4,14839
+prismaflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+prismaflow/renderers/__init__.py,sha256=ssDxOwN30HbAwGo0iq6TnNMUQDQPFZCzrrmIVYUOqYo,317
+prismaflow/renderers/html.py,sha256=CUjYycp_5KdZsosQJSgFYTR6x9kvidhjZko3PK2nWlc,1391
+prismaflow/renderers/mermaid.py,sha256=s8A3fO_W4DMAsTvIFnvZzZYHACuxGTE7Zbj1qAIiKkQ,1949
+prismaflow/renderers/png.py,sha256=kLLU4P_AuLIIRT-Ehgbx8SS5whytQn1NnML6L6HhYA8,1052
+prismaflow/renderers/svg.py,sha256=msM8Mqlu1s3L_EpyMb6TraJpQxeRfMfCKQJBPI59mJk,7927
+prismaflow/templates/__init__.py,sha256=RLHizwx71HVJWPDrY0m-LOVdBFO9KBJhjnHzarfhhhE,223
+prismaflow/templates/base.py,sha256=L5INco9lgdbEd6STwbifM-tpZrl_2ITeXisOXvHI4ZE,598
+prismaflow/templates/prisma_2020_new.py,sha256=kkdeL2mJg7fsnwTzPUJUijfcDE65oPRM0vJwN6sHfUg,7218
+prismaflow/validation.py,sha256=f8qKNUqUQg3hvHNLWRDH8gBhOlombseE2fLMAw45mRQ,8225
+prisma_flow-0.1.1.dist-info/METADATA,sha256=bUTJn4d0oppiMzkfOkEQ8ADd_AKlxWAYCKfupdKYWGo,6397
+prisma_flow-0.1.1.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+prisma_flow-0.1.1.dist-info/entry_points.txt,sha256=TeiZqSlnbxszvNXeJ2BWhMAgTNSu0OvpUKdIwzrvcqw,51
+prisma_flow-0.1.1.dist-info/licenses/LICENSE,sha256=vY8jl7ZbJTe7b45QSxc7JAy_FC7eZnnOFI1xz70Ab68,1514
+prisma_flow-0.1.1.dist-info/RECORD,,

prisma_flow-0.1.1.dist-info/WHEEL

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

prisma_flow-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+prisma-flow=prismaflow.cli:main
+

prisma_flow-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Open Science Labs Incubator
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

prismaflow/__init__.py

@@ -0,0 +1,40 @@
+"""
+title: Lightweight PRISMA-style flow diagram generation.
+"""
+
+from prismaflow.enums import PrismaTemplate
+from prismaflow.exceptions import (
+    OptionalDependencyError,
+    PrismaFlowError,
+    PrismaValidationError,
+    TemplateNotSupportedError,
+)
+from prismaflow.models import (
+    EligibilityStage,
+    FlowMetadata,
+    IdentificationStage,
+    IncludedStage,
+    PrismaFlow,
+    ScreeningStage,
+)
+from prismaflow.validation import ValidationMessage, ValidationReport, validate_flow
+
+__version__ = "0.1.1"  # semantic-release
+
+__all__ = [
+    "EligibilityStage",
+    "FlowMetadata",
+    "IdentificationStage",
+    "IncludedStage",
+    "OptionalDependencyError",
+    "PrismaFlow",
+    "PrismaFlowError",
+    "PrismaTemplate",
+    "PrismaValidationError",
+    "ScreeningStage",
+    "TemplateNotSupportedError",
+    "ValidationMessage",
+    "ValidationReport",
+    "__version__",
+    "validate_flow",
+]

prismaflow/cli.py

@@ -0,0 +1,208 @@
+"""
+title: Command-line interface for prisma-flow.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from pydantic import ValidationError as PydanticValidationError
+
+from prismaflow.exceptions import OptionalDependencyError, PrismaFlowError
+from prismaflow.models import PrismaFlow
+
+RenderFormat = str
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """
+    title: Run the prisma-flow command-line interface.
+    parameters:
+      argv:
+        type: Sequence[str] | None
+        description: Value for argv.
+    returns:
+      type: int
+      description: Return value.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "validate":
+            return _validate_command(args)
+        if args.command == "render":
+            return _render_command(args)
+    except PydanticValidationError as exc:
+        print("Input model validation failed:", file=sys.stderr)
+        print(str(exc), file=sys.stderr)
+        return 2
+    except OptionalDependencyError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except PrismaFlowError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    parser.print_help(sys.stderr)
+    return 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """
+    title: Build the CLI argument parser.
+    returns:
+      type: argparse.ArgumentParser
+      description: Return value.
+    """
+    parser = argparse.ArgumentParser(
+        prog="prisma-flow",
+        description="Generate PRISMA-style flow diagrams without system dependencies.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate = subparsers.add_parser("validate", help="validate a PRISMA flow file")
+    validate.add_argument("input", help="input JSON/YAML file")
+    validate.add_argument(
+        "--strict-included",
+        action="store_true",
+        help="treat included-study reconciliation warnings as errors",
+    )
+
+    render = subparsers.add_parser("render", help="render a PRISMA flow file")
+    render.add_argument("input", help="input JSON/YAML file")
+    render.add_argument(
+        "-f",
+        "--format",
+        choices=["svg", "html", "mermaid", "png", "json", "yaml"],
+        help="output format; inferred from --output when omitted",
+    )
+    render.add_argument("-o", "--output", help="output path")
+    render.add_argument(
+        "--allow-invalid",
+        action="store_true",
+        help="render even when PRISMA count validation has errors",
+    )
+    return parser
+
+
+def _validate_command(args: argparse.Namespace) -> int:
+    """
+    title: _validate_command.
+    parameters:
+      args:
+        type: argparse.Namespace
+        description: Value for args.
+    returns:
+      type: int
+      description: Return value.
+    """
+    flow = _load_flow(args.input)
+    report = flow.validate(strict_included=args.strict_included)
+    print(report.format_text())
+    return 0 if report.ok else 1
+
+
+def _render_command(args: argparse.Namespace) -> int:
+    """
+    title: _render_command.
+    parameters:
+      args:
+        type: argparse.Namespace
+        description: Value for args.
+    returns:
+      type: int
+      description: Return value.
+    """
+    flow = _load_flow(args.input)
+    report = flow.validate()
+    if report.has_errors and not args.allow_invalid:
+        print(report.format_text(), file=sys.stderr)
+        return 1
+    if report.has_warnings:
+        print(report.format_text(), file=sys.stderr)
+
+    output_format = args.format or _infer_format(args.output)
+    rendered = _render(flow, output_format, args.output)
+    if args.output is None and isinstance(rendered, str):
+        print(rendered, end="")
+    return 0
+
+
+def _load_flow(path: str | Path) -> PrismaFlow:
+    """
+    title: _load_flow.
+    parameters:
+      path:
+        type: str | Path
+        description: Value for path.
+    returns:
+      type: PrismaFlow
+      description: Return value.
+    """
+    suffix = Path(path).suffix.lower()
+    if suffix in {".yaml", ".yml"}:
+        return PrismaFlow.from_yaml(path)
+    return PrismaFlow.from_json(path)
+
+
+def _infer_format(output: str | None) -> RenderFormat:
+    """
+    title: _infer_format.
+    parameters:
+      output:
+        type: str | None
+        description: Value for output.
+    returns:
+      type: RenderFormat
+      description: Return value.
+    """
+    if not output:
+        return "svg"
+    suffix = Path(output).suffix.lower().lstrip(".")
+    if suffix == "mmd":
+        return "mermaid"
+    if suffix in {"svg", "html", "png", "json", "yaml", "yml"}:
+        return "yaml" if suffix == "yml" else suffix
+    return "svg"
+
+
+def _render(
+    flow: PrismaFlow,
+    output_format: RenderFormat,
+    output: str | None,
+) -> str | bytes:
+    """
+    title: _render.
+    parameters:
+      flow:
+        type: PrismaFlow
+        description: Value for flow.
+      output_format:
+        type: RenderFormat
+        description: Value for output_format.
+      output:
+        type: str | None
+        description: Value for output.
+    returns:
+      type: str | bytes
+      description: Return value.
+    """
+    if output_format == "svg":
+        return flow.to_svg(output)
+    if output_format == "html":
+        return flow.to_html(output)
+    if output_format == "mermaid":
+        return flow.to_mermaid(output)
+    if output_format == "png":
+        return flow.to_png(output)
+    if output_format == "json":
+        return flow.to_json(output)
+    if output_format == "yaml":
+        return flow.to_yaml(output)
+    raise PrismaFlowError(f"Unsupported output format: {output_format}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

prismaflow/enums.py

@@ -0,0 +1,20 @@
+"""
+title: Enumerations used by prisma-flow.
+"""
+
+from enum import Enum
+
+
+class PrismaTemplate(str, Enum):
+    """
+    title: Supported and planned PRISMA diagram templates.
+    """
+
+    PRISMA_2020_NEW_DATABASES_REGISTERS = "prisma_2020_new_databases_registers"
+    PRISMA_2020_NEW_DATABASES_REGISTERS_OTHER = (
+        "prisma_2020_new_databases_registers_other"
+    )
+    PRISMA_2020_UPDATED_DATABASES_REGISTERS = "prisma_2020_updated_databases_registers"
+    PRISMA_2020_UPDATED_DATABASES_REGISTERS_OTHER = (
+        "prisma_2020_updated_databases_registers_other"
+    )

prismaflow/exceptions.py

@@ -0,0 +1,27 @@
+"""
+title: Exceptions raised by prisma-flow.
+"""
+
+
+class PrismaFlowError(Exception):
+    """
+    title: Base exception for prisma-flow errors.
+    """
+
+
+class TemplateNotSupportedError(PrismaFlowError):
+    """
+    title: Raised when a requested PRISMA template is not implemented.
+    """
+
+
+class OptionalDependencyError(PrismaFlowError):
+    """
+    title: Raised when an optional export backend is not installed.
+    """
+
+
+class PrismaValidationError(PrismaFlowError):
+    """
+    title: Raised when a flow has validation errors.
+    """

prismaflow/io/__init__.py

@@ -0,0 +1,8 @@
+"""
+title: Input/output helpers.
+"""
+
+from prismaflow.io.json import dump_json, load_json
+from prismaflow.io.yaml import dump_yaml, load_yaml
+
+__all__ = ["dump_json", "dump_yaml", "load_json", "load_yaml"]

prismaflow/io/json.py

@@ -0,0 +1,64 @@
+"""
+title: JSON input/output helpers.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from prismaflow.models import PrismaFlow
+
+
+def load_json(source: str | Path) -> PrismaFlow:
+    """
+    title: Load a PrismaFlow model from a JSON file path or JSON string.
+    parameters:
+      source:
+        type: str | Path
+        description: Value for source.
+    returns:
+      type: PrismaFlow
+      description: Return value.
+    """
+    if isinstance(source, Path) or _looks_like_path(source):
+        path = Path(source)
+        if path.exists():
+            return PrismaFlow.model_validate_json(path.read_text(encoding="utf-8"))
+    return PrismaFlow.model_validate_json(str(source))
+
+
+def dump_json(flow: PrismaFlow, path: str | Path | None = None) -> str:
+    """
+    title: Serialize a flow to JSON and optionally write it.
+    parameters:
+      flow:
+        type: PrismaFlow
+        description: Value for flow.
+      path:
+        type: str | Path | None
+        description: Value for path.
+    returns:
+      type: str
+      description: Return value.
+    """
+    output = flow.model_dump_json(indent=2)
+    if path is not None:
+        Path(path).write_text(output + "\n", encoding="utf-8")
+    return output
+
+
+def _looks_like_path(source: str | Path) -> bool:
+    """
+    title: _looks_like_path.
+    parameters:
+      source:
+        type: str | Path
+        description: Value for source.
+    returns:
+      type: bool
+      description: Return value.
+    """
+    if isinstance(source, Path):
+        return True
+    text = str(source)
+    return text.endswith(".json") or "/" in text or "\\" in text