cf-web 0.2.4

Web-based GUI for Cogniflow with FastAPI backend and React frontend

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:

pip install cf-web

Installed launcher surface:

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):

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

Install with pipeline runtime support:

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

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

.\scripts\build_cf_web_frontend.ps1

Run

Option 1: direct app launcher

cogniflow-web

Disable browser auto-open:

cogniflow-web --no-browser

Option 2: unified CLI

cf web start

or

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