fkf 5.0.0__tar.gz

fkf-5.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Médéric Hurier (Fmind)
+
+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.

fkf-5.0.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: fkf
+Version: 5.0.0
+Summary: Local, offline evidence retrieval for coding agents
+Keywords: agents,knowledge,mcp,retrieval
+Author: Médéric Hurier
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: markdown-it-py>=4.2.0,<5
+Requires-Dist: mcp>=2.1.1,<3
+Requires-Dist: pydantic>=2.13.5,<3
+Requires-Dist: pyyaml>=6.0.3,<7
+Requires-Dist: typer>=0.27.2,<1
+Requires-Python: >=3.14
+Project-URL: Documentation, https://fmind.github.io/fkf/
+Project-URL: Issues, https://github.com/fmind/fkf/issues
+Project-URL: Repository, https://github.com/fmind/fkf
+Description-Content-Type: text/markdown
+
+# fkf — Fmind Knowledge Framework
+
+[![CI](https://github.com/fmind/fkf/actions/workflows/ci.yml/badge.svg)](https://github.com/fmind/fkf/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/fmind/fkf?sort=semver)](https://github.com/fmind/fkf/releases/latest) [![Python 3.14+](https://img.shields.io/badge/Python-3.14%2B-blue.svg)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Your coding agent knows your repository. It does not know the meeting that set the constraint, the review that rejected the approach, or the ticket that explains why the code looks like that.**
+
+`fkf` collects that work history into a git repository you own — plain JSON and Markdown, gathered by the provider CLIs you already trust — and hands your agent a small, budgeted, reproducible slice of it on demand.
+
+One command. No account, daemon, database, or telemetry. Stored reads are offline.
+
+## See it in 30 seconds
+
+No credentials, no network, no configuration:
+
+```bash
+fkf init ~/demo --demo 30
+fkf --format text context "retrieval boundary" --budget 1024 --explain --base ~/demo
+```
+
+The demo base is synthetic, but it is a real base: 30 days of events across six sources, a wiki, project pages, and a graph. This abridged result shortens URIs, fields, and receipt values:
+
+```text
+350 wiki   wiki/retrieval-boundary.md  Retrieval boundary · tags=decision,retrieval
+           why=exact-identifier:+100(retrieval boundary),term:+100(retrieval …),exact-phrase:+50
+182 record events/…/git-commits.json#…            Design retrieval boundary (LG-77)
+182 record events/…/google-calendar-events.json#… Document retrieval boundary (GW-1203)
+182 record events/…/google-gmail-emails.json#…    Fix retrieval boundary (FK-412)
+182 record events/…/jira-issues.json#FK-418-4     Revert retrieval boundary (FK-418)
+... 3 more selected items ...
+ 80 wiki   wiki/index.md  Wiki · navigation-page:-50(curated navigation ranks below concept pages)
+receipt pack for "retrieval boundary" · 9/736 selected · <1024 text tokens · floor 10
+window <30 days> · as_of <today> · digest <hex> · ranking v7 · dropped 717
+```
+
+One decision, scattered across a commit, a calendar invite, an email, and a Jira issue, pulled back together under a token budget.
+
+Three things make that pack usable by an agent rather than merely interesting:
+
+1. **It fits.** You set the budget; `context` selects the strongest evidence and stops. No pack silently blows past the window.
+1. **It explains itself.** Every line carries the score and the reason it was chosen — and the receipt records what was dropped, so a wrong answer is debuggable instead of mysterious.
+1. **It is reproducible.** Ranking is deterministic, and indexed and fallback reads return the same semantic answer. The receipt records the effective inputs, semantic digest, selection boundaries, and execution path. There are no embeddings or model calls in the read path.
+
+Then look around the base with `fkf find`, `fkf graph repo:github.com/fmind/fkf --in`, and `fkf list projects --status active`. Delete `~/demo` when you are done.
+
+## Install
+
+FKF is a Python 3.14 package. Install its stable `fkf` launcher with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install fkf
+```
+
+Use `uvx fkf ...` for a one-shot command without a persistent installation. Harness and schedule integration intentionally require a stable installed launcher because their configuration must keep working after the invoking process exits.
+
+Upgrade an installed tool through the package manager:
+
+```bash
+uv tool upgrade fkf
+```
+
+Wheel and source distributions are published to PyPI and attached to the [matching GitHub release](https://github.com/fmind/fkf/releases/latest) with build-provenance attestations.
+
+FKF supports Linux and macOS. WSL2 works when the base stays on its Linux filesystem; native Windows is out of scope because cancellation uses POSIX process groups.
+
+<details>
+<summary>Install from source</summary>
+
+```bash
+mise trust -y
+mise install --locked
+mise run install
+```
+
+To exercise the checkout without installing its launcher, run commands as `uv run fkf ...`.
+
+</details>
+
+## Connect your own work
+
+Start with one real source. The personal preset ships a reviewed GitHub Search helper — it needs `python3` and `gh` on your `PATH`, and `gh` owns the login:
+
+```bash
+gh auth status
+fkf init ~/brain --preset personal
+$EDITOR ~/brain/fkf.yaml                            # sources.github-pull-requests.enabled: true
+fkf config helpers --refresh --base ~/brain
+fkf trust --all --base ~/brain
+fkf status --base ~/brain                           # confirms every requirement is on PATH
+fkf sync github-pull-requests --days 30 --base ~/brain
+fkf context "repo:github.com/OWNER/REPOSITORY" --since 30d --explain --base ~/brain
+```
+
+Set `FKF_BASE=~/brain`, or run from inside the base, to drop `--base`.
+
+`fkf init` creates the five layers, `fkf.yaml`, managed git rules, the helpers your enabled sources need under `bin/`, and three agent skills under `.agents/skills/`. It contacts no provider and asks for no token. Browser, mail, and shell-history sources stay disabled until you turn them on.
+
+From there, `fkf sync` is safe to re-run: existing event documents are skipped, due index snapshots refresh, the graph follows document writes, and the lexical cache rebuilds only when searchable bytes change. `fkf brief` gives you the daily loop — yesterday's digest, today's calendar, assigned work, failing CI, stale or login-blocked sources.
+
+## The model
+
+Four ideas cover most of FKF.
+
+**A base is a folder.** One git repository, five readable layers. `ls`, `rg`, and `jq` still work.
+
+```text
+events/YYYY-MM-DD/  one complete JSON document per event source
+index/              current point-in-time source documents
+tasks/              authored execution evidence and learned items
+projects/           active, paused, or completed efforts
+wiki/               reusable decisions, patterns, tools, and insights
+graph.tsv           rebuildable relation cache at the base root
+```
+
+**A source is a command.** A source runs a reviewed command that prints one JSON document, and the named CLI owns its login. Adding GitHub, Google Workspace, Jira, or a local database needs no framework adapter — just YAML and, when the glue gets real, a small reviewed helper under the base's `bin/`:
+
+```yaml
+sources:
+  github-pull-requests:
+    enabled: true
+    layer: events
+    requires: [github-search-json.py, python3, gh]
+    window: true
+    run: [github-search-json.py, prs, assignee, "{{start}}", "{{end}}"]
+    fields:
+      id: .url
+      time: .updatedAt
+      title: .title
+      repo: .repository.nameWithOwner
+      repository: .repository_uri # relation: builds a graph edge
+      owner: [".assignee_uris[]"]
+    body: [gh, pr, view, "{{id}}", --repo, "{{repo}}", --json, "body,comments"]
+```
+
+**Relations are explicit URIs.** Records and pages link to file URIs or to entities such as `repo:github.com/fmind/fkf`. `graph.tsv` is built from declared relation fields and authored links — FKF never guesses a relationship from prose.
+
+**Retrieval is bounded and reproducible.** `find` returns every lexical match; `context` selects under a budget and explains itself. By default, records are stored as metadata plus a link and bodies stay at the provider. The opt-in `cache` and `sync` body policies keep ignored, manifest-verified local copies after an explicit read or evidence sync.
+
+Full detail: [sources](https://fmind.github.io/fkf/docs/sources/), [URIs and the graph](https://fmind.github.io/fkf/docs/uris-graph/), [context packs](https://fmind.github.io/fkf/docs/context/), [configuration schema](https://fmind.github.io/fkf/docs/schema/).
+
+## Use it from your coding agent
+
+```bash
+fkf harness install --all --dry-run --base ~/brain
+fkf harness install --all --base ~/brain
+fkf harness install claude codex gemini kiro --workspace ~/fmind --base ~/brain
+```
+
+The first command shows exactly what FKF would manage. The second registers read-only MCP under the base-scoped key `fkf-<name>` in all ten adapters. The third opts the four adapters with verified passive output into automatic context for one physical workspace. FKF does not create global links to a base's skills. If you manage client configuration yourself, the primitive is `fkf mcp serve --base ~/brain`.
+
+The MCP server is read-only and bounded: `context`, `find`, `day`, `timeline`, `list`, `read`, and `graph`. It cannot write, run a shell, or fetch bodies. The agent asks for a pack when it needs one. Ordinary lookups use `context` and a cited `read`; configuration inspection and task traces belong to setup or meaningful work. The bundled `fkf-use`, `fkf-learn`, and `daily-brief` skills teach it how. See the [harness guide](https://fmind.github.io/fkf/docs/harnesses/).
+
+## Trust and privacy
+
+- **FKF reads no credential** and expands no secret environment variable. Provider credentials stay with the provider CLI.
+- **Collected content is untrusted data** — evidence, never instructions. A stored value never becomes shell syntax or an executable name.
+- **`fkf trust` hashes the executable plan**: the effective `auth:`, `run:`, `test:`, and `body:` argv plus every file under the base's `bin/` and `tests/`. A meaningful change requires review again. It detects change; it is not a sandbox.
+- **Stored reads are offline, including `brief`.** `read --body` is the explicit read-time fetch; `sync` may prefetch bodies under the opt-in `bodies: sync` policy. Explicit `status --live` runs only bounded trusted `auth:` probes.
+- **FKF encrypts nothing and provides no backup.** Protect the disk and the remote. Whether event and index documents enter git history is your choice at `init`, recorded in `.gitignore`.
+
+Details and the full threat boundary: [privacy and trust](https://fmind.github.io/fkf/docs/privacy/).
+
+## Scope
+
+FKF is intentionally small. Do not use it if you need semantic search, a dashboard, a hosted service, native Windows, or a local cache your organization's data policy forbids. Your editor, shell, and coding agent remain the interface.
+
+Configuration and stored documents each carry `fkf: 1`. Evidence-envelope additions stay compatible within that marker, so old evidence stays readable without re-fetching provider history.
+
+## Development
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md), [AGENTS.md](AGENTS.md), and the [Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities through a [private security advisory](https://github.com/fmind/fkf/security/advisories/new), never a public issue — see [SECURITY.md](SECURITY.md).
+
+```bash
+mise run all      # format, check, branch-coverage tests, and package build
+mise run coverage # optional HTML branch-coverage report
+```
+
+The suite is hermetic and holds branch coverage to its ratcheted floor. Large graph observations remain opt-in test cases, never cross-machine thresholds.
+
+Full documentation: <https://fmind.github.io/fkf/>
+
+## License
+
+MIT. See [LICENSE](LICENSE).

fkf-5.0.0/README.md

@@ -0,0 +1,183 @@
+# fkf — Fmind Knowledge Framework
+
+[![CI](https://github.com/fmind/fkf/actions/workflows/ci.yml/badge.svg)](https://github.com/fmind/fkf/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/fmind/fkf?sort=semver)](https://github.com/fmind/fkf/releases/latest) [![Python 3.14+](https://img.shields.io/badge/Python-3.14%2B-blue.svg)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Your coding agent knows your repository. It does not know the meeting that set the constraint, the review that rejected the approach, or the ticket that explains why the code looks like that.**
+
+`fkf` collects that work history into a git repository you own — plain JSON and Markdown, gathered by the provider CLIs you already trust — and hands your agent a small, budgeted, reproducible slice of it on demand.
+
+One command. No account, daemon, database, or telemetry. Stored reads are offline.
+
+## See it in 30 seconds
+
+No credentials, no network, no configuration:
+
+```bash
+fkf init ~/demo --demo 30
+fkf --format text context "retrieval boundary" --budget 1024 --explain --base ~/demo
+```
+
+The demo base is synthetic, but it is a real base: 30 days of events across six sources, a wiki, project pages, and a graph. This abridged result shortens URIs, fields, and receipt values:
+
+```text
+350 wiki   wiki/retrieval-boundary.md  Retrieval boundary · tags=decision,retrieval
+           why=exact-identifier:+100(retrieval boundary),term:+100(retrieval …),exact-phrase:+50
+182 record events/…/git-commits.json#…            Design retrieval boundary (LG-77)
+182 record events/…/google-calendar-events.json#… Document retrieval boundary (GW-1203)
+182 record events/…/google-gmail-emails.json#…    Fix retrieval boundary (FK-412)
+182 record events/…/jira-issues.json#FK-418-4     Revert retrieval boundary (FK-418)
+... 3 more selected items ...
+ 80 wiki   wiki/index.md  Wiki · navigation-page:-50(curated navigation ranks below concept pages)
+receipt pack for "retrieval boundary" · 9/736 selected · <1024 text tokens · floor 10
+window <30 days> · as_of <today> · digest <hex> · ranking v7 · dropped 717
+```
+
+One decision, scattered across a commit, a calendar invite, an email, and a Jira issue, pulled back together under a token budget.
+
+Three things make that pack usable by an agent rather than merely interesting:
+
+1. **It fits.** You set the budget; `context` selects the strongest evidence and stops. No pack silently blows past the window.
+1. **It explains itself.** Every line carries the score and the reason it was chosen — and the receipt records what was dropped, so a wrong answer is debuggable instead of mysterious.
+1. **It is reproducible.** Ranking is deterministic, and indexed and fallback reads return the same semantic answer. The receipt records the effective inputs, semantic digest, selection boundaries, and execution path. There are no embeddings or model calls in the read path.
+
+Then look around the base with `fkf find`, `fkf graph repo:github.com/fmind/fkf --in`, and `fkf list projects --status active`. Delete `~/demo` when you are done.
+
+## Install
+
+FKF is a Python 3.14 package. Install its stable `fkf` launcher with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install fkf
+```
+
+Use `uvx fkf ...` for a one-shot command without a persistent installation. Harness and schedule integration intentionally require a stable installed launcher because their configuration must keep working after the invoking process exits.
+
+Upgrade an installed tool through the package manager:
+
+```bash
+uv tool upgrade fkf
+```
+
+Wheel and source distributions are published to PyPI and attached to the [matching GitHub release](https://github.com/fmind/fkf/releases/latest) with build-provenance attestations.
+
+FKF supports Linux and macOS. WSL2 works when the base stays on its Linux filesystem; native Windows is out of scope because cancellation uses POSIX process groups.
+
+<details>
+<summary>Install from source</summary>
+
+```bash
+mise trust -y
+mise install --locked
+mise run install
+```
+
+To exercise the checkout without installing its launcher, run commands as `uv run fkf ...`.
+
+</details>
+
+## Connect your own work
+
+Start with one real source. The personal preset ships a reviewed GitHub Search helper — it needs `python3` and `gh` on your `PATH`, and `gh` owns the login:
+
+```bash
+gh auth status
+fkf init ~/brain --preset personal
+$EDITOR ~/brain/fkf.yaml                            # sources.github-pull-requests.enabled: true
+fkf config helpers --refresh --base ~/brain
+fkf trust --all --base ~/brain
+fkf status --base ~/brain                           # confirms every requirement is on PATH
+fkf sync github-pull-requests --days 30 --base ~/brain
+fkf context "repo:github.com/OWNER/REPOSITORY" --since 30d --explain --base ~/brain
+```
+
+Set `FKF_BASE=~/brain`, or run from inside the base, to drop `--base`.
+
+`fkf init` creates the five layers, `fkf.yaml`, managed git rules, the helpers your enabled sources need under `bin/`, and three agent skills under `.agents/skills/`. It contacts no provider and asks for no token. Browser, mail, and shell-history sources stay disabled until you turn them on.
+
+From there, `fkf sync` is safe to re-run: existing event documents are skipped, due index snapshots refresh, the graph follows document writes, and the lexical cache rebuilds only when searchable bytes change. `fkf brief` gives you the daily loop — yesterday's digest, today's calendar, assigned work, failing CI, stale or login-blocked sources.
+
+## The model
+
+Four ideas cover most of FKF.
+
+**A base is a folder.** One git repository, five readable layers. `ls`, `rg`, and `jq` still work.
+
+```text
+events/YYYY-MM-DD/  one complete JSON document per event source
+index/              current point-in-time source documents
+tasks/              authored execution evidence and learned items
+projects/           active, paused, or completed efforts
+wiki/               reusable decisions, patterns, tools, and insights
+graph.tsv           rebuildable relation cache at the base root
+```
+
+**A source is a command.** A source runs a reviewed command that prints one JSON document, and the named CLI owns its login. Adding GitHub, Google Workspace, Jira, or a local database needs no framework adapter — just YAML and, when the glue gets real, a small reviewed helper under the base's `bin/`:
+
+```yaml
+sources:
+  github-pull-requests:
+    enabled: true
+    layer: events
+    requires: [github-search-json.py, python3, gh]
+    window: true
+    run: [github-search-json.py, prs, assignee, "{{start}}", "{{end}}"]
+    fields:
+      id: .url
+      time: .updatedAt
+      title: .title
+      repo: .repository.nameWithOwner
+      repository: .repository_uri # relation: builds a graph edge
+      owner: [".assignee_uris[]"]
+    body: [gh, pr, view, "{{id}}", --repo, "{{repo}}", --json, "body,comments"]
+```
+
+**Relations are explicit URIs.** Records and pages link to file URIs or to entities such as `repo:github.com/fmind/fkf`. `graph.tsv` is built from declared relation fields and authored links — FKF never guesses a relationship from prose.
+
+**Retrieval is bounded and reproducible.** `find` returns every lexical match; `context` selects under a budget and explains itself. By default, records are stored as metadata plus a link and bodies stay at the provider. The opt-in `cache` and `sync` body policies keep ignored, manifest-verified local copies after an explicit read or evidence sync.
+
+Full detail: [sources](https://fmind.github.io/fkf/docs/sources/), [URIs and the graph](https://fmind.github.io/fkf/docs/uris-graph/), [context packs](https://fmind.github.io/fkf/docs/context/), [configuration schema](https://fmind.github.io/fkf/docs/schema/).
+
+## Use it from your coding agent
+
+```bash
+fkf harness install --all --dry-run --base ~/brain
+fkf harness install --all --base ~/brain
+fkf harness install claude codex gemini kiro --workspace ~/fmind --base ~/brain
+```
+
+The first command shows exactly what FKF would manage. The second registers read-only MCP under the base-scoped key `fkf-<name>` in all ten adapters. The third opts the four adapters with verified passive output into automatic context for one physical workspace. FKF does not create global links to a base's skills. If you manage client configuration yourself, the primitive is `fkf mcp serve --base ~/brain`.
+
+The MCP server is read-only and bounded: `context`, `find`, `day`, `timeline`, `list`, `read`, and `graph`. It cannot write, run a shell, or fetch bodies. The agent asks for a pack when it needs one. Ordinary lookups use `context` and a cited `read`; configuration inspection and task traces belong to setup or meaningful work. The bundled `fkf-use`, `fkf-learn`, and `daily-brief` skills teach it how. See the [harness guide](https://fmind.github.io/fkf/docs/harnesses/).
+
+## Trust and privacy
+
+- **FKF reads no credential** and expands no secret environment variable. Provider credentials stay with the provider CLI.
+- **Collected content is untrusted data** — evidence, never instructions. A stored value never becomes shell syntax or an executable name.
+- **`fkf trust` hashes the executable plan**: the effective `auth:`, `run:`, `test:`, and `body:` argv plus every file under the base's `bin/` and `tests/`. A meaningful change requires review again. It detects change; it is not a sandbox.
+- **Stored reads are offline, including `brief`.** `read --body` is the explicit read-time fetch; `sync` may prefetch bodies under the opt-in `bodies: sync` policy. Explicit `status --live` runs only bounded trusted `auth:` probes.
+- **FKF encrypts nothing and provides no backup.** Protect the disk and the remote. Whether event and index documents enter git history is your choice at `init`, recorded in `.gitignore`.
+
+Details and the full threat boundary: [privacy and trust](https://fmind.github.io/fkf/docs/privacy/).
+
+## Scope
+
+FKF is intentionally small. Do not use it if you need semantic search, a dashboard, a hosted service, native Windows, or a local cache your organization's data policy forbids. Your editor, shell, and coding agent remain the interface.
+
+Configuration and stored documents each carry `fkf: 1`. Evidence-envelope additions stay compatible within that marker, so old evidence stays readable without re-fetching provider history.
+
+## Development
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md), [AGENTS.md](AGENTS.md), and the [Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities through a [private security advisory](https://github.com/fmind/fkf/security/advisories/new), never a public issue — see [SECURITY.md](SECURITY.md).
+
+```bash
+mise run all      # format, check, branch-coverage tests, and package build
+mise run coverage # optional HTML branch-coverage report
+```
+
+The suite is hermetic and holds branch coverage to its ratcheted floor. Large graph observations remain opt-in test cases, never cross-machine thresholds.
+
+Full documentation: <https://fmind.github.io/fkf/>
+
+## License
+
+MIT. See [LICENSE](LICENSE).