cf-web 0.1.0__tar.gz

cf_web-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: cf-web
+Version: 0.1.0
+Summary: Web-based GUI for Cogniflow with FastAPI backend and React frontend
+Requires-Python: >=3.10
+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.1
+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.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.
+
+## 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):
+
+```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`
+
+## 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
+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
+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).

cf_web-0.1.0/README.md

@@ -0,0 +1,154 @@
+# 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.
+
+## 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):
+
+```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`
+
+## 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
+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
+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).

cf_web-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=70"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cf-web"
+version = "0.1.0"
+description = "Web-based GUI for Cogniflow with FastAPI backend and React frontend"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.100,<1.0",
+    "uvicorn[standard]>=0.24,<1.0",
+    "pydantic>=2.0,<3.0",
+    "cf-ontology>=0.1",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.24,<0.25",
+    "httpx>=0.25,<1.0",
+]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.24,<0.25",
+    "httpx>=0.25,<1.0",
+]
+pipeline = [
+    "cf-pipeline-engine>=0.1",
+]
+
+[project.scripts]
+cogniflow-web = "cf_web.cli:main"
+
+[project.entry-points."cogniflow.cli"]
+web = "cf_web.cli:register_cli"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cf_web = ["static/*", "static/**/*"]

cf_web-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cf_web-0.1.0/src/cf_web/__init__.py

@@ -0,0 +1,5 @@
+"""Cogniflow web package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

cf_web-0.1.0/src/cf_web/api/__init__.py

@@ -0,0 +1 @@
+"""API package."""

cf_web-0.1.0/src/cf_web/api/routers/__init__.py

@@ -0,0 +1,3 @@
+"""API routers."""
+
+__all__ = ["health", "ontology", "packages", "pipelines", "resource_manager"]

cf_web-0.1.0/src/cf_web/api/routers/health.py

@@ -0,0 +1,13 @@
+"""Health endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/health")
+async def healthcheck() -> dict[str, str]:
+    """Return liveness status for API health probing."""
+    return {"status": "ok"}

cf_web-0.1.0/src/cf_web/api/routers/ontology.py

@@ -0,0 +1,90 @@
+"""Ontology endpoints."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+
+from cf_web.services.pipeline_creator_service import PipelineCreatorService
+from cf_web.services.ontology_explorer_service import OntologyExplorerService
+
+router = APIRouter()
+pipeline_creator_service = PipelineCreatorService()
+ontology_explorer_service = OntologyExplorerService()
+
+
+@router.get("/graph")
+async def get_graph() -> dict[str, object]:
+    """Return ontology explorer graph payload."""
+    return {"jsonld": ontology_explorer_service.get_graph()}
+
+
+@router.get("/dataset")
+async def get_dataset() -> dict[str, object]:
+    """Return ontology dataset payload."""
+    return {"jsonld": ontology_explorer_service.get_dataset()}
+
+
+@router.get("/steps")
+async def list_steps() -> dict[str, object]:
+    """List processing-step DTOs for pipeline creation."""
+    return {"steps": pipeline_creator_service.get_steps()}
+
+
+@router.get("/steps/{step_id}")
+async def get_step(step_id: str) -> dict[str, object]:
+    """Return one processing-step DTO by id or alias."""
+    step = pipeline_creator_service.get_step(step_id)
+    if not step:
+        raise HTTPException(status_code=404, detail="Step not found")
+    return {"step": step}
+
+
+@router.get("/step-builder-options")
+async def get_step_builder_options() -> dict[str, object]:
+    """Return ontology-derived dropdown options for the package creator step builder."""
+    return pipeline_creator_service.get_step_builder_options()
+
+
+@router.get("/dashboard")
+async def get_dashboard() -> dict[str, object]:
+    """Return ontology dashboard graph data."""
+    return {"graphs": ontology_explorer_service.get_dashboard_graphs()}
+
+
+@router.get("/datatypes")
+async def get_datatypes_graph() -> dict[str, object]:
+    """Return the virtual datatypes graph payload."""
+    return {"graph": ontology_explorer_service.get_datatypes_graph()}
+
+
+@router.get("/node-quads")
+async def get_node_quads(
+    node_id: str,
+    graph_id: Optional[str] = None,
+    aliases: Optional[str] = None,
+    limit: int = 200,
+) -> dict[str, object]:
+    """Return raw quads for one selected node id/alias."""
+    alias_items = [item for item in (aliases or "").split(",") if item]
+    return {
+        "quads": ontology_explorer_service.get_node_quads(
+            node_id=node_id,
+            graph_id=graph_id,
+            aliases=alias_items,
+            limit=limit,
+        )
+    }
+
+
+@router.get("/diagnostics")
+async def get_diagnostics() -> dict[str, object]:
+    """Return read-only diagnostics for ontology graph/quads quality checks."""
+    return ontology_explorer_service.get_diagnostics_report()
+
+
+@router.post("/diagnostics/run")
+async def run_diagnostics() -> dict[str, object]:
+    """Run comprehensive diagnostics across semantics DuckDB quad stores."""
+    return ontology_explorer_service.run_comprehensive_diagnostics()

cf_web-0.1.0/src/cf_web/api/routers/packages.py

@@ -0,0 +1,53 @@
+"""Package template endpoints."""
+
+from __future__ import annotations
+
+import base64
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from cf_web.services.package_template_service import (
+    PackageTemplateRequest,
+    PackageTemplateService,
+)
+
+router = APIRouter()
+service = PackageTemplateService()
+
+
+@router.post("/template")
+async def create_package_template(payload: PackageTemplateRequest) -> StreamingResponse:
+    """Generate a package template archive and return as a download."""
+    try:
+        result = service.create_template(payload)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    headers = {"Content-Disposition": f'attachment; filename="{result.filename}"'}
+    return StreamingResponse(
+        iter([result.content]),
+        media_type="application/zip",
+        headers=headers,
+    )
+
+
+@router.post("/template/build")
+async def build_package_template(payload: PackageTemplateRequest) -> dict[str, object]:
+    """Generate a package template and return zip payload plus validation report."""
+    try:
+        result = service.create_template(payload)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    return {
+        "filename": result.filename,
+        "zip_base64": base64.b64encode(result.content).decode("ascii"),
+        "validation_report": result.validation_report,
+        "generated_files": result.generated_files,
+        "generated_at_utc": result.generated_at_utc,
+    }

cf_web-0.1.0/src/cf_web/api/routers/pipelines.py

@@ -0,0 +1,75 @@
+"""Pipeline endpoints."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from cf_web.services.pipeline_service import PipelineService
+
+router = APIRouter()
+service = PipelineService()
+
+
+class SavePipelineRequest(BaseModel):
+    """Payload for saving a pipeline revision."""
+
+    pipeline_id: str = Field(min_length=1)
+    jsonld: dict[str, Any]
+    user: Optional[str] = None
+    message: Optional[str] = None
+
+
+class ValidatePipelineRequest(BaseModel):
+    """Payload for validating pipeline JSON-LD."""
+
+    jsonld: dict[str, Any]
+
+
+@router.get("/")
+async def list_pipelines() -> dict[str, list[dict[str, Any]]]:
+    """List stored pipelines with current revision metadata."""
+    return {"pipelines": service.list_pipelines()}
+
+
+@router.get("/{pipeline_id}")
+async def load_pipeline(pipeline_id: str, rev: Optional[int] = None) -> dict[str, object]:
+    """Load a pipeline by id, optionally for a specific revision."""
+    try:
+        jsonld = service.get_pipeline(pipeline_id, rev=rev)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    return {"pipeline_id": pipeline_id, "rev": rev, "jsonld": jsonld}
+
+
+@router.post("/save")
+async def save_pipeline(payload: SavePipelineRequest) -> dict[str, object]:
+    """Commit a pipeline revision to the pipeline store."""
+    try:
+        result = service.save_pipeline(
+            pipeline_id=payload.pipeline_id,
+            jsonld=payload.jsonld,
+            user=payload.user,
+            message=payload.message,
+        )
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return result
+
+
+@router.post("/validate")
+async def validate_pipeline(payload: ValidatePipelineRequest) -> dict[str, object]:
+    """Validate pipeline JSON-LD and return validation diagnostics."""
+    try:
+        result = service.validate_pipeline(payload.jsonld)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return result