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

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