cobalt-grinding 0.1.0__tar.gz

cobalt_grinding-0.1.0/.dockerignore

@@ -0,0 +1,21 @@
+# Exclude things that don't belong in the published image.
+# pyproject.toml / uv.lock / README.md / src/ are explicitly COPY'd
+# by the Dockerfile, so we don't need an allow-list here — just a
+# denylist for the obvious noise.
+
+.git
+.github
+.venv
+.gitignore
+.dockerignore
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+docs
+tests
+humans_notes.md
+worktrees

cobalt_grinding-0.1.0/.github/workflows/dev-release.yml

@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Dev release
+
+# On-demand PRE-RELEASE publish from `develop` — a dev build to exercise a candidate
+# before the real release. Manually triggered (workflow_dispatch; run it with
+# `--ref develop`, or via `git dev-release`). Publishes a GHCR `:dev` image and the
+# `X.Y.Z.devN` version to TestPyPI. It creates NO `v*` tag, so the real release.yml
+# gate is untouched, and runs no changelog job. See the handbook's releases.md
+# ("Development versioning") + ci.md.
+#
+# Python/pyproject + TestPyPI variant; a Node repo would publish an npm dist-tag instead.
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write       # GHCR push
+  id-token: write       # TestPyPI trusted publishing (OIDC)
+
+jobs:
+  # Gate: dev builds come from develop and must carry a dev version. Both publish
+  # jobs need it, so a bad invocation ships nothing.
+  gate:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.v.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Verify dev build from develop
+        id: v
+        run: |
+          if [ "$GITHUB_REF" != "refs/heads/develop" ]; then
+            echo "dev-release runs from develop only (got $GITHUB_REF)"; exit 1
+          fi
+          VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          case "$VERSION" in
+            *.dev*|*-dev) ;;
+            *) echo "version '$VERSION' is not a dev version (expected X.Y.Z.devN) — open the dev cycle first"; exit 1 ;;
+          esac
+          echo "dev version: $VERSION"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+  docker:
+    needs: gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up QEMU (arm64 emulation)
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (dev tags — NOT latest)
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=dev
+            type=raw,value=${{ needs.gate.outputs.version }}
+            type=sha,prefix=sha-
+
+      - name: Build and push (linux/amd64 + linux/arm64)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  testpypi:
+    needs: gate
+    runs-on: ubuntu-latest
+    environment: testpypi   # matches the trusted-publisher config on TestPyPI
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

cobalt_grinding-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,171 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read        # default — gate/docker/pypi only read the tree
+  packages: write       # GHCR push
+  id-token: write       # PyPI trusted publishing
+
+jobs:
+  # Pre-flight checks. Both publish jobs depend on this, so a failed gate
+  # prevents *any* artifact from shipping (no half-shipped state).
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0          # full history needed for the ancestor check below
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Verify tag matches pyproject version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PROJECT_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$PROJECT_VERSION" ]; then
+            echo "tag $TAG != pyproject $PROJECT_VERSION"
+            exit 1
+          fi
+
+      - name: Verify tag is reachable from origin/main
+        run: |
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "tagged commit $GITHUB_SHA is not on origin/main"
+            echo "release tags must come from main — back-merge through, then re-tag from main"
+            exit 1
+          fi
+
+  docker:
+    needs: gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up QEMU (arm64 emulation)
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags + labels)
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+
+      - name: Build and push (linux/amd64 + linux/arm64)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  pypi:
+    needs: gate
+    runs-on: ubuntu-latest
+    environment: pypi   # matches the trusted-publisher config on PyPI
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Generate the Highlights paragraph + categorized list, commit the new
+  # CHANGELOG.md section back to main, and create the GitHub Release. Runs
+  # AFTER docker + pypi so the Release page points at artifacts that already
+  # exist. Two-phase invocation of generate_changelog.py keeps the LLM call
+  # to a single round-trip even though the commit-back happens onto a fresh
+  # main checkout.
+  changelog:
+    needs: [gate, docker, pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # scoped here — only this job commits CHANGELOG.md back to main
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0          # full history + all tags for git-cliff
+          # default ref = the tag, which is what we want for `--mode=generate`
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Install git-cliff
+        uses: taiki-e/install-action@v2
+        with:
+          tool: git-cliff
+
+      - name: Generate release-body.md (LLM call happens here)
+        env:
+          # Set at the ParkviewLab org level — inherited by every repo
+          # under the org. Missing key → script writes a placeholder
+          # paragraph and the release still ships.
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_REF: ${{ github.ref }}
+        # `uv run --with anthropic` injects the SDK for just this invocation,
+        # without polluting pyproject.toml. Lets this workflow snippet be
+        # identical across every ParkviewLab repo regardless of whether
+        # `anthropic` is otherwise a project dep.
+        run: uv run --with anthropic python scripts/generate_changelog.py --mode=generate
+
+      - name: Switch to fresh origin/main and insert into CHANGELOG.md
+        run: |
+          # Stash the just-generated release body so it survives the checkout.
+          cp release-body.md /tmp/release-body.md
+          git fetch origin main
+          git checkout origin/main
+          mv /tmp/release-body.md release-body.md
+          # Re-runs only the file-manipulation half — no LLM call, no anthropic SDK needed.
+          uv run python scripts/generate_changelog.py --mode=insert
+
+      - name: Commit CHANGELOG.md back to main
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add CHANGELOG.md
+          if git diff --staged --quiet; then
+            echo "no changelog change to commit"
+            exit 0
+          fi
+          TAG="${GITHUB_REF#refs/tags/}"
+          # [skip ci] guards against any future non-tag-triggered workflows;
+          # this release workflow only fires on `push: tags` so isn't at risk
+          # of recursing, but the marker is cheap insurance.
+          git commit -m "docs(changelog): $TAG [skip ci]"
+          git push origin HEAD:main
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --notes-file release-body.md \
+            --target main

cobalt_grinding-0.1.0/.github/workflows/reuse.yml

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: REUSE
+
+# REUSE/SPDX compliance — a required check in every repo (code and docs).
+# See the handbook's licensing.md and ci.md.
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  reuse:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - name: reuse lint
+        run: uvx --from "reuse[charset-normalizer]" reuse lint

cobalt_grinding-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Test
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Sync deps
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Format check
+        run: uv run ruff format --check src tests
+
+      - name: Type check
+        run: uv run ty check          # ty must be a dev dependency
+
+      - name: Tests (excluding network + docling marker)
+        run: uv run pytest -m "not integration" -q

cobalt_grinding-0.1.0/.github/workflows/version-guard.yml

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Version guard
+
+# Feature PRs into `develop` must NOT change the version source-of-truth — the
+# bump happens at release, on `main` (see the handbook's releases.md / ci.md).
+# The release back-merge (main→develop) is a direct push, not a PR, so it is not
+# subject to this check.
+
+on:
+  pull_request:
+    branches: [develop]
+
+permissions:
+  contents: read
+
+jobs:
+  no-version-change:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Version SoT must be unchanged
+        env:
+          BASE: ${{ github.base_ref }}
+        run: |
+          git fetch --no-tags --depth=1 origin "$BASE"
+          fail=0
+          flag() { echo "::error::$1 changed in a feature PR — version bumps happen at release on main, not in feature work (handbook releases.md)."; fail=1; }
+          if [ -f VERSION.txt ]; then
+            old=$(git show "origin/$BASE:VERSION.txt" 2>/dev/null || echo "")
+            [ "$(cat VERSION.txt)" = "$old" ] || flag VERSION.txt
+          fi
+          if [ -f pyproject.toml ]; then
+            new=$(grep -E '^version *=' pyproject.toml | head -1 || true)
+            old=$(git show "origin/$BASE:pyproject.toml" 2>/dev/null | grep -E '^version *=' | head -1 || true)
+            [ "$new" = "$old" ] || flag "pyproject.toml [project].version"
+          fi
+          if [ -f package.json ]; then
+            new=$(grep -E '"version"' package.json | head -1 || true)
+            old=$(git show "origin/$BASE:package.json" 2>/dev/null | grep -E '"version"' | head -1 || true)
+            [ "$new" = "$old" ] || flag "package.json version"
+          fi
+          if [ "$fail" = 0 ]; then echo "version unchanged ✓"; fi
+          exit $fail

cobalt_grinding-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+
+# Build artifacts (uv build / hatchling)
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.ty_cache/
+.mypy_cache/
+
+# venv / uv
+.venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local test artifacts
+/tmp-wiki/
+
+# Transient release artifact: scripts/generate_changelog.py writes this for
+# `gh release create --notes-file`; it's regenerated every release, never committed.
+release-body.md
+
+# Secrets
+.env
+.env.*

cobalt_grinding-0.1.0/.mailmap

@@ -0,0 +1,4 @@
+# Canonicalize commit identity to the public project identity.
+# Maps the personal GitHub handle email to the ParkviewLab identity so any
+# tooling (git shortlog, blame, forges) shows the canonical author/committer.
+Gary Frattarola <garyf@parkviewlab.ai> <garycoding@gmail.com>

cobalt_grinding-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "deco-assaying": {
+      "type": "http",
+      "url": "http://127.0.0.1:35832/sse"
+    }
+  }
+}

cobalt_grinding-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

cobalt_grinding-0.1.0/AGENTS.md

@@ -0,0 +1,29 @@
+<!--
+SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<!-- PARKVIEWLAB:BEGIN (managed by ParkviewLab/handbook — do not edit inside this block; run scripts/sync-agent-files.sh to update) -->
+# ParkviewLab conventions
+
+This repo follows the **[ParkviewLab handbook](https://github.com/ParkviewLab/handbook/tree/main)** —
+the single source of truth for how we work. These pointer files **don't re-inline** its rules:
+**read the handbook before non-trivial work**, starting with
+**[`ai-collaboration.md`](https://github.com/ParkviewLab/handbook/blob/main/docs/ai-collaboration.md)**
+(the behavioural contract). Only the safety-critical guardrails are summarized here.
+
+**If present, read `docs/northstar.md` before working.** It states the project's intent and is authoritative.
+
+## Shared-state writes need explicit authorization
+- **Merging a PR into `develop` is the user's call.** A broad directive ("fix all that", "finish it") authorizes work on the branch, **not** the merge.
+- **Tagging, cutting a release, force-pushing, or pushing to a protected branch each need an explicit, per-action go-ahead** — never inferred from a descriptive label (e.g. "→ v0.1.1"). One release ask covers the whole CLI release flow.
+
+## Workflow basics
+- Work in an ephemeral, **prefixed** worktree off `develop` (`feature-`/`fix-`/`doc-`/…) — don't commit on `develop`/`main` directly. Open a PR **into `develop`**.
+- PRs are **squash-merged**, so the **PR title** carries the Conventional Commit prefix (`feat:`/`fix:`/`docs:`/…) the changelog is generated from.
+
+**Everything else lives in the handbook** (don't rely on memory): branching, commits & changelogs, releases, Python tooling, CI, licensing, and the full communication norms — see <https://github.com/ParkviewLab/handbook/tree/main/docs>.
+<!-- PARKVIEWLAB:END -->
+
+<!-- Repo-specific guidance below this line is preserved by the sync script — add anything particular to this repo here. -->

cobalt_grinding-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are recorded here. Each release entry
+has two parts:
+
+- **Highlights** — a 2-3 sentence "what's new" paragraph generated at
+  release time by an Anthropic-API call (see
+  `scripts/generate_changelog.py`).
+- **Categorized changes** — a list of merged commits since the previous
+  tag, grouped by [Conventional Commit](https://www.conventionalcommits.org/)
+  prefix, produced by [git-cliff](https://git-cliff.org/) using
+  `cliff.toml`.
+
+The release workflow on every tag push regenerates both, commits the new
+section here, and uses the same content as the GitHub Release body.
+
+<!--
+  Keep-a-Changelog ordering: [Unreleased] at the top, then newest
+  released version, then older versions. generate_changelog.py inserts
+  new "## [vX.Y.Z] - YYYY-MM-DD" sections directly below [Unreleased].
+  Don't remove the marker.
+-->
+
+## [Unreleased]

cobalt_grinding-0.1.0/CLAUDE.md

@@ -0,0 +1,29 @@
+<!--
+SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<!-- PARKVIEWLAB:BEGIN (managed by ParkviewLab/handbook — do not edit inside this block; run scripts/sync-agent-files.sh to update) -->
+# ParkviewLab conventions
+
+This repo follows the **[ParkviewLab handbook](https://github.com/ParkviewLab/handbook/tree/main)** —
+the single source of truth for how we work. These pointer files **don't re-inline** its rules:
+**read the handbook before non-trivial work**, starting with
+**[`ai-collaboration.md`](https://github.com/ParkviewLab/handbook/blob/main/docs/ai-collaboration.md)**
+(the behavioural contract). Only the safety-critical guardrails are summarized here.
+
+**If present, read `docs/northstar.md` before working.** It states the project's intent and is authoritative.
+
+## Shared-state writes need explicit authorization
+- **Merging a PR into `develop` is the user's call.** A broad directive ("fix all that", "finish it") authorizes work on the branch, **not** the merge.
+- **Tagging, cutting a release, force-pushing, or pushing to a protected branch each need an explicit, per-action go-ahead** — never inferred from a descriptive label (e.g. "→ v0.1.1"). One release ask covers the whole CLI release flow.
+
+## Workflow basics
+- Work in an ephemeral, **prefixed** worktree off `develop` (`feature-`/`fix-`/`doc-`/…) — don't commit on `develop`/`main` directly. Open a PR **into `develop`**.
+- PRs are **squash-merged**, so the **PR title** carries the Conventional Commit prefix (`feat:`/`fix:`/`docs:`/…) the changelog is generated from.
+
+**Everything else lives in the handbook** (don't rely on memory): branching, commits & changelogs, releases, Python tooling, CI, licensing, and the full communication norms — see <https://github.com/ParkviewLab/handbook/tree/main/docs>.
+<!-- PARKVIEWLAB:END -->
+
+<!-- Repo-specific guidance below this line is preserved by the sync script — add anything particular to this repo here. -->

cobalt_grinding-0.1.0/Dockerfile

@@ -0,0 +1,46 @@
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
+
+WORKDIR /app
+
+# Layer 1: resolve project deps for cache stability across source changes.
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --no-dev --no-install-project
+
+# Layer 2: install the project itself + the three sibling MCP servers
+# cobalt-grinding spawns as children. README.md is part of pyproject's
+# metadata (project.readme); the first uv sync skipped reading it, but
+# the second sync (with --install-project) needs it. Bundling the
+# children keeps the "out of the box demo" working — `docker run …`
+# starts a daemon that has a Smalt + lab notebook + code parser ready
+# without extra installs. Operators who want to swap or omit a child
+# can override the [mcp.clients.*] config or remove its env entry.
+COPY README.md ./
+COPY src/ src/
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --no-dev && \
+    uv pip install --system smalt-mcp ebony-enriching deco-assaying
+
+# Container env. The three substrate / capability dirs land under
+# /data, mounted via VOLUME. cobalt-grinding's config layer reads
+# `COBALT_GRINDING_SMALT_DIR` / `_EBONY_DIR` / `_COBALT_GRINDING_DIR`
+# and injects them into the matching child's env at startup.
+#
+# `MCP_HOST=0.0.0.0` is the bind address for the HTTP transport —
+# 127.0.0.1 (the default) wouldn't accept connections from outside
+# the container.
+ENV PYTHONUNBUFFERED=1 \
+    COBALT_GRINDING_SMALT_DIR=/data/smalt \
+    COBALT_GRINDING_EBONY_DIR=/data/ebony \
+    COBALT_GRINDING_COBALT_GRINDING_DIR=/data/cobalt_grinding \
+    COBALT_GRINDING_MCP_HOST=0.0.0.0 \
+    COBALT_GRINDING_MCP_PORT=7474
+
+EXPOSE 7474
+VOLUME ["/data"]
+
+# `ANTHROPIC_API_KEY` must be passed at run time
+# (`docker run -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY …`). Without it
+# the daemon still starts and substrate-bootstraps; cognitive-skill
+# tools (wiki.ask, etc.) will return a clear error at call time.
+CMD ["uv", "run", "cobalt-grinding"]