Metadata-Version: 2.4
Name: cf-web
Version: 0.2.6
Summary: Web-based GUI for Cogniflow with FastAPI backend and React frontend
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1.0,>=0.100
Requires-Dist: uvicorn[standard]<1.0,>=0.24
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: rdflib<8.0,>=7.4
Requires-Dist: pyshacl<0.30,>=0.25
Requires-Dist: cf-service-contracts>=0.1.0
Provides-Extra: test
Requires-Dist: pytest<9.0,>=8.0; extra == "test"
Requires-Dist: pytest-asyncio<0.25,>=0.24; extra == "test"
Requires-Dist: httpx<1.0,>=0.25; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio<0.25,>=0.24; extra == "dev"
Requires-Dist: httpx<1.0,>=0.25; extra == "dev"

# CogniFlow Web

`cf_web` is the web application package for CogniFlow. It provides:

- a FastAPI backend (`src/cf_web`) exposing ontology/pipeline APIs
- a React + TypeScript frontend (`frontend`) for ontology exploration and pipeline editing
- a CLI entrypoint (`cogniflow-web`) to launch the app

Published distribution name:

```bash
pip install cf-web
```

Installed launcher surface:

```powershell
cogniflow-web
```

The backend reads semantics through `cf-semantics-runtime` over the semantics-store contract boundary.
The active explorer and validation path is dataset-first: persisted quads -> RDFLib `Dataset`/`Graph` views -> API payloads, with raw RDF transport exposed as N-Quads.

## Architecture

- Backend framework: FastAPI + Uvicorn
- Frontend framework: React + Vite
- Semantics source: `cf_semantics_runtime` provider contract (quads-backed)
- Service split:
  - `ontology_explorer_service.py` for ontology explorer payloads
  - `pipeline_creator_service.py` for step DTOs used by the editor
  - `pipeline_service.py` for pipeline list/load/save/validate operations
  - Explorer dashboard and backend SHACL validation read dataset/graph views directly; maintained raw RDF payloads are N-Quads.

## Install

From repository root (recommended in a virtual environment):

```powershell
python -m pip install -e "sandcastle/cf_web[test]"
```

Install with pipeline runtime support:

```powershell
python -m pip install -e "sandcastle/cf_web[test,pipeline]"
```

If you want frontend production assets served by FastAPI, build the frontend first:

```powershell
.\scripts\build_cf_web_frontend.ps1
```

## Run

### Option 1: direct app launcher

```powershell
cogniflow-web
```

Disable browser auto-open:

```powershell
cogniflow-web --no-browser
```

### Option 2: unified CLI

```powershell
cf web start
```

or

```powershell
cf web start --no-browser
```

## Backend API

Key routes:

- `GET /api/health`
- `GET /api/ontology/graph`
- `GET /api/ontology/dataset`
- `GET /api/ontology/dashboard`
- `GET /api/semantics/steps`
- `GET /api/semantics/steps/{step_id}`
- `GET /api/pipelines/`
- `GET /api/pipelines/{pipeline_id}?rev={n}`
- `POST /api/pipelines/save`
- `POST /api/pipelines/validate`

Pipeline transport is N-Quads-first:

- `GET /api/pipelines/{pipeline_id}` returns `{ pipeline_id, rev, pipeline_nquads }`
- `POST /api/pipelines/save` accepts `{ pipeline_id, pipeline_nquads, ... }`
- `POST /api/pipelines/validate` accepts `{ pipeline_nquads }`

Raw ontology exports return `{ nquads }`. `GET /api/ontology/graph` and `GET /api/ontology/dataset` intentionally expose the same maintained N-Quads export because the web surface no longer depends on a synthetic JSON-LD graph-vs-dataset distinction.

Step and ontology-explorer payloads consume standardized metadata contracts from the registered semantics/runtime providers.
The canonical documentation fields are:
- `skos:prefLabel`
- `skos:definition`
- `skos:scopeNote`
- `skos:example`

When present, the UI also preserves a bounded adaptive SKOS surface for search and detail display:
- `skos:altLabel`
- `skos:notation`
- `skos:inScheme`
- `skos:broader`
- `skos:narrower`
- `skos:related`

Frontend code should consume this normalized service-layer contract and must not parse raw RDF in the browser.

## Configuration

`cf_web` reads these environment variables:

- `CF_WEB_HOST` (default: `127.0.0.1`)
- `CF_WEB_PORT` (default: `8000`)
- `CF_WEB_RELOAD` (`1` enables reload, default: `0`)
- `CF_WEB_DEBUG` (`1` enables debug flag, default: `0`)
- Workspace root: `~/.cogniflow/workspace`
- Semantics root: `~/.cogniflow/workspace/semantics`

By default the launcher sets:

- `CF_ENABLE_STEP_PACKAGES=1`

so installed step packages are ingested/discovered for UI usage.

## Development Notes

- Frontend source of truth is under `frontend/src`.
- Built frontend files are emitted to `src/cf_web/static` by Vite.
- The publish workflow packages the checked-in `src/cf_web/static` bundle and does not run a frontend build step.
- Backend services use a shared `OntologyManager` provider (`manager_provider.py`) to avoid repeated manager instantiation.
- The pipeline editor keeps live backend validation enabled with a 450 ms debounce in `PipelineEditorPage.tsx`.
- Local `.nq` import/export happens in the browser via `frontend/src/utils/nquads.ts` and `n3`.

## Publishing

`cf_web` is published with the dedicated Windows workflow:

- Workflow: `.github/workflows/cf_web_windows_publish.yml`
- Package directory: `sandcastle/cf_web`
- Published distribution: `cf-web`
- PyPI tag: `cf-web-v<version>`
- TestPyPI tag: `cf-web-v<version>-test`

Local preflight:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/mimic_windows_python_publish_workflow.ps1 `
  -WorkflowFile .github/workflows/cf_web_windows_publish.yml `
  -PackageDir sandcastle/cf_web `
  -PythonExe py `
  -PythonVersion 3.14
```

Queue a dry-run dispatch:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/queue_windows_python_publish_workflow.ps1 `
  -WorkflowFile .github/workflows/cf_web_windows_publish.yml `
  -PackageDir sandcastle/cf_web `
  -PublishTarget testpypi `
  -Ref main `
  -RequireLocalPass `
  -DryRun
```

## Troubleshooting

- `GET /favicon.ico 404`: ensure favicon exists in `src/cf_web/static/favicon.ico` and frontend was rebuilt.
- App opens but says frontend build missing: run `.\scripts\build_cf_web_frontend.ps1`.
- No steps visible in UI: ensure step packages are installed and `CF_ENABLE_STEP_PACKAGES=1` (default via launcher).

