Metadata-Version: 2.4
Name: cf-ontology
Version: 0.2.7
Summary: CogniFlow ontology definitions and utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: rdflib<8.0,>=7.4
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: cf-service-contracts>=0.1.0
Requires-Dist: pyshacl<0.30,>=0.25
Provides-Extra: test
Requires-Dist: pytest<9.0,>=8.0; extra == "test"

# CogniFlow Ontology

`cf_ontology` is a data-only package whose maintained output is the packaged
ontology N-Quads resources under `src/cf_ontology/ontology/**` plus the minimal
package metadata needed to ship them.

Active semantics behavior is owned by `cf_semantics_runtime`. That package
consumes the packaged ontology N-Quads, discovers installed step packages,
and writes the active ontology and step views into the semantics store
through service contracts.

Semantics are authored as RDF documents:
- ontology fragments
- step packages
- pipelines

## Ownership

This package no longer owns the active runtime surface.

- `cf_semantics_runtime` is the maintained contract-backed runtime for
  snapshots, validation, and step-package discovery.
- `cf_semantics_store` owns the workspace-local RDF semantics store.
- New integrations should not add direct `cf_ontology` runtime dependencies.

## Storage (Semantics Store)

The default RDF semantics store remains under `~/.cogniflow/workspace/semantics`,
but the maintained runtime behavior is resolved through `ProviderKey.SEMANTICS_STORE`
and the `cf_semantics_runtime` contracts.

- Pipeline runtime state is handled separately by `cf_pipeline_manager`.
- Step packages are discovered and materialized by `cf_semantics_runtime`, not by
  `cf_ontology` directly.

## Graph IDs (binding conventions)

### Step packages

- Split steps (`split_steps=True`): `g = "pkg:{package_name}@{package_version}#{step_id}"`
- Unsplit: `g = "pkg:{package_name}@{package_version}"`

`package_name` is the StepPackage id (from `cf:packageId` in `steps.nq`).

Package upgrades generate new graph ids (the version is part of `g`). Existing graphs are not deleted; missing/uninstalled packages are marked inactive via `graphs.is_active=false`.

### Pipelines (versioned)

- Stable pipeline identifier: `pipeline_id` (UUID or user-provided stable id)
- Revision graph: `g = "pipe:{pipeline_id}@{rev}"` with monotonically increasing `rev` starting at `1`
- "Current" is a pointer in the `pipelines` table (no separate quad graph)

## What is included

- Packaged N-Quads fragments: `ontology/core/*.nq`, `ontology/foundations/contracts/*.nq`, `ontology/vocab/*.nq`, and `ontology/shapes/*.nq`.
- Packaged ontology resources consumed by `cf_semantics_runtime`.
- Step-package manifests and other RDF assets that are ingested through the runtime contracts.

## Installation

From the `sandcastle/cf_ontology` directory:

```bash
pip install .
```

Published distribution name:

```bash
pip install cf-ontology
```

Optional (for unified `cf` CLI integration):

```bash
pip install -e ../cf_core_cli
```

## Usage

**Policy:** all reads and writes to the semantics store must go through the
`cf_semantics_runtime` and `cf_semantics_store` service-contract boundary.
Do not access `cf-*.store.db` files directly from other packages.

## Data-only runtime ownership

`cf_ontology` does not own the active runtime APIs, installers, or pipeline
revision machinery.

- `cf_semantics_runtime` ingests packaged ontology and step-package N-Quads,
  discovers installed step packages, and materializes the active semantics
  store views through contracts.
- `cf_semantics_store` owns the RDF store layout.
- `cf_pipeline_manager` owns runtime state, run history, and revision metadata.

## Step package entry point convention

Entry point group: `cogniflow.steps`

Supported entry point values:

- Resource path: `some_pkg_module:steps.nq` (path relative to that package/module)
- Loader function: `some_pkg_module:load_steps` returning an RDF document `dict` or JSON string

Package metadata is read from the `cf:StepPackage` node in `steps.nq` (`cf:packageId` / `cf:packageVersion`).

Normative documentation in repository-tracked ontology assets is SKOS-only:
- `skos:prefLabel`
- `skos:definition`
- `skos:scopeNote`
- `skos:example`

The cf_web-facing step DTO contract keeps those four fields as the standard documentation surface for
steps, ports, and parameters, and exposes bounded adaptive SKOS metadata only when present:
- `skos:altLabel`
- `skos:notation`
- `skos:inScheme`
- `skos:broader`
- `skos:narrower`
- `skos:related`

The adaptive surface is intentionally constrained. `cf_ontology` only ships the packaged RDF assets;
it does not expose an unrestricted predicate dump or runtime write path to downstream services or the browser.

## Pipeline plugins header

Pipelines should also declare plugin directories so the runner can load implementations without `--plugins`:

```json
{
  "@id": "ex:MyPipeline",
  "@type": "cf:ProcessingPipeline",
  "cf:hasPluginsHeader": { "@id": "ex:pluginsHeader" }
},
{
  "@id": "ex:pluginsHeader",
  "@type": "cf:PluginsHeader",
  "cf:pluginPath": [
    "path/to/plugin/bin",
    "path/to/other/plugin/bin"
  ]
}
```

## Publishing

`cf_ontology` is published with the dedicated Windows workflow:

- Workflow: `.github/workflows/cf_ontology_windows_publish.yml`
- Package directory: `sandcastle/cf_ontology`
- PyPI tag: `cf-ontology-v<version>`
- TestPyPI tag: `cf-ontology-v<version>-test`

Local preflight:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/mimic_windows_python_publish_workflow.ps1 `
  -WorkflowFile .github/workflows/cf_ontology_windows_publish.yml `
  -PackageDir sandcastle/cf_ontology `
  -PythonExe py `
  -PythonVersion 3.14
```

The workflow test phase is expected to run the full package test surface from `sandcastle/cf_ontology` via:

```powershell
python -m pytest tests -q
```

This hard gate should stay aligned with the package contents under `cf-package.yaml` and the packaged ontology resources shipped from `src/cf_ontology/ontology/**`.

Queue a dry-run dispatch:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/queue_windows_python_publish_workflow.ps1 `
  -WorkflowFile .github/workflows/cf_ontology_windows_publish.yml `
  -PackageDir sandcastle/cf_ontology `
  -PublishTarget testpypi `
  -Ref main `
  -RequireLocalPass `
  -DryRun
```

