Metadata-Version: 2.4
Name: cf-web
Version: 0.2.4
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: cf-ontology>=0.2.3
Requires-Dist: cf-pipeline-creator>=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"
Provides-Extra: pipeline
Requires-Dist: cf-pipeline-engine>=0.2.1; extra == "pipeline"

# 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_ontology` and its DuckDB quads stores.
The active explorer and validation path is dataset-first: DuckDB 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_ontology.OntologyManager` (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/ontology/steps`
- `GET /api/ontology/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.

## 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`)
- `CF_WORKSPACE_DIR` (default: `~/.cogniflow/workspace`)
- `CF_SEMANTICS_DIR` (default: `<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`; the backend no longer exposes pipeline parse/serialize adapter endpoints.

## 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).

