okf-parser 0.1.0__tar.gz

okf_parser-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  version-bump:
+    name: Version bump and changelog
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Require a version bump and matching changelog
+        shell: bash
+        env:
+          BASE: ${{ github.base_ref }}
+        run: |
+          set -euo pipefail
+          read_version() {
+            sed -n 's/^version = "\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\)"$/\1/p'
+          }
+
+          git fetch --quiet origin "$BASE"
+          head_version=$(read_version < pyproject.toml)
+          if git cat-file -e "origin/$BASE:pyproject.toml" 2>/dev/null; then
+            base_version=$(git show "origin/$BASE:pyproject.toml" | read_version)
+          else
+            base_version="0.0.0"
+          fi
+
+          if [[ -z "$head_version" ]]; then
+            echo "::error file=pyproject.toml::A versão SemVer não foi encontrada."
+            exit 1
+          fi
+          if [[ "$head_version" == "$base_version" ]]; then
+            echo "::error file=pyproject.toml::A versão continua $head_version; faça o bump."
+            exit 1
+          fi
+          highest=$(printf '%s\n%s\n' "$base_version" "$head_version" | sort -V | tail -1)
+          if [[ "$highest" != "$head_version" ]]; then
+            echo "::error file=pyproject.toml::A versão $head_version não supera $base_version."
+            exit 1
+          fi
+
+          expected_changelog="changelog/$head_version.md"
+          mapfile -t added_changelogs < <(
+            git diff --diff-filter=A --name-only "origin/$BASE...HEAD" -- "changelog/*.md"
+          )
+          if [[ "${#added_changelogs[@]}" -ne 1 ]]; then
+            echo "::error file=changelog::Cada PR deve adicionar exatamente um changelog."
+            printf 'Encontrado: %s\n' "${added_changelogs[@]}"
+            exit 1
+          fi
+          if [[ "${added_changelogs[0]}" != "$expected_changelog" ]]; then
+            echo "::error file=${added_changelogs[0]}::Esperado $expected_changelog."
+            exit 1
+          fi
+
+          echo "OK: $base_version -> $head_version; $expected_changelog presente."
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.21"
+          python-version: "3.12"
+
+      - name: Install locked dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Check lockfile
+        run: uv lock --check
+
+      - name: Check Python formatting
+        run: uv run ruff format --check .
+
+      - name: Lint Python
+        run: uv run ruff check .
+
+      - name: Check types
+        run: uv run ty check src tests
+
+      - name: Find dead code
+        run: uv run vulture src --min-confidence 90
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Validate this repository with okf-parser
+        run: uv run okf-parser check .
+
+      - name: Build distributions
+        run: uv build

okf_parser-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out release
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.21"
+          python-version: "3.12"
+
+      - name: Verify release version
+        shell: bash
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/okf-parser/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions with attestations
+        uses: pypa/gh-action-pypi-publish@release/v1

okf_parser-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/

okf_parser-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: okf-parser
+Version: 0.1.0
+Summary: Relational inspection and validation for Open Knowledge Format bundles
+Requires-Python: >=3.12
+Requires-Dist: cyclopts<5,>=4.22
+Requires-Dist: duckdb<2,>=1.4
+Requires-Dist: fastmcp<4,>=3.4
+Requires-Dist: ibis-framework[duckdb]<13,>=12
+Requires-Dist: markdown-it-py<5,>=4
+Requires-Dist: mdformat-frontmatter<3,>=2
+Requires-Dist: mdformat-gfm<2,>=1
+Requires-Dist: mdformat<2,>=1
+Requires-Dist: networkx<4,>=3.4
+Requires-Dist: pyyaml<7,>=6
+Description-Content-Type: text/markdown
+
+---
+type: Project
+title: okf-parser
+description: Relational inspection and validation for Open Knowledge Format bundles
+---
+
+# okf-parser
+
+Relational inspection and validation for
+[Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundles.
+
+`okf-parser` reads an OKF bundle without imposing a domain taxonomy, preserves
+unknown frontmatter fields, and exposes concepts and links as
+[Ibis](https://ibis-project.org/) tables. This makes bundle-wide rules—identity,
+lineage, cardinality, provenance, and profile-specific constraints—expressible
+as deterministic relational checks.
+
+## Why another OKF tool?
+
+The ecosystem already has good static linters and generators, including
+`okflint`, `okf-cli`, and `google-okf`. This project focuses on a different
+layer:
+
+- compile a bundle into queryable relational tables;
+- project those same relations into a NetworkX graph;
+- validate OKF v0.2 conformance without rejecting extensions;
+- distinguish normative errors from advisory diagnostics;
+- let projects add cross-concept rules as Ibis expressions;
+- produce stable human-readable and JSON reports for CI and agents.
+
+The parser and validation model are inspired by
+[`franklinbaldo/sisprev`](https://github.com/franklinbaldo/sisprev): parse
+documents independently from semantic validation, aggregate violations instead
+of failing at the first bad concept, preserve authored bodies, and test
+filesystem identity explicitly. No Sisprev-specific legal types are copied into
+the core.
+
+[`mrorigo/rust-okf`](https://github.com/mrorigo/rust-okf) inspired the stable
+logical key, conservative metadata preservation, BOM/CRLF handling, and clean
+separation between bundle parsing and downstream query surfaces. Its BM25,
+vector index, storage format, and HTTP server are intentionally outside this
+project's scope.
+
+## Quick start
+
+```bash
+uv sync
+uv run okf-parser check path/to/bundle
+uv run okf-parser inventory path/to/bundle
+uv run okf-parser graph path/to/bundle
+uv run okf-parser format path/to/bundle
+uv run okf-parser format path/to/bundle --write
+uv run okf-parser duckdb path/to/bundle knowledge.duckdb
+```
+
+The command exits with status `1` only when normative errors exist. Broken
+cross-links are warnings because OKF v0.2 explicitly says they do not make a
+bundle non-conformant.
+
+## GitHub Actions
+
+Add the repository as a CI check:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: franklinbaldo/okf-parser@v1
+    with:
+      path: knowledge
+```
+
+The composite action installs a pinned uv version and executes the same
+`validate_path()` function used by the Python API, CLI, and MCP server.
+
+Releases are published to PyPI from GitHub Releases through OIDC Trusted
+Publishing. No long-lived PyPI token is stored in the repository.
+
+Every pull request must increase the SemVer version in `pyproject.toml` and add
+exactly one matching `changelog/<version>.md` entry. CI compares both against
+the target branch before allowing merge.
+
+## MCP
+
+```bash
+uv run okf-parser serve
+uv run okf-parser-mcp
+uv run fastmcp run
+```
+
+Read-only tools: `check`, `inventory`, `graph`, and `format_check`.
+
+## DuckDB
+
+`okf-parser` is a regular uv-managed Python app; the DuckDB integration is part
+of the same package, not a native C++ subproject:
+
+```python
+import duckdb
+
+from okf_parser.duckdb import attach_okf
+
+connection = duckdb.connect("knowledge.duckdb")
+attach_okf(connection, "knowledge/")
+
+connection.sql("""
+    SELECT concept_type, count(*)
+    FROM okf.concepts
+    GROUP BY concept_type
+""").show()
+```
+
+The call creates `okf.concepts`, `okf.links`, `okf.reserved`, and
+`okf.diagnostics` as ordinary DuckDB tables. Use a new database or schema for
+each materialization.
+
+## Python API
+
+```python
+from pathlib import Path
+
+from okf_parser import load_bundle, validate_path
+
+bundle = load_bundle(Path("knowledge"))
+print(bundle.concepts.execute())
+print(bundle.links.execute())
+print(bundle.to_networkx())
+print(bundle.validate())
+
+report = validate_path(Path("knowledge"))
+assert report.markdown_count == report.concept_count + report.reserved_count
+assert report.is_conformant
+```
+
+## Current scope
+
+- UTF-8 Markdown discovery;
+- reserved `index.md` and `log.md` handling;
+- strict YAML-frontmatter parsing for concept documents;
+- required non-empty `type`;
+- stable concept IDs derived from paths;
+- Markdown-link extraction and resolution;
+- Ibis tables for concepts, reserved documents, and links;
+- NetworkX graph projection for traversal, cycles, components, and impact;
+- aggregated validation reports.
+
+Profiles, lifecycle/provenance family validation, external resources, and
+pluggable Ibis rules are the next milestones.

okf_parser-0.1.0/README.md

@@ -0,0 +1,148 @@
+---
+type: Project
+title: okf-parser
+description: Relational inspection and validation for Open Knowledge Format bundles
+---
+
+# okf-parser
+
+Relational inspection and validation for
+[Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundles.
+
+`okf-parser` reads an OKF bundle without imposing a domain taxonomy, preserves
+unknown frontmatter fields, and exposes concepts and links as
+[Ibis](https://ibis-project.org/) tables. This makes bundle-wide rules—identity,
+lineage, cardinality, provenance, and profile-specific constraints—expressible
+as deterministic relational checks.
+
+## Why another OKF tool?
+
+The ecosystem already has good static linters and generators, including
+`okflint`, `okf-cli`, and `google-okf`. This project focuses on a different
+layer:
+
+- compile a bundle into queryable relational tables;
+- project those same relations into a NetworkX graph;
+- validate OKF v0.2 conformance without rejecting extensions;
+- distinguish normative errors from advisory diagnostics;
+- let projects add cross-concept rules as Ibis expressions;
+- produce stable human-readable and JSON reports for CI and agents.
+
+The parser and validation model are inspired by
+[`franklinbaldo/sisprev`](https://github.com/franklinbaldo/sisprev): parse
+documents independently from semantic validation, aggregate violations instead
+of failing at the first bad concept, preserve authored bodies, and test
+filesystem identity explicitly. No Sisprev-specific legal types are copied into
+the core.
+
+[`mrorigo/rust-okf`](https://github.com/mrorigo/rust-okf) inspired the stable
+logical key, conservative metadata preservation, BOM/CRLF handling, and clean
+separation between bundle parsing and downstream query surfaces. Its BM25,
+vector index, storage format, and HTTP server are intentionally outside this
+project's scope.
+
+## Quick start
+
+```bash
+uv sync
+uv run okf-parser check path/to/bundle
+uv run okf-parser inventory path/to/bundle
+uv run okf-parser graph path/to/bundle
+uv run okf-parser format path/to/bundle
+uv run okf-parser format path/to/bundle --write
+uv run okf-parser duckdb path/to/bundle knowledge.duckdb
+```
+
+The command exits with status `1` only when normative errors exist. Broken
+cross-links are warnings because OKF v0.2 explicitly says they do not make a
+bundle non-conformant.
+
+## GitHub Actions
+
+Add the repository as a CI check:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+  - uses: franklinbaldo/okf-parser@v1
+    with:
+      path: knowledge
+```
+
+The composite action installs a pinned uv version and executes the same
+`validate_path()` function used by the Python API, CLI, and MCP server.
+
+Releases are published to PyPI from GitHub Releases through OIDC Trusted
+Publishing. No long-lived PyPI token is stored in the repository.
+
+Every pull request must increase the SemVer version in `pyproject.toml` and add
+exactly one matching `changelog/<version>.md` entry. CI compares both against
+the target branch before allowing merge.
+
+## MCP
+
+```bash
+uv run okf-parser serve
+uv run okf-parser-mcp
+uv run fastmcp run
+```
+
+Read-only tools: `check`, `inventory`, `graph`, and `format_check`.
+
+## DuckDB
+
+`okf-parser` is a regular uv-managed Python app; the DuckDB integration is part
+of the same package, not a native C++ subproject:
+
+```python
+import duckdb
+
+from okf_parser.duckdb import attach_okf
+
+connection = duckdb.connect("knowledge.duckdb")
+attach_okf(connection, "knowledge/")
+
+connection.sql("""
+    SELECT concept_type, count(*)
+    FROM okf.concepts
+    GROUP BY concept_type
+""").show()
+```
+
+The call creates `okf.concepts`, `okf.links`, `okf.reserved`, and
+`okf.diagnostics` as ordinary DuckDB tables. Use a new database or schema for
+each materialization.
+
+## Python API
+
+```python
+from pathlib import Path
+
+from okf_parser import load_bundle, validate_path
+
+bundle = load_bundle(Path("knowledge"))
+print(bundle.concepts.execute())
+print(bundle.links.execute())
+print(bundle.to_networkx())
+print(bundle.validate())
+
+report = validate_path(Path("knowledge"))
+assert report.markdown_count == report.concept_count + report.reserved_count
+assert report.is_conformant
+```
+
+## Current scope
+
+- UTF-8 Markdown discovery;
+- reserved `index.md` and `log.md` handling;
+- strict YAML-frontmatter parsing for concept documents;
+- required non-empty `type`;
+- stable concept IDs derived from paths;
+- Markdown-link extraction and resolution;
+- Ibis tables for concepts, reserved documents, and links;
+- NetworkX graph projection for traversal, cycles, components, and impact;
+- aggregated validation reports.
+
+Profiles, lifecycle/provenance family validation, external resources, and
+pluggable Ibis rules are the next milestones.

okf_parser-0.1.0/action.yml

@@ -0,0 +1,20 @@
+name: Validate OKF bundle
+description: Validate every Markdown file below a path as Open Knowledge Format v0.2
+inputs:
+  path:
+    description: Bundle directory to validate
+    required: false
+    default: .
+runs:
+  using: composite
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      with:
+        version: "0.11.21"
+    - name: Validate OKF
+      shell: bash
+      env:
+        OKF_PATH: ${{ inputs.path }}
+      run: |
+        uv run --project "$GITHUB_ACTION_PATH" --frozen okf-parser check "$OKF_PATH"

okf_parser-0.1.0/changelog/0.1.0.md

@@ -0,0 +1,20 @@
+---
+type: ChangelogEntry
+title: okf-parser 0.1.0
+description: Initial release of the relational OKF validation toolkit
+---
+
+# okf-parser 0.1.0
+
+- Validate complete OKF v0.2 bundles with aggregated diagnostics.
+- Query concepts and links through Ibis and materialize them in DuckDB.
+- Project bundle relationships into NetworkX graphs.
+- Expose Cyclopts CLI commands and read-only FastMCP tools.
+- Check or apply Markdown formatting with mdformat.
+- Reuse validation through a composite GitHub Action.
+- Publish signed PyPI releases through OIDC Trusted Publishing.
+- Validate the repository with `okf-parser` itself in CI.
+- Propose bidirectional code generation between OKF profiles and Python models.
+- Reserve only normative `index.md` and `log.md` documents.
+- Discover Markdown consistently without traversing environments or symlinks.
+- Extract links through CommonMark tokens and use portable concept keys.

okf_parser-0.1.0/fastmcp.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+  "source": {
+    "type": "filesystem",
+    "path": "src/okf_parser/cli.py",
+    "entrypoint": "mcp"
+  },
+  "environment": {
+    "type": "uv",
+    "python": "3.12",
+    "project": "."
+  },
+  "deployment": {
+    "transport": "stdio",
+    "log_level": "INFO"
+  }
+}

okf_parser-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "okf-parser"
+version = "0.1.0"
+description = "Relational inspection and validation for Open Knowledge Format bundles"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "cyclopts>=4.22,<5",
+  "duckdb>=1.4,<2",
+  "fastmcp>=3.4,<4",
+  "ibis-framework[duckdb]>=12,<13",
+  "markdown-it-py>=4,<5",
+  "mdformat>=1,<2",
+  "mdformat-frontmatter>=2,<3",
+  "mdformat-gfm>=1,<2",
+  "networkx>=3.4,<4",
+  "pyyaml>=6,<7",
+]
+
+[project.scripts]
+okf-parser = "okf_parser.cli:main"
+okf-parser-mcp = "okf_parser.cli:run_mcp_stdio"
+
+[dependency-groups]
+dev = [
+  "pytest>=8,<10",
+  "ruff>=0.15,<0.16",
+  "ty>=0.0.1a20,<0.1",
+  "vulture>=2.14,<3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "COM812",
+  "ISC001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/okf_parser/cli.py" = ["T201"]
+"tests/*" = ["D103", "PLR2004", "S101"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"