Metadata-Version: 2.4
Name: controlbridge-api
Version: 0.4.1
Summary: FastAPI REST server + bundled React web UI for ControlBridge
Project-URL: Homepage, https://github.com/allenfbyrd/controlbridge
Project-URL: Repository, https://github.com/allenfbyrd/controlbridge
Project-URL: Issues, https://github.com/allenfbyrd/controlbridge/issues
Project-URL: Changelog, https://github.com/allenfbyrd/controlbridge/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: controlbridge-ai<0.5.0,>=0.4.0
Requires-Dist: controlbridge-core<0.5.0,>=0.4.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

# controlbridge-api

FastAPI REST server and bundled React web UI for **ControlBridge**, 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 "controlbridge[gui]"
# or
pip install "controlbridge[gui]"
```

Then run:

```bash
controlbridge serve
# -> FastAPI + React UI at http://127.0.0.1:8000
```

## What's inside

- **FastAPI app** (`controlbridge_api.app:app`) — REST endpoints mirroring every CLI capability.
- **SPA** — React/Vite/shadcn/ui frontend, bundled as static assets inside the wheel under `controlbridge_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 `controlbridge-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` | ControlBridge version info |
| GET | `/api/doctor` | Diagnostic summary |
| POST | `/api/doctor/check-air-gap` | Air-gap validator |
| GET | `/api/config` | Read `controlbridge.yaml` |
| PUT | `/api/config` | Write `controlbridge.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 `controlbridge 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/controlbridge-ui && npm install && npm run dev  # Vite dev server at :5173
# In another terminal:
controlbridge serve --dev  # FastAPI at :8000 proxies /api/* to itself, / to Vite :5173
```

## License

Apache-2.0 — see [`LICENSE`](../../LICENSE).
