evidentia-api 0.6.0__tar.gz

evidentia_api-0.6.0/.gitignore

@@ -0,0 +1,95 @@
+# v0.4.0 — frontend build output lands in the Python package's static
+# directory at wheel-assembly time via the hatchling build hook. The
+# .gitkeep file in static/ is tracked; everything else is regenerated.
+packages/evidentia-api/src/evidentia_api/static/assets/
+packages/evidentia-api/src/evidentia_api/static/index.html
+packages/evidentia-api/src/evidentia_api/static/*.js
+packages/evidentia-api/src/evidentia_api/static/*.css
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+# NB: `lib/` and `lib64/` above would otherwise also match
+# packages/evidentia-ui/src/lib/ (TypeScript utils). Scope to top-level
+# only — there's no real Python-venv lib/ we'd fail to ignore because
+# .venv/ and venv/ below cover that case.
+!packages/evidentia-ui/src/lib/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+# NOTE: uv.lock is committed for reproducible builds.
+# https://docs.astral.sh/uv/concepts/projects/sync/#locking-dependencies
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.cache
+coverage.xml
+*.cover
+.hypothesis/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Claude Code local state
+.claude/
+
+# Evidentia runtime — user project state (NOT bundled examples).
+# `.controlbridge/` and `/controlbridge.yaml` are kept ignored for the
+# lifetime of the shim (through v0.7.0) so legacy project workspaces
+# authored against v0.1.0 – v0.5.0 don't start leaking into git.
+.evidentia/
+.controlbridge/
+/evidentia.yaml
+/controlbridge.yaml
+*.local.yaml
+evidence/
+reports/
+risks/
+
+# Generated reports from examples (keep source files, ignore generated ones)
+examples/**/report.json
+examples/**/report.csv
+examples/**/report.md
+examples/**/report.oscal.json
+examples/**/risks.json

evidentia_api-0.6.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: evidentia-api
+Version: 0.6.0
+Summary: FastAPI REST server + bundled React web UI for Evidentia
+Project-URL: Homepage, https://github.com/allenfbyrd/evidentia
+Project-URL: Repository, https://github.com/allenfbyrd/evidentia
+Project-URL: Issues, https://github.com/allenfbyrd/evidentia/issues
+Project-URL: Changelog, https://github.com/allenfbyrd/evidentia/blob/main/CHANGELOG.md
+Author-email: Allen Byrd <allen@allenfbyrd.com>
+License-Expression: Apache-2.0
+Keywords: compliance,fastapi,grc,oscal,rest-api,web-ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: evidentia-ai<0.7.0,>=0.6.0
+Requires-Dist: evidentia-core<0.7.0,>=0.6.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sse-starlette>=2.1
+Requires-Dist: uvicorn[standard]>=0.30
+Description-Content-Type: text/markdown
+
+# evidentia-api
+
+FastAPI REST server and bundled React web UI for **Evidentia**, the open-source GRC tool.
+
+This package is not typically installed directly. The preferred way is via the `[gui]` extra on the meta-package:
+
+```bash
+uv tool install "evidentia[gui]"
+# or
+pip install "evidentia[gui]"
+```
+
+Then run:
+
+```bash
+evidentia serve
+# -> FastAPI + React UI at http://127.0.0.1:8000
+```
+
+## What's inside
+
+- **FastAPI app** (`evidentia_api.app:app`) — REST endpoints mirroring every CLI capability.
+- **SPA** — React/Vite/shadcn/ui frontend, bundled as static assets inside the wheel under `evidentia_api/static/`.
+- **SSE streaming** — long-running LLM calls (`risk generate`, `explain`) stream progress to the browser without blocking.
+
+## REST surface
+
+Every endpoint is typed with Pydantic models reused from `evidentia-core`. All endpoints bind to `127.0.0.1` by default; `--host 0.0.0.0` emits a security warning.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/health` | Health probe |
+| GET | `/api/version` | Evidentia version info |
+| GET | `/api/doctor` | Diagnostic summary |
+| POST | `/api/doctor/check-air-gap` | Air-gap validator |
+| GET | `/api/config` | Read `evidentia.yaml` |
+| PUT | `/api/config` | Write `evidentia.yaml` |
+| GET | `/api/frameworks` | List all 82 bundled catalogs |
+| GET | `/api/frameworks/{id}` | Framework detail |
+| GET | `/api/frameworks/{id}/controls/{control_id}` | Single control |
+| POST | `/api/gap/analyze` | Run GapAnalyzer, save to gap store |
+| GET | `/api/gap/reports` | List saved reports |
+| GET | `/api/gap/reports/{key}` | Load a saved report |
+| POST | `/api/gap/diff` | Compute diff between two reports |
+| POST | `/api/risk/generate` | SSE: per-gap risk statement generation |
+| POST | `/api/explain/{framework}/{control_id}` | Plain-English control explanation |
+| POST | `/api/init/wizard` | Generate starter YAML files |
+| GET | `/api/llm-status` | LLM provider configuration state |
+
+## Air-gapped mode
+
+Running `evidentia serve --offline` wires the air-gap guard into every `/api/*` call. LLM features gracefully degrade with a pointer to Ollama. See [`docs/air-gapped.md`](../../docs/air-gapped.md).
+
+## Development
+
+```bash
+# From the repo root:
+uv sync --all-packages
+cd packages/evidentia-ui && npm install && npm run dev  # Vite dev server at :5173
+# In another terminal:
+evidentia serve --dev  # FastAPI at :8000 proxies /api/* to itself, / to Vite :5173
+```
+
+## License
+
+Apache-2.0 — see [`LICENSE`](../../LICENSE).

evidentia_api-0.6.0/README.md

@@ -0,0 +1,66 @@
+# evidentia-api
+
+FastAPI REST server and bundled React web UI for **Evidentia**, the open-source GRC tool.
+
+This package is not typically installed directly. The preferred way is via the `[gui]` extra on the meta-package:
+
+```bash
+uv tool install "evidentia[gui]"
+# or
+pip install "evidentia[gui]"
+```
+
+Then run:
+
+```bash
+evidentia serve
+# -> FastAPI + React UI at http://127.0.0.1:8000
+```
+
+## What's inside
+
+- **FastAPI app** (`evidentia_api.app:app`) — REST endpoints mirroring every CLI capability.
+- **SPA** — React/Vite/shadcn/ui frontend, bundled as static assets inside the wheel under `evidentia_api/static/`.
+- **SSE streaming** — long-running LLM calls (`risk generate`, `explain`) stream progress to the browser without blocking.
+
+## REST surface
+
+Every endpoint is typed with Pydantic models reused from `evidentia-core`. All endpoints bind to `127.0.0.1` by default; `--host 0.0.0.0` emits a security warning.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/health` | Health probe |
+| GET | `/api/version` | Evidentia version info |
+| GET | `/api/doctor` | Diagnostic summary |
+| POST | `/api/doctor/check-air-gap` | Air-gap validator |
+| GET | `/api/config` | Read `evidentia.yaml` |
+| PUT | `/api/config` | Write `evidentia.yaml` |
+| GET | `/api/frameworks` | List all 82 bundled catalogs |
+| GET | `/api/frameworks/{id}` | Framework detail |
+| GET | `/api/frameworks/{id}/controls/{control_id}` | Single control |
+| POST | `/api/gap/analyze` | Run GapAnalyzer, save to gap store |
+| GET | `/api/gap/reports` | List saved reports |
+| GET | `/api/gap/reports/{key}` | Load a saved report |
+| POST | `/api/gap/diff` | Compute diff between two reports |
+| POST | `/api/risk/generate` | SSE: per-gap risk statement generation |
+| POST | `/api/explain/{framework}/{control_id}` | Plain-English control explanation |
+| POST | `/api/init/wizard` | Generate starter YAML files |
+| GET | `/api/llm-status` | LLM provider configuration state |
+
+## Air-gapped mode
+
+Running `evidentia serve --offline` wires the air-gap guard into every `/api/*` call. LLM features gracefully degrade with a pointer to Ollama. See [`docs/air-gapped.md`](../../docs/air-gapped.md).
+
+## Development
+
+```bash
+# From the repo root:
+uv sync --all-packages
+cd packages/evidentia-ui && npm install && npm run dev  # Vite dev server at :5173
+# In another terminal:
+evidentia serve --dev  # FastAPI at :8000 proxies /api/* to itself, / to Vite :5173
+```
+
+## License
+
+Apache-2.0 — see [`LICENSE`](../../LICENSE).

evidentia_api-0.6.0/hatch_build.py

@@ -0,0 +1,127 @@
+"""Hatchling build hook — bundle the Vite-built React SPA into the wheel.
+
+Runs before wheel packaging when ``uv build`` (or ``python -m build``) is
+invoked for the ``evidentia-api`` package:
+
+1. Checks if ``packages/evidentia-ui/dist/`` exists and is non-empty.
+2. If yes, copies ``dist/*`` into ``src/evidentia_api/static/``.
+3. If no, runs ``npm ci && npm run build`` in the UI directory to produce
+   ``dist/`` first, then copies. Gracefully skips with a warning if Node
+   isn't installed on the build machine — for Python-only contributors
+   who only touch backend code.
+
+The hook is a no-op on machines that set the ``EVIDENTIA_SKIP_FRONTEND_BUILD``
+environment variable — convenient for CI matrices that separate concerns
+between Python tests and frontend builds.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+logger = logging.getLogger("hatch.build.evidentia-api")
+
+# Paths are resolved relative to the evidentia-api package root at
+# build time. The UI sits one directory up.
+_PKG_ROOT = Path(__file__).parent
+_UI_DIR = (_PKG_ROOT.parent / "evidentia-ui").resolve()
+_UI_DIST = _UI_DIR / "dist"
+_STATIC_DEST = _PKG_ROOT / "src" / "evidentia_api" / "static"
+
+
+class FrontendBundleHook(BuildHookInterface):
+    """Copies the React SPA build output into the Python package tree."""
+
+    PLUGIN_NAME = "evidentia-frontend"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        """Invoked by hatchling before the wheel/sdist is assembled."""
+        del version, build_data  # unused
+
+        if os.environ.get("EVIDENTIA_SKIP_FRONTEND_BUILD"):
+            logger.info(
+                "EVIDENTIA_SKIP_FRONTEND_BUILD set; leaving static/ untouched."
+            )
+            return
+
+        if not _UI_DIR.is_dir():
+            logger.warning(
+                "Frontend dir %s not found; skipping static bundle. "
+                "The wheel will serve a dev-placeholder page.",
+                _UI_DIR,
+            )
+            return
+
+        # If the user hasn't run `npm run build` yet, try to do it now.
+        if (not _UI_DIST.is_dir() or not any(_UI_DIST.iterdir())) and not _try_npm_build():
+            # Node unavailable or build failed. Ship without the SPA.
+            logger.warning(
+                "Frontend build unavailable; static/ will remain empty. "
+                "The wheel will serve a dev-placeholder page."
+            )
+            return
+
+        self._copy_dist_to_static()
+
+    def _copy_dist_to_static(self) -> None:
+        """Sync ``dist/*`` -> ``static/``. Wipes stale assets first."""
+        _STATIC_DEST.mkdir(parents=True, exist_ok=True)
+
+        # Clear stale assets but keep the .gitkeep file so the directory
+        # is preserved even when fresh checkouts haven't built yet.
+        for item in _STATIC_DEST.iterdir():
+            if item.name == ".gitkeep":
+                continue
+            if item.is_file() or item.is_symlink():
+                item.unlink()
+            else:
+                shutil.rmtree(item)
+
+        for src in _UI_DIST.iterdir():
+            dest = _STATIC_DEST / src.name
+            if src.is_dir():
+                shutil.copytree(src, dest)
+            else:
+                shutil.copy2(src, dest)
+
+        logger.info("Copied frontend bundle from %s -> %s", _UI_DIST, _STATIC_DEST)
+
+
+def _try_npm_build() -> bool:
+    """Attempt ``npm install && npm run build`` in the UI dir. Return True on success.
+
+    Uses ``npm ci`` when ``package-lock.json`` already exists (faster + deterministic)
+    and falls back to ``npm install`` when it doesn't — this covers fresh checkouts
+    where the lockfile hasn't been committed yet.
+    """
+    npm = shutil.which("npm")
+    if npm is None:
+        logger.warning(
+            "`npm` not found on PATH; cannot auto-build frontend. "
+            "Install Node 20+ or run `npm install && npm run build` manually "
+            "in packages/evidentia-ui/ before `uv build`."
+        )
+        return False
+
+    lockfile = _UI_DIR / "package-lock.json"
+    install_cmd = (
+        [npm, "ci", "--no-audit", "--no-fund"]
+        if lockfile.is_file()
+        else [npm, "install", "--no-audit", "--no-fund"]
+    )
+
+    for cmd in (install_cmd, [npm, "run", "build"]):
+        logger.info("Running: %s (cwd=%s)", " ".join(cmd), _UI_DIR)
+        try:
+            subprocess.run(cmd, cwd=_UI_DIR, check=True)
+        except subprocess.CalledProcessError as e:
+            logger.error("Frontend build step failed: %s", e)
+            return False
+    return True

evidentia_api-0.6.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "evidentia-api"
+version = "0.6.0"
+description = "FastAPI REST server + bundled React web UI for Evidentia"
+readme = "README.md"
+authors = [{name = "Allen Byrd", email = "allen@allenfbyrd.com"}]
+license = "Apache-2.0"
+requires-python = ">=3.12"
+keywords = ["grc", "compliance", "fastapi", "web-ui", "oscal", "rest-api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Topic :: Security",
+    "Framework :: FastAPI",
+    "Typing :: Typed",
+]
+dependencies = [
+    "evidentia-core>=0.6.0,<0.7.0",
+    "evidentia-ai>=0.6.0,<0.7.0",
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "python-multipart>=0.0.9",
+    "sse-starlette>=2.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/allenfbyrd/evidentia"
+Repository = "https://github.com/allenfbyrd/evidentia"
+Issues = "https://github.com/allenfbyrd/evidentia/issues"
+Changelog = "https://github.com/allenfbyrd/evidentia/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/evidentia_api"]
+# The static/ subdirectory is populated at build time by the custom
+# hatchling build hook (hatch_build.py). The hook runs `npm run build`
+# in packages/evidentia-ui/ and copies dist/* into
+# src/evidentia_api/static/ before wheel assembly. Set the env var
+# EVIDENTIA_SKIP_FRONTEND_BUILD=1 to bypass the hook in Python-only
+# build environments.
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.uv.sources]
+evidentia-core = { workspace = true }
+evidentia-ai = { workspace = true }

evidentia_api-0.6.0/src/evidentia_api/__init__.py

@@ -0,0 +1,21 @@
+"""Evidentia API: FastAPI REST server + bundled React web UI.
+
+The FastAPI application is exposed as :data:`evidentia_api.app.app` and
+can be served directly with uvicorn:
+
+    uvicorn evidentia_api.app:app --host 127.0.0.1 --port 8000
+
+Typical users reach it via the CLI:
+
+    evidentia serve [--host HOST] [--port PORT] [--offline]
+
+which is a thin Typer wrapper around :func:`evidentia_api.cli.serve`.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("evidentia-api")
+except PackageNotFoundError:  # pragma: no cover — only hit in editable repos without install
+    __version__ = "0.0.0+unknown"