kbforge 0.1.0__tar.gz

kbforge-0.1.0/.github/dependabot.yml

@@ -0,0 +1,39 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # The hook revs in .pre-commit-config.yaml are the only place ruff's and ty's
+  # versions are declared -- the lint job runs the hooks rather than the tools --
+  # so bumping a rev here moves CI and every developer's pre-commit in lockstep.
+  # Dependabot skips `local` hooks, which is why these must stay as real repos.
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "dependencies"
+    groups:
+      hooks:
+        patterns:
+          - "*"

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

@@ -0,0 +1,87 @@
+name: CI and Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "*.md"
+      - "docs/**"
+      - "LICENSE"
+      - ".gitignore"
+  pull_request:
+    paths-ignore:
+      - "*.md"
+      - "docs/**"
+      - "LICENSE"
+      - ".gitignore"
+  release:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      run_publish:
+        description: "Set to true to run the publish job"
+        required: false
+        default: "false"
+
+permissions: {}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - run: uv python install 3.13
+      # Not a lint step: `--frozen` fails if uv.lock has drifted from pyproject.
+      - run: uv sync --all-extras --dev --frozen
+      # Run the hooks themselves instead of re-invoking ruff and ty, so the revs
+      # in .pre-commit-config.yaml are the single source of truth for which tool
+      # versions run. A version named here too would be a copy Dependabot cannot
+      # see, and it would silently drift from the hook on the next bump.
+      - run: uvx prek run --all-files --show-diff-on-failure
+
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --all-extras --dev --frozen
+      - run: uv run pytest --cov=kbforge --cov-report=term-missing
+
+  security:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+      - run: uvx uv-secure uv.lock
+
+  publish:
+    needs: [lint, test, security]
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.run_publish == 'true')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+      - run: uv python install 3.13
+      - run: uv build --no-sources
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

kbforge-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage

kbforge-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  # The rev pins both the ty version and a compatible uv version. The hook runs
+  # `uv check` under the hood, so kbforge's own dependencies resolve for ty --
+  # a local `entry: ty check` hook cannot see them.
+  - repo: https://github.com/astral-sh/ty-pre-commit
+    rev: v0.0.59
+    hooks:
+      - id: ty

kbforge-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

kbforge-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-19
+
+First release: a deterministic, credential-free walking skeleton of the kbforge
+production protocol.
+
+### Added
+
+- **Fixed pipeline** — `fetch → normalize → mirror → diff → scope → synthesize →
+  validate → publish`, run once by `kbforge run`. The order is not pluggable, and
+  neither are the two trust guarantees enforced in it: the **no-op rule** (a sync
+  that finds no change opens no merge request) and the **never-auto-merge rule**
+  (a publisher proposes; it never merges).
+- **Canonicalization** with the §4.3 stability law — `normalize` is deterministic,
+  clock-free, and volatile-free, so identical input always yields identical content
+  hashes. A byte-different but content-identical re-save (CRLF flips, a BOM, a
+  re-export) is not a change.
+- **Replay-safe mirror and read-only diff** — change is detected against a
+  core-owned mirror; the mirror advances only after a run fully succeeds. Absence
+  never implies a deletion.
+- **Two built-in connectors**, both credential-free:
+  - `local_files` — a folder of markdown-with-frontmatter, with an additive
+    `ignore_globs` config and always-on defaults (`.venv`, `.git`, `node_modules`,
+    tool caches) so pointing at a repository root does not sweep in dependencies.
+  - `git_commits` — one concept per commit, with genuine incremental sync: the
+    cursor is the last-synced SHA, so a re-run fetches only `<last>..<ref>`.
+- **§4.4 agent-facing artifact laws**, enforced as core validators at the `validate`
+  stage: facet well-formedness, link resolvability, anchor presence, and freshness
+  legibility, plus a projection↔files coherence check. Nothing non-conformant ships.
+- **Stub synthesizer** — deterministic, no LLM; reshapes canonical documents into
+  OKF concepts and gives the validators real structure to check.
+- **Dry-run publisher** — writes the proposed bundle to a local directory under a
+  source-named branch; never merges; idempotent.
+- **Plugin system** on Pluggy with entry-point discovery: any installed package
+  advertising the `kbforge.connectors` or `kbforge.publishers` entry-point group is
+  discovered without editing kbforge.
+- **CLI** — `kbforge list` shows available connectors; `kbforge run --connector NAME
+  --set KEY=VALUE ...` resolves the connector from the registry and takes YAML-typed
+  config, with no per-connector knowledge in the CLI.
+
+[Unreleased]: https://github.com/flyersworder/kbforge/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/flyersworder/kbforge/releases/tag/v0.1.0

kbforge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qing Ye
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kbforge-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: kbforge
+Version: 0.1.0
+Summary: Agent-first knowledge bases, forged from your systems of record
+Project-URL: Homepage, https://github.com/flyersworder/kbforge
+Project-URL: Repository, https://github.com/flyersworder/kbforge
+Project-URL: Issues, https://github.com/flyersworder/kbforge/issues
+Project-URL: Documentation, https://github.com/flyersworder/kbforge/blob/main/docs/architecture.md
+Project-URL: Changelog, https://github.com/flyersworder/kbforge/blob/main/CHANGELOG.md
+Author-email: Qing <qingye779@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent-governance,ai-agents,connectors,knowledge-base,mcp,okf,open-knowledge-format,pluggy,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: pluggy>=1.5
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kbforge
+
+[![CI](https://github.com/flyersworder/kbforge/actions/workflows/ci.yml/badge.svg)](https://github.com/flyersworder/kbforge/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Agent-first knowledge bases, forged from your systems of record.**
+
+The [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+(OKF) v0.1 standardizes the *artifact at rest* — markdown concept files, frontmatter,
+`index.md`, `log.md`. It says nothing about how those bundles get **produced**: how you
+pull from a wiki or a CMDB, how you tell a real change from an export timestamp jittering,
+how a claim stays traceable to its source, and how an update reaches `main` without a human
+losing an afternoon to review.
+
+`kbforge` is the missing half — the production protocol.
+
+| Layer | Standardized by |
+|---|---|
+| Artifact format | OKF v0.1 |
+| **Production protocol** — connectors, canonicalization, diff, provenance, publish | **kbforge** |
+| Serving protocol | MCP |
+
+"Agent-first" is a *checkable* claim, not a downstream hope. kbforge stays a producer —
+the agent connects over MCP, which kbforge doesn't own — but every publish is gated on
+four **agent-facing artifact laws** (facet well-formedness, link resolvability, anchor
+presence, freshness legibility), plus a projection↔files coherence check so nothing
+ships unvalidated. That gate is what puts the frontmatter, links, and provenance an
+agent's serving layer needs into the artifact. What each law enforces at full versus
+reduced strength (and the paths to full strength) is spelled out honestly in
+[architecture.md §4.4](docs/architecture.md#44-agent-facing-artifact-laws-the-emit-side)
+and the [artifact-contract spec](docs/design/2026-07-18-agent-facing-artifact-contract-design.md) §5.1.
+
+## Status
+
+**Alpha — a working walking skeleton.** The deterministic pipeline runs end to end with
+no credentials and no LLM: two built-in connectors (`local_files`, `git_commits`),
+canonicalization with a stability law, a replay-safe mirror and diff, a stub synthesizer,
+the §4.4 validator gate, and a dry-run publisher. Change detection, the no-op rule, and
+incremental sync via a real cursor are exercised by the test suite.
+
+Not built yet: a real LLM synthesizer (the current one copies source text verbatim), a
+credentialed system-of-record connector, and a GitHub-PR publisher. See
+[`docs/architecture.md`](docs/architecture.md) for the full map.
+
+## Quickstart
+
+```bash
+pip install kbforge
+kbforge list                       # show available connectors
+
+kbforge run \
+  --connector local_files \
+  --set path=./docs \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+Re-running with no source change is a no-op — no merge request is opened. Point
+`--connector git_commits --set repo=.` at a git repository to sync commit history
+incrementally instead. Config values are YAML-typed, so `--set max_commits=50` is an
+integer and `--set 'ignore_globs=[drafts]'` is a list.
+
+## Design stance
+
+The core ships **zero credentialed connectors and zero CI logic.** The two built-in
+connectors need no credentials and serve as references; real systems of record are
+plugins, discovered through the `kbforge.connectors` (and `kbforge.publishers`)
+entry-point group without editing kbforge — deployments are separate, private
+repositories. The interface is the product.
+
+```toml
+# in a third-party package's pyproject.toml — discovered automatically once installed
+[project.entry-points."kbforge.connectors"]
+myservice = "my_package:connector"
+```
+
+The pipeline order — fetch → normalize → mirror → diff → scope → synthesize → validate →
+publish — is deliberately **not** pluggable, and neither are the no-op rule or the
+never-auto-merge rule. Those are the trust guarantees; making them pluggable would make
+them optional. Plugins extend stages. They cannot reorder or remove them.
+
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md) — package architecture, the Pluggy
+  hookspecs, the connector protocol and its canonicalization laws, the fixed pipeline, and
+  the conformance test kit.
+- [`docs/context/knowledge-base-design.md`](docs/context/knowledge-base-design.md) — the
+  system kbforge was extracted from: an OKF knowledge base for application managers served
+  over MCP, including the security model and a literature review.
+- [`docs/design/2026-07-18-agent-facing-artifact-contract-design.md`](docs/design/2026-07-18-agent-facing-artifact-contract-design.md)
+  — why the artifact contract exists and how the four emit-side laws are enforced.
+- [`docs/design/2026-07-19-agentic-ingest-design.md`](docs/design/2026-07-19-agentic-ingest-design.md)
+  — the roadmap for agentic fetch, the refresh model, and KB bootstrap.
+- [`docs/design/2026-07-18-datacontract-bridge-design.md`](docs/design/2026-07-18-datacontract-bridge-design.md)
+  — how kbforge bridges to `agentic-data-contracts` via the OKF bundle (future, cross-project).
+- [`CHANGELOG.md`](CHANGELOG.md) — release history.
+
+## Related projects
+
+kbforge is one of three *contracts for agents*, split by seam:
+
+- [**ai-agent-contracts**](https://github.com/flyersworder/agent-contracts) — the formal
+  spine: resource, temporal, and lifecycle contracts (the seven-tuple kbforge maps onto).
+- [**agentic-data-contracts**](https://github.com/flyersworder/agentic-data-contracts) —
+  the *consumption* half for **structured** data: domain-driven governance enforced at
+  query time. kbforge is the *production* half for **unstructured** knowledge; both
+  independently converged on making freshness legible to the agent.
+
+## Development
+
+```bash
+uv sync --all-extras --dev   # create the venv and install
+prek install                 # ruff + ty on every commit
+uv run pytest
+```
+
+## License
+
+MIT

kbforge-0.1.0/README.md

@@ -0,0 +1,119 @@
+# kbforge
+
+[![CI](https://github.com/flyersworder/kbforge/actions/workflows/ci.yml/badge.svg)](https://github.com/flyersworder/kbforge/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Agent-first knowledge bases, forged from your systems of record.**
+
+The [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+(OKF) v0.1 standardizes the *artifact at rest* — markdown concept files, frontmatter,
+`index.md`, `log.md`. It says nothing about how those bundles get **produced**: how you
+pull from a wiki or a CMDB, how you tell a real change from an export timestamp jittering,
+how a claim stays traceable to its source, and how an update reaches `main` without a human
+losing an afternoon to review.
+
+`kbforge` is the missing half — the production protocol.
+
+| Layer | Standardized by |
+|---|---|
+| Artifact format | OKF v0.1 |
+| **Production protocol** — connectors, canonicalization, diff, provenance, publish | **kbforge** |
+| Serving protocol | MCP |
+
+"Agent-first" is a *checkable* claim, not a downstream hope. kbforge stays a producer —
+the agent connects over MCP, which kbforge doesn't own — but every publish is gated on
+four **agent-facing artifact laws** (facet well-formedness, link resolvability, anchor
+presence, freshness legibility), plus a projection↔files coherence check so nothing
+ships unvalidated. That gate is what puts the frontmatter, links, and provenance an
+agent's serving layer needs into the artifact. What each law enforces at full versus
+reduced strength (and the paths to full strength) is spelled out honestly in
+[architecture.md §4.4](docs/architecture.md#44-agent-facing-artifact-laws-the-emit-side)
+and the [artifact-contract spec](docs/design/2026-07-18-agent-facing-artifact-contract-design.md) §5.1.
+
+## Status
+
+**Alpha — a working walking skeleton.** The deterministic pipeline runs end to end with
+no credentials and no LLM: two built-in connectors (`local_files`, `git_commits`),
+canonicalization with a stability law, a replay-safe mirror and diff, a stub synthesizer,
+the §4.4 validator gate, and a dry-run publisher. Change detection, the no-op rule, and
+incremental sync via a real cursor are exercised by the test suite.
+
+Not built yet: a real LLM synthesizer (the current one copies source text verbatim), a
+credentialed system-of-record connector, and a GitHub-PR publisher. See
+[`docs/architecture.md`](docs/architecture.md) for the full map.
+
+## Quickstart
+
+```bash
+pip install kbforge
+kbforge list                       # show available connectors
+
+kbforge run \
+  --connector local_files \
+  --set path=./docs \
+  --mirror .kbforge/mirror --out .kbforge/out --state .kbforge/state
+```
+
+Re-running with no source change is a no-op — no merge request is opened. Point
+`--connector git_commits --set repo=.` at a git repository to sync commit history
+incrementally instead. Config values are YAML-typed, so `--set max_commits=50` is an
+integer and `--set 'ignore_globs=[drafts]'` is a list.
+
+## Design stance
+
+The core ships **zero credentialed connectors and zero CI logic.** The two built-in
+connectors need no credentials and serve as references; real systems of record are
+plugins, discovered through the `kbforge.connectors` (and `kbforge.publishers`)
+entry-point group without editing kbforge — deployments are separate, private
+repositories. The interface is the product.
+
+```toml
+# in a third-party package's pyproject.toml — discovered automatically once installed
+[project.entry-points."kbforge.connectors"]
+myservice = "my_package:connector"
+```
+
+The pipeline order — fetch → normalize → mirror → diff → scope → synthesize → validate →
+publish — is deliberately **not** pluggable, and neither are the no-op rule or the
+never-auto-merge rule. Those are the trust guarantees; making them pluggable would make
+them optional. Plugins extend stages. They cannot reorder or remove them.
+
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md) — package architecture, the Pluggy
+  hookspecs, the connector protocol and its canonicalization laws, the fixed pipeline, and
+  the conformance test kit.
+- [`docs/context/knowledge-base-design.md`](docs/context/knowledge-base-design.md) — the
+  system kbforge was extracted from: an OKF knowledge base for application managers served
+  over MCP, including the security model and a literature review.
+- [`docs/design/2026-07-18-agent-facing-artifact-contract-design.md`](docs/design/2026-07-18-agent-facing-artifact-contract-design.md)
+  — why the artifact contract exists and how the four emit-side laws are enforced.
+- [`docs/design/2026-07-19-agentic-ingest-design.md`](docs/design/2026-07-19-agentic-ingest-design.md)
+  — the roadmap for agentic fetch, the refresh model, and KB bootstrap.
+- [`docs/design/2026-07-18-datacontract-bridge-design.md`](docs/design/2026-07-18-datacontract-bridge-design.md)
+  — how kbforge bridges to `agentic-data-contracts` via the OKF bundle (future, cross-project).
+- [`CHANGELOG.md`](CHANGELOG.md) — release history.
+
+## Related projects
+
+kbforge is one of three *contracts for agents*, split by seam:
+
+- [**ai-agent-contracts**](https://github.com/flyersworder/agent-contracts) — the formal
+  spine: resource, temporal, and lifecycle contracts (the seven-tuple kbforge maps onto).
+- [**agentic-data-contracts**](https://github.com/flyersworder/agentic-data-contracts) —
+  the *consumption* half for **structured** data: domain-driven governance enforced at
+  query time. kbforge is the *production* half for **unstructured** knowledge; both
+  independently converged on making freshness legible to the agent.
+
+## Development
+
+```bash
+uv sync --all-extras --dev   # create the venv and install
+prek install                 # ruff + ty on every commit
+uv run pytest
+```
+
+## License
+
+MIT