cf-web 0.2.2

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.

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

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

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.

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

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