okfgraph 0.9.0__tar.gz → 0.10.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. {okfgraph-0.9.0 → okfgraph-0.10.2}/PKG-INFO +180 -79
  2. okfgraph-0.10.2/README.md +476 -0
  3. okfgraph-0.10.2/okfgraph/__init__.py +24 -0
  4. okfgraph-0.10.2/okfgraph/_entry.py +28 -0
  5. okfgraph-0.10.2/okfgraph/cli.py +1478 -0
  6. okfgraph-0.10.2/okfgraph/components/bibtex.py +336 -0
  7. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/converters.py +51 -2
  8. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/delta.py +29 -4
  9. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/doctor.py +117 -10
  10. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/embedding.py +282 -46
  11. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/export.py +2 -14
  12. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/image_assets.py +1 -8
  13. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/import_.py +248 -75
  14. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/ingest.py +310 -190
  15. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/lint.py +9 -2
  16. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/purge.py +3 -4
  17. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/ranking.py +1 -1
  18. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/schema.py +0 -1
  19. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/search.py +87 -60
  20. okfgraph-0.10.2/okfgraph/crash.py +88 -0
  21. okfgraph-0.10.2/okfgraph/errors.py +225 -0
  22. okfgraph-0.10.2/okfgraph/mcp_server.py +466 -0
  23. okfgraph-0.10.2/okfgraph/ops/__init__.py +13 -0
  24. okfgraph-0.10.2/okfgraph/ops/admin.py +426 -0
  25. okfgraph-0.10.2/okfgraph/ops/export.py +83 -0
  26. okfgraph-0.10.2/okfgraph/ops/ingest.py +21 -0
  27. okfgraph-0.10.2/okfgraph/ops/query.py +325 -0
  28. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/router.py +58 -178
  29. okfgraph-0.10.2/okfgraph/settings.py +561 -0
  30. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph.egg-info/PKG-INFO +180 -79
  31. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph.egg-info/SOURCES.txt +24 -3
  32. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph.egg-info/entry_points.txt +1 -1
  33. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph.egg-info/requires.txt +2 -2
  34. {okfgraph-0.9.0 → okfgraph-0.10.2}/pyproject.toml +11 -5
  35. okfgraph-0.10.2/tests/test_bibtex.py +85 -0
  36. okfgraph-0.10.2/tests/test_cache_hygiene.py +173 -0
  37. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_chunk_search.py +23 -1
  38. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_chunking.py +8 -31
  39. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_cli.py +13 -13
  40. okfgraph-0.10.2/tests/test_converter_status.py +78 -0
  41. okfgraph-0.10.2/tests/test_crash_report.py +107 -0
  42. okfgraph-0.10.2/tests/test_delete.py +92 -0
  43. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_delta.py +2 -2
  44. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_detach.py +16 -11
  45. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_diff.py +6 -2
  46. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_directory_hash.py +1 -1
  47. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_doctor.py +4 -4
  48. okfgraph-0.10.2/tests/test_envelope.py +138 -0
  49. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_error_paths.py +35 -5
  50. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_export_compliance.py +7 -6
  51. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_golden_vectors.py +1 -1
  52. okfgraph-0.10.2/tests/test_gpu_hint.py +127 -0
  53. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_graph_enrichment.py +6 -4
  54. okfgraph-0.10.2/tests/test_import_positional.py +95 -0
  55. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_ingest.py +18 -48
  56. okfgraph-0.10.2/tests/test_ingest_bib.py +111 -0
  57. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_integration.py +5 -5
  58. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_lazy_encoder.py +1 -1
  59. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_lint.py +4 -2
  60. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_logging.py +19 -0
  61. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_max_length.py +18 -17
  62. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_mcp_server.py +134 -77
  63. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_mcp_stdio.py +20 -2
  64. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_model.py +17 -18
  65. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_multiroot.py +59 -47
  66. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_obsidian.py +5 -5
  67. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_ort.py +34 -1
  68. okfgraph-0.10.2/tests/test_pages.py +142 -0
  69. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_parity.py +3 -0
  70. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_pdf_e2e.py +8 -24
  71. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_phase0.py +7 -7
  72. okfgraph-0.10.2/tests/test_pinned_bundle.py +153 -0
  73. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_ppr_search.py +7 -6
  74. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_precision.py +17 -19
  75. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_reconstruction.py +1 -1
  76. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_reserved.py +2 -2
  77. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_retrieval_conformance.py +7 -7
  78. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_rootless.py +9 -8
  79. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_roundup_cli.py +12 -8
  80. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_router.py +133 -106
  81. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_router_misc.py +6 -6
  82. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_rust_backend.py +1 -1
  83. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_sanitize.py +1 -1
  84. okfgraph-0.10.2/tests/test_settings.py +340 -0
  85. okfgraph-0.10.2/tests/test_shell.py +228 -0
  86. okfgraph-0.10.2/tests/test_surface_contract.py +237 -0
  87. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_thought_ids.py +6 -11
  88. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_vision.py +2 -2
  89. okfgraph-0.9.0/README.md +0 -378
  90. okfgraph-0.9.0/okfgraph/__init__.py +0 -7
  91. okfgraph-0.9.0/okfgraph/cli.py +0 -1560
  92. okfgraph-0.9.0/okfgraph/config.py +0 -541
  93. okfgraph-0.9.0/okfgraph/mcp_server.py +0 -536
  94. okfgraph-0.9.0/okfgraph/tools.py +0 -461
  95. okfgraph-0.9.0/tests/test_config.py +0 -156
  96. {okfgraph-0.9.0 → okfgraph-0.10.2}/LICENSE +0 -0
  97. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/__init__.py +0 -0
  98. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/diff.py +0 -0
  99. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/links.py +0 -0
  100. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/producers.py +0 -0
  101. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/components/roots.py +0 -0
  102. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/images.py +0 -0
  103. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/models.py +0 -0
  104. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph/security.py +0 -0
  105. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph.egg-info/dependency_links.txt +0 -0
  106. {okfgraph-0.9.0 → okfgraph-0.10.2}/okfgraph.egg-info/top_level.txt +0 -0
  107. {okfgraph-0.9.0 → okfgraph-0.10.2}/setup.cfg +0 -0
  108. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_chunk_cap.py +0 -0
  109. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_converter.py +0 -0
  110. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_encode_bucketing.py +0 -0
  111. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_explicit_files.py +0 -0
  112. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_gpu_integration.py +0 -0
  113. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_image_ingest.py +0 -0
  114. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_images.py +0 -0
  115. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_ingest_tool.py +0 -0
  116. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_models.py +0 -0
  117. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_observations.py +0 -0
  118. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_okf_ingest_tool.py +0 -0
  119. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_packaging.py +0 -0
  120. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_produce.py +0 -0
  121. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_ranking.py +0 -0
  122. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_rust_e2e.py +0 -0
  123. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_search_browser.py +0 -0
  124. {okfgraph-0.9.0 → okfgraph-0.10.2}/tests/test_security.py +0 -0
@@ -1,13 +1,16 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: okfgraph
3
- Version: 0.9.0
3
+ Version: 0.10.2
4
4
  Summary: Ladybug-backed OKF knowledge graph with ONNX + Jina v5 embeddings
5
5
  License-Expression: Apache-2.0 OR MIT
6
+ Project-URL: Homepage, https://opticswolf.github.io/OKFgraph/
7
+ Project-URL: Documentation, https://github.com/opticsWolf/OKFgraph/blob/main/docs/architecture.md
8
+ Project-URL: Repository, https://github.com/opticsWolf/OKFgraph
6
9
  Requires-Python: >=3.11
7
10
  Description-Content-Type: text/markdown
8
11
  License-File: LICENSE
9
12
  Requires-Dist: ladybug==0.21.2
10
- Requires-Dist: embroider<0.4,>=0.3.0
13
+ Requires-Dist: embroider<0.4,>=0.3.2
11
14
  Requires-Dist: pydantic>=2.0
12
15
  Requires-Dist: python-frontmatter>=1.0
13
16
  Requires-Dist: pyyaml>=6.0
@@ -23,7 +26,7 @@ Requires-Dist: onnxruntime==1.29.0; extra == "cpu"
23
26
  Provides-Extra: gpu
24
27
  Requires-Dist: onnxruntime-gpu[cuda,cudnn]==1.29.0; extra == "gpu"
25
28
  Provides-Extra: pdf
26
- Requires-Dist: bobine>=0.5; extra == "pdf"
29
+ Requires-Dist: bobine>=0.6; extra == "pdf"
27
30
  Dynamic: license-file
28
31
 
29
32
  # OKFgraph
@@ -32,7 +35,8 @@ Dynamic: license-file
32
35
  [![Python](https://img.shields.io/badge/python-%3E%3D3.11-blue)](https://www.python.org/)
33
36
  [![License](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-green)](LICENSE)
34
37
  [![MCP](https://img.shields.io/badge/MCP-%E2%89%A52.0-purple)](https://modelcontextprotocol.io/)
35
- [![Ladybug](https://img.shields.io/badge/ladybug-0.20.3-orange)](https://pypi.org/project/ladybug/)
38
+ [![Ladybug](https://img.shields.io/badge/ladybug-0.21.2-orange)](https://pypi.org/project/ladybug/)
39
+ [![Website](https://img.shields.io/badge/website-OKFgraph-blue)](https://opticswolf.github.io/OKFgraph/)
36
40
 
37
41
  **Ladybug-backed knowledge graph with Rust-driven Jina v5 embeddings, model-free
38
42
  graph retrieval, and agent-first MCP + CLI surfaces.**
@@ -55,48 +59,74 @@ a swappable `DocumentConverter` seam. What isn't needed isn't installed.
55
59
 
56
60
  | Category | Features |
57
61
  |---|---|
58
- | **Embeddings** | Jina v5 (default `…-text-small-retrieval`, `--model` selects registry: text-nano) via the `embroider` Rust wheel; last-token pooling, Matryoshka truncation (default 512, per-model ladder); device `auto` (CUDA→FP16 mirror weights, CPU→FP32, `--precision` pins incl. explicit `int8`); CPU arena off by default (`--cpu-arena`); token ceiling configurable (`--max-length`); model + precision pinned per graph, never mixed. No torch anywhere (0.7.0+) |
62
+ | **Embeddings** | Jina v5 (default `…-text-small-retrieval`, `--model-id` selects registry: text-nano) via the `embroider` Rust wheel; last-token pooling, Matryoshka truncation (default 512, per-model ladder); device `auto` (CUDA→FP16 mirror weights, CPU→FP32, `--precision` pins incl. explicit `int8`); CPU arena off by default (`--cpu-arena`); token ceiling configurable (`--max-length`); model + precision pinned per graph, never mixed. No torch anywhere (0.7.0+) |
59
63
  | **Search** | Hybrid RRF fusion (vector + FTS) at concept and chunk granularity; `rank=none\|hub\|ppr` — including **PPR**: lexical seeds → exact Personalized PageRank, zero model load, deterministic |
60
64
  | **Read** | Body / chunks / rebuilt document / graph context, with optional **token budgets** (`max_tokens`): self first, then PPR-ranked neighbours, index-first for context |
61
65
  | **Storage** | LadybugDB `==0.21.2` (pinned — 0.20.x segfaulted 2nd in-process vector-index builds): graph + vector + FTS in one file |
62
66
  | **Links** | Path links (`](doc.md)`) + `[[wikilinks]]` resolved by name (`uid` → `aliases` → `title` → filename stem); ambiguous names never resolve; broken links tracked and repairable |
63
- | **Import** | Single files, whole bundles (delta-aware: only changed files re-embed, `--purge` drops deleted concepts), markdown / PDF+Office / raw thoughts; mordant lint on the way in |
67
+ | **Import** | Single files, whole bundles (delta-aware: only changed files re-embed, `--prune-missing` drops deleted concepts), markdown / PDF+Office / raw thoughts; mordant lint on the way in; `okf produce` generates bundles from SQLite (`## Observations` + `log.md` changelog) |
64
68
  | **PDF** | `DocumentConverter` seam with `BobineConverter` default (routing `auto\|surgical\|always\|never`); bring your own converter, no code changes |
65
69
  | **Diff** | `okf diff`: structural snapshot (dir vs dir, no model load) and drift (graph vs dir) modes; CI exit codes + `--json` |
66
70
  | **Doctor** | `okf doctor`: 0–100 health score (broken/orphan/stale/duplicate-title/missing-description), safe `--fix` that never touches `reviewed: true`, `--strict` CI gate |
67
71
  | **Export** | OKF round-trip with See Also / Cited By enrichment + index files, or `--flavor obsidian` (`[[Title]]` wikilinks, no index files, edge-lossless re-import) |
68
72
  | **Images** | Caption-based (`mode=text`) or image-content (`mode=optional`/`omni` via the ONNX vision model, needs a text-nano graph; 0.8.0+) content-hash dedup, `okf-asset://` protocol |
69
- | **MCP** | 5 tools (`search`, `read`, `traverse`, `ingest`, `export_bundle`), MCP ≥ 2.0 (`MCPServer` + `ToolAnnotations`), stdio transport |
70
- | **CLI** | Same 5 verbs plus maintenance (`init`, `import`, `diff`, `doctor`, `shell`, `reindex`, `broken-links`, `deleted-*`, …), slim per-command help, `okfgraph.toml` config |
73
+ | **MCP** | 8 tools (`search`, `read`, `traverse`, `ingest`, `export_bundle`, `export_concept`, `list_images`, `get_image`), MCP ≥ 2.0 (`MCPServer` + `ToolAnnotations`), stdio transport; success result = envelope, failures = `isError: true` + error envelope (D7) |
74
+ | **CLI** | Same 8 core verbs (`search`, `read`, `traverse`, `ingest`, `import`, `export`, `diff`, `doctor`) plus maintenance (`shell`, `lint`, `produce`, `reindex`, `broken-links`, `deleted-*`, `delete`, `images`, `image`, …), global `--json` (D5), slim per-command help, `okfgraph.toml` config |
71
75
  | **Skills** | 3 harness-neutral skills (`okfgraph-mcp`, `okfgraph-cli`, `okfgraph-ingest`), `.mcp.json` wiring included |
72
76
 
73
77
  ---
74
78
 
75
79
  ## Installation
76
80
 
77
- Requires Python ≥ 3.11.
81
+ Requires Python ≥ 3.11. You must pick **exactly one** ONNX Runtime
82
+ extra, `cpu` or `gpu`:
83
+
84
+ ### CPU or GPU?
85
+
86
+ | | `[gpu]` | `[cpu]` |
87
+ |---|---|---|
88
+ | **Pick it when** | the machine has an NVIDIA GPU (`nvidia-smi` prints it) | no NVIDIA GPU, macOS, CI, or a small install |
89
+ | Runtime | `onnxruntime-gpu[cuda,cudnn]==1.29.0` (bundles the CUDA + cuDNN runtime wheels: a large download) | `onnxruntime==1.29.0` (small) |
90
+ | `--device auto` lands on | CUDA, FP16 weights (much faster bulk import) | CPU, FP32 weights |
91
+ | Platforms | Windows, Linux x86-64 with a recent NVIDIA driver | all |
92
+
93
+ Not sure? Run `nvidia-smi`: if it lists a GPU, take `[gpu]`. After
94
+ installing, `okf doctor` shows `cuda_usable=True/False`. With a GPU
95
+ present but the CPU runtime installed it adds an `ort_gpu_unused` note,
96
+ and `--device auto` logs a warning when it falls back to CPU. Switching
97
+ later is safe: the extras conflict, so installing one replaces the
98
+ other. Vectors made on CPU (FP32) and GPU (FP16) cannot share one graph
99
+ (the precision pin refuses it), so pick before the first import or plan
100
+ a reimport.
101
+
102
+ **PyPI**
78
103
 
79
104
  ```bash
80
- pip install "okfgraph[cpu,pdf]" # PyPI (embeddings come from the published `embroider` wheels; use [gpu,pdf] for CUDA)
105
+ pip install "okfgraph[gpu,pdf]" # NVIDIA GPU
106
+ pip install "okfgraph[cpu,pdf]" # everything else
81
107
  ```
82
108
 
83
- Or from source with `uv` (no Rust toolchain needed — the embedding
84
- engine is the external `embroider` package):
109
+ **From source** with `uv` (no Rust toolchain needed: the embedding
110
+ engine is the external `embroider` package). Name every extra in **one**
111
+ `uv sync`: each sync makes the venv exactly what it names, so a later
112
+ `uv sync --extra pdf` would uninstall the runtime again.
85
113
 
86
114
  ```bash
87
115
  git clone <repo> && cd OKFgraph
88
- uv sync # core: ladybug, embroider, mordant, mcp, … (no ORT — pick cpu|gpu)
89
- uv sync --extra cpu # ONNX Runtime CPU (or --extra gpu for CUDA)
90
- uv sync --extra pdf # bobine PDF converter
91
- uv sync --extra dev # pytest
116
+ uv sync --extra gpu --extra pdf --extra dev # NVIDIA GPU
117
+ uv sync --extra cpu --extra pdf --extra dev # everything else
92
118
  ```
93
119
 
120
+ (`pdf` = bobine PDF converter, `dev` = pytest; drop what you don't need.
121
+ Bare `uv sync` installs the core only, with no runtime: the first
122
+ encode then fails with an install hint.)
123
+
94
124
  Prefer a system-wide ONNX Runtime (conda, distro package, self-built)?
95
125
  Skip both extras and point `ORT_DYLIB_PATH` at your onnxruntime 1.29
96
126
  library instead — but never rely on bare OS-loader discovery: a stale
97
127
  system DLL (e.g. in `System32`) fails the load instead of being used.
98
128
 
99
- Core dependencies are deliberately few: `ladybug==0.21.2`, `embroider>=0.3,<0.4`
129
+ Core dependencies are deliberately few: `ladybug==0.21.2`, `embroider>=0.3.2,<0.4`
100
130
  (the shared embedding engine — github.com/opticsWolf/embroider, also used by
101
131
  bobine), `onnxruntime==1.29.0` (one pinned ORT binary shared by bobine +
102
132
  embroider; `ORT_DYLIB_PATH`-overridable), `mordant`, `mcp>=2.0`, `pydantic`,
@@ -108,8 +138,8 @@ transformers, no optimum, no PDF stack in the core install.
108
138
  ## Quick start
109
139
 
110
140
  ```bash
111
- okf init --db kb.db --bundle kb/ # once; persists to okfgraph.toml
112
- okf import --all --bundle kb/ # delta-aware bulk import
141
+ okf init --db-path kb.db --bundle-root kb/ # once; persists to okfgraph.toml
142
+ okf import --all # delta-aware bulk import
113
143
  okf search "honey badger defense" # hybrid semantic search
114
144
  okf search --rank ppr "honey badger" # same question, no model load
115
145
  okf read savanna --include context --max-tokens 1500
@@ -117,7 +147,9 @@ okf traverse savanna --relationship LINKS_TO --direction BOTH
117
147
  okf diff # drift: graph vs bundle dir
118
148
  okf doctor # health score + findings
119
149
  okf lint kb/ # pre-import gate: frontmatter + links, no model
120
- okf produce --from sqlite --source shop.db --output kb/ # SQLite → bundle (lint pre-flighted)
150
+ okf produce --from sqlite --source shop.db --output-dir kb/ # SQLite → bundle (lint pre-flighted)
151
+ okf images savanna # image assets on one concept
152
+ okf image img-1 --output-path asset.png # fetch one asset
121
153
  ```
122
154
 
123
155
  ### Programmatic usage
@@ -128,29 +160,37 @@ from okfgraph import OKFRouter
128
160
 
129
161
  router = OKFRouter(db_path="kb.db", bundle_root="kb/", embedding_dim=512)
130
162
 
163
+ # One vocabulary: every operation lives on the router (24 ops), raises
164
+ # OKFError(code) with a stable exit plan, and returns dict/list data.
165
+
131
166
  # Import: whole bundle (delta-aware), one file, or raw reasoning
132
- ids = router.import_mgr.import_bundle(Path("kb/"), purge_deleted=False)
133
- cid = router.import_from_okf(Path("kb/auth.md"), mode="text")
134
- th = router.ingest_mgr.ingest_thoughts("Session decided X because Y", topic="auth-refactor")
167
+ result = router.import_bundle(None) # every configured root -> {"concept_ids", "images"}
168
+ cid = router.import_file("kb/auth.md", mode="text")["concept_id"]
169
+ th = router.ingest("thoughts", thoughts="Session decided X because Y",
170
+ topic="auth-refactor")["concept_id"]
135
171
 
136
172
  # Search: hybrid (default), hub-blended, or model-free PPR
137
- hits = router.search_hybrid("session auth decisions", limit=5)
138
- hubbed = router.search_hybrid("session auth decisions", rank="hub")
139
- cold = router.search_engine.search_with_ppr("auth refactor") # no ONNX load
173
+ hits = router.search("session auth decisions", limit=5)
174
+ hubbed = router.search("session auth decisions", rank="hub")
175
+ cold = router.search("auth refactor", rank="ppr") # no ONNX load
140
176
 
141
177
  # Read: full shapes, or a token-budgeted section list
142
- doc = router.get_by_id("auth")
143
- reading = router.search_engine.read_with_budget("auth", include="context", max_tokens=1500)
178
+ doc = router.read("auth", include="body")
179
+ reading = router.read("auth", include="context", max_tokens=1500)
180
+
181
+ # Image assets are first-class read ops
182
+ imgs = router.list_images(cid)
183
+ row = router.get_image(imgs[0]["id"])
144
184
 
145
185
  # Maintain: drift, health, links
146
- print(router.diff_db_dir(Path("kb/"))["identical"]) # True when in sync
147
- print(router.diagnose()["score"]) # 0-100
148
- print(router.doctor_fix()) # safe repairs only
149
- print(router.repair_links()) # re-point broken links
186
+ print(router.diff(Path("kb/"))["identical"]) # in sync; differs -> DIFF_DIFFERENT (report on err.data)
187
+ print(router.doctor()["report"]["score"]) # 0-100
188
+ print(router.doctor(stale_days=365, fix=True)) # repair pass, then re-score
189
+ print(router.repair_links()) # re-point broken links -> {"repaired": n}
150
190
 
151
191
  # Export: OKF bundle or Obsidian vault
152
- router.export_mgr.export_bundle(Path("out-okf/"))
153
- router.export_mgr.export_bundle(Path("out-vault/"), flavor="obsidian")
192
+ router.export_bundle(Path("out-okf/"))
193
+ router.export_bundle(Path("out-vault/"), flavor="obsidian")
154
194
 
155
195
  router.close()
156
196
  ```
@@ -159,9 +199,13 @@ router.close()
159
199
 
160
200
  | Kind | Entry point | Notes |
161
201
  |---|---|---|
162
- | `md` | `ingest_md(md_path, concept_id?, title?, tags?, mode?)` | mordant-linted; frontmatter wins over overrides |
163
- | `pdf` | `ingest_pdf(pdf_path, auto_import?, routing_mode?, …)` | bobine converter; `md_path` is transient when auto-importing — verify by searching, not by reading the path |
164
- | `thoughts` | `ingest_thoughts(text, topic, tags?)` | cheapest, highest value: persist session reasoning with a stable topic scheme (`auth-refactor`, `api-design`) |
202
+ | `md` | `router.ingest("md", md_path=…, concept_id?, title?, description?, tags?, mode?) -> {"concept_id","chunk_count","image_count","lint_issues",…}` | mordant-linted, report-only (`lint_issues.fixable_count` — the source file is never rewritten); `image_count` counts real image refs resolved next to the file; frontmatter wins over overrides |
203
+ | `pdf` | `router.ingest("pdf", pdf_path=…, routing_mode?, extract_images?, auto_import?, output_dir?) -> {"concept_ids","page_count","md_path","image_dir"}` | bobine converter; auto-imports by default (`auto_import=False` / `--no-auto-import` converts only, into `output_dir` or next to the source) |
204
+ | `thoughts` | `router.ingest("thoughts", thoughts=…, topic=…, concept_id?, tags?) -> {"concept_id","topic","chunk_count",…}` | cheapest, highest value: persist session reasoning with a stable topic scheme (`auth-refactor`, `api-design`) |
205
+ | `bib` | `router.ingest("bib", bib_path=…, tags?) -> {"concept_ids","entry_count","skipped_entries",…}` | one `reference` concept per `@entry` as `refs/<key>` (stable IDs — re-ingesting upserts; slug collisions disambiguated, never silently overwritten); malformed entries reported per-entry in `skipped_entries`, never fatal |
206
+
207
+ Params that belong to another kind are refused (`BAD_VALUE` naming them),
208
+ not silently dropped.
165
209
 
166
210
  Frontmatter that matters: `title`, `type`, `tags`, `aliases: [...]` (wikilink
167
211
  names), `id:` (stable identity, preserved as `uid`, written back on export),
@@ -174,37 +218,76 @@ pdf — reasoning you already hold beats re-extracting it from files.
174
218
 
175
219
  ## CLI reference
176
220
 
177
- Five verbs mirror the MCP tools; maintenance commands cover the rest. Global
178
- flags (`--db`, `--bundle`, `--bundle-root`, `--dim`, `--max-length`, …) are documented once in `okf --help`,
179
- accepted everywhere, and usually live in `okfgraph.toml`.
221
+ Eight verbs mirror the MCP tools; maintenance commands cover the rest. Global
222
+ flags (`--db-path`, `--bundle-root`, `--embedding-dim`, `--model-id`,
223
+ `--max-length`, …) are documented once in `okf --help`, accepted everywhere,
224
+ and usually live in `okfgraph.toml`. Every command accepts `--json` (D5):
225
+ human renderer by default, the result envelope
226
+ (`{ok, op, data, warnings, error}`) on stdout with `--json`. Results always
227
+ go to stdout and logs to stderr (`-q` silences logs, never results).
228
+ Failures print `[ERROR] CODE: message (remedy)` on stderr (plus the error
229
+ envelope on stdout under `--json`) and exit 0 ok / 1 state·outcome / 2
230
+ usage. Outcomes (`lint` errors, `diff` differences, `doctor --strict`
231
+ findings) still render their report before exiting 1. Typed state codes
232
+ include `DB_LOCKED` (the db is open in another process — `okf` commands
233
+ run one at a time per database; when `okf-mcp` is serving, query through
234
+ it), `NO_ORT_RUNTIME` (no/broken ONNX Runtime), and the pin set.
235
+ Concurrency: one process per db file; the 0-byte `<db>.lock` beside it is
236
+ ladybug's own lock marker and is harmless when no process holds it.
237
+ A leftover after a crash/kill is indistinguishable from a live hold at first
238
+ glance — check processes first, then remove by hand if stale (`okf doctor`
239
+ reports it; the CLI never auto-deletes). Pin the database in `okfgraph.toml`
240
+ (`db_path = "kb.db"`, overridable per-invocation with `OKFGRAPH_DB_PATH`)
241
+ so a held-open default can never silently fork a second database.
242
+ Unexpected failures (`INTERNAL`) also write the full traceback — with argv,
243
+ versions and platform — to a crash file (`%LOCALAPPDATA%\okfgraph\crash\`,
244
+ else `$XDG_STATE_HOME`/`~/.local/state`; `OKF_CRASH_DIR` overrides, newest
245
+ 20 kept). The final `[ERROR]` line names the file, so it survives `tail`,
246
+ and `--json` carries it in `error.fields.crash_report`. Start-up failures
247
+ (a broken install, a native DLL, a half-edited checkout) are covered too:
248
+ the `okf` launcher enters through `okfgraph._entry`, which guards the
249
+ package import itself.
180
250
 
181
251
  | Command | Description |
182
252
  |---|---|
183
253
  | `okf search QUERY [--target concepts\|chunks\|images] [--rank none\|hub\|ppr] [--expand] [--hub-rerank]` | Concepts (RRF hybrid), chunks (passages), images; `--rank ppr` is model-free |
184
254
  | `okf read ID [--include body\|chunks\|document\|context] [--max-tokens N]` | Full shapes uncapped; budgeted section list with `--max-tokens` |
185
255
  | `okf traverse [ID] [--relationship CONTAINS\|LINKS_TO\|PART_OF\|INCLUDES_ASSET] [--direction …] [--target ID]` | Relationships, directory listing (empty ID = root), shortest path via `--target` |
186
- | `okf ingest --kind md\|pdf\|thoughts …` | `--md-file`, `--pdf-file` (`--routing-mode`, `--auto-import`), `--thoughts --topic` |
187
- | `okf export --all\|--concept-id ID --output DIR [--flavor okf\|obsidian]` | Bundle export; obsidian = `[[Title]]` links, no index files |
256
+ | `okf ingest --kind md\|pdf\|thoughts\|bib …` | `--md-path`, `--pdf-path` (`--routing-mode`, auto-imports by default; `--no-auto-import` converts only), `--thoughts --topic`, `--bib-path` (one `refs/<key>` concept per BibTeX entry) |
257
+ | `okf export --all\|--concept-id ID --output-dir DIR [--flavor okf\|obsidian]` | Bundle or single-concept export; obsidian = `[[Title]]` links, no index files |
258
+ | `okf images CONCEPT_ID` / `okf image ASSET_ID [--output-path F]` | Image assets on a concept; metadata (+ bytes) per asset |
188
259
  | `okf diff [OLD] [NEW] [--json]` | Snapshot (two dirs, no model) or drift (graph vs dir); exit 0 identical / 1 different |
189
260
  | `okf lint [DIR] [--json]` | Pre-import gate (no DB, no model); exit 0 clean / 1 errors / 2 bad dir |
190
261
  | `okf doctor [--fix] [--strict] [--stale-days N] [--json]` | Score + findings; `--fix` repairs safely, `--strict` exits 1 on any finding |
191
- | `okf import [--all] [--purge] [--mode text] [--force]` | Bulk/single import, delta-aware (`--force` re-attaches a detached graph); repeatable `--bundle-root ALIAS=PATH` adds named roots (`@alias/` IDs, unmounted ≠ deleted, `--purge` refuses while any root is absent); `--bundle` pins one tree, `--primary` sets the bare-ID root for all-roots scope (both = refused) |
192
- | `okf detach [--bundle DIR] [--no-verify] [--force]` | End the mirror: the DB becomes the artifact (verify-first; imports refuse without `--force`) |
193
- | `okf init`, `okf model-info`, `okf shell`, `okf reindex`, `okf broken-links`, `okf repair-links`, `okf deleted-*` | Setup, cache inspection, REPL, index rebuild, link + soft-delete maintenance |
194
-
195
- Every CLI call cold-boots the router (model load ~30s when the embedder is
196
- needed) — batch reads, and reach for `--rank ppr` for topic queries in cold
197
- sessions.
262
+ | `okf import [FILE...] [--all] [--prune-missing] [--mode text] [--force]` | Single files / bulk import, delta-aware (`--force` re-attaches a detached graph); TOML `[[roots]]` (or per-call `--root ALIAS=PATH`) add named roots (`@alias/` IDs, unmounted ≠ deleted, `--prune-missing` skips while any root is absent); `--bundle-path DIR` pins one tree for this call |
263
+ | `okf produce --from sqlite --source DB --output-dir DIR` | Generate a bundle from a data source (one concept per table, FK links, `## Observations` notes, `log.md` changelog); lint pre-flighted, CLI-only |
264
+ | `okf detach [--bundle-path DIR] [--no-verify] [--force]` | End the mirror: the DB becomes the artifact (verify-first; imports refuse without `--force`) |
265
+ | `okf init`, `okf model-info`, `okf shell`, `okf reindex`, `okf broken-links`, `okf repair-links`, `okf deleted-*`, `okf delete ID` | Setup, cache inspection, REPL, index rebuild, link + soft-delete maintenance (`delete` refuses file-backed concepts while their source exists) |
266
+
267
+ Only commands that embed text (`search` except `--rank ppr`, `import`,
268
+ `ingest`) load the model (~30s cold per process); `read`, `traverse`,
269
+ `lint`, `diff`, `doctor` and `export` never do — batch searches, use
270
+ `okf shell` for a warm session, and reach for `--rank ppr` for topic
271
+ queries in cold sessions. Omit `--bundle-root` entirely for file-free mode: thoughts ingest,
272
+ search, read, traverse, doctor, and export work from the DB alone (file-side
273
+ ops fail fast naming the missing root). Thought IDs are namespaced
274
+ (`thoughts/<topic>/<ts>_<id>`), so a fileless graph exports into a tidy tree.
198
275
 
199
276
  ---
200
277
 
201
278
  ## MCP server
202
279
 
203
- 5 tools, MCP ≥ 2.0, stdio transport. Wire once per project with a **stable**
204
- `--db-path` + `--bundle` (a temp dir means amnesia every session); first boot
205
- creates the schema; pre-approve the `ingest` / `export_bundle` write tools for
206
- knowledge workflows. `.mcp.json` ships a ready config (`uv run --project .
207
- okf-mcp`).
280
+ 8 tools, MCP ≥ 2.0, stdio transport. Wire once per project with a **stable**
281
+ database — `--db-path`, `OKFGRAPH_DB_PATH` or `[database] db_path` in
282
+ `okfgraph.toml`; the server refuses to boot without one (`CONFIG_INVALID`,
283
+ exit 2) since a temp dir means amnesia every session. `--bundle-root`
284
+ defaults to the database's parent directory. First
285
+ boot creates the schema; pre-approve the `ingest` / `export_bundle` /
286
+ `export_concept` write tools for knowledge workflows. `.mcp.json` ships a
287
+ ready config (`uv run --project . okf-mcp`). Every tool returns the result
288
+ envelope (`{ok, op, data, warnings, error}`); failures raise so the result
289
+ carries `isError: true` with the error envelope as text — never a bare
290
+ traceback.
208
291
 
209
292
  ```bash
210
293
  okf-mcp --db-path ./kb.db --bundle-root ./kb
@@ -215,8 +298,11 @@ okf-mcp --db-path ./kb.db --bundle-root ./kb
215
298
  | `search(query, target?, rank?, …)` | `concepts` = open questions; `chunks` = exact passages (`expand`, `hub_rerank`); `images` = assets; `rank=ppr` = model-free topic search |
216
299
  | `read(concept_id, include?, max_tokens?)` | Full shapes, or a budgeted section list |
217
300
  | `traverse(start_id, relationship?, direction?, target?, …)` | Walk edges, list dirs, connect two concepts |
218
- | `ingest(kind, …)` | `md` / `pdf` / `thoughts` with per-kind params |
301
+ | `ingest(kind, …)` | `md` / `pdf` / `thoughts` / `bib` with per-kind params |
219
302
  | `export_bundle(output_dir, …, flavor?)` | `okf` or `obsidian` |
303
+ | `export_concept(concept_id, output_dir, flavor?)` | Single concept → `<output_dir>/<id>.md` |
304
+ | `list_images(concept_id)` | Image assets on one concept (metadata) |
305
+ | `get_image(asset_id)` | One asset: metadata + base64 `data` |
220
306
 
221
307
  Verify wiring with any `search` — an empty graph returns `[]`, which still
222
308
  proves the plumbing works.
@@ -238,7 +324,7 @@ Harness-neutral skill sources live in `skills/` (Claude Code auto-loads
238
324
  ## Architecture
239
325
 
240
326
  ```
241
- ┌──────────── MCP (5 tools) / CLI (5 verbs + maintenance)
327
+ ┌──────────── MCP (8 tools) / CLI (8 verbs + maintenance)
242
328
  │ │
243
329
  OKFRouter (facade: owns conn, encoder, lock; thin proxies)
244
330
  │
@@ -289,25 +375,40 @@ Key design decisions:
289
375
  - **Bundle is source of truth, graph is the index** — edit markdown,
290
376
  re-import; verify ingests by searching, since empty `[]` proves wiring
291
377
  while errors prove broken setup.
292
- - **MCP-first surface** — CLI mirrors the same 5 verbs; maintenance
293
- (`diff`, `doctor`) is CLI-only to keep the agent tool surface at 5.
378
+ - **MCP-first surface** — CLI mirrors the same verbs; maintenance
379
+ (`diff`, `doctor`) is CLI-only to keep the agent tool surface at 8.
294
380
 
295
381
  ---
296
382
 
297
- ## API reference (`OKFRouter` proxies)
383
+ ## API reference (`OKFRouter` ops)
384
+
385
+ One vocabulary of 24 operations on the facade (mixins `QueryOps`,
386
+ `IngestOps`, `ExportOps`, `AdminOps`); every failure raises
387
+ `OKFError(code, message, fields?, remedy?)` — `UsageError` (exit 2) for
388
+ caller mistakes, `StateError`/`OutcomeError` (exit 1) for graph state and
389
+ domain outcomes (the class always follows the code). Outcome errors
390
+ (`DIFF_DIFFERENT`, `DOCTOR_FINDINGS`, `LINT_ERRORS`) carry the full result
391
+ on `err.data`. A passed param the chosen path ignores is refused with
392
+ `BAD_VALUE` naming it in `fields["ignored"]`.
298
393
 
299
- | Method | Description |
394
+ | Op | Description |
300
395
  |---|---|
301
- | `import_from_okf(file_path, mode?)` / `import_mgr.import_bundle(dir?, batch_size?, mode?, purge_deleted?)` | Single / bulk import |
302
- | `ingest_mgr.ingest_md / ingest_pdf / ingest_thoughts` | Kind-based ingestion with lint + chunk + embed + link |
303
- | `search_hybrid(query, …, rank="none"\|"hub"\|"ppr")` | RRF hybrid; `hub` blends authority, `ppr` is model-free |
304
- | `search_engine.search_with_ppr / read_with_budget / search_chunks / traverse / find_path / get_chunks / get_by_id / list_directory` | Model-free PPR, budgeted reads, retrieval + navigation |
305
- | `embed_engine.reconstruct_document(id)` / `count_tokens(text)` | ~98% chunk→markdown rebuild; Rust counter with chars/4 fallback |
306
- | `export_mgr.export_bundle / export_to_okf(..., flavor="okf"\|"obsidian")` | Filtered export, both flavors |
307
- | `diff_mgr.diff_dirs(old, new)` / `diff_db_dir(bundle_dir)` | Snapshot / drift structural reports |
308
- | `diagnose(stale_days?)` / `doctor_fix()` | Health report / safe repairs |
309
- | `list_broken_links()` / `repair_links(skip_sources?)` | Unresolved refs; exact-id + unique-name repair |
310
- | `model_info(...)` / `default_cache_dir()` | Cache inspection without model load |
396
+ | `search(query, target="concepts", limit?, concept_type?, tags?, parent_id?, include_chunks?, max_chunks_per_doc?, expand?, context_hops?, hub_rerank?, hub_weight?, rank="none"\|"hub"\|"ppr")` | RRF hybrid; `hub` blends authority, `ppr` is model-free; chunk paths: `hub_rerank` > `expand` > plain |
397
+ | `read(concept_id, include="body"\|"chunks"\|"document"\|"context", max_tokens?)` | Concept dict / chunk dicts (no embeddings) / `{"concept_id","markdown"}` / `{incoming_links, outgoing_links, ancestry, siblings}`; or a budgeted `{sections, used, budget, truncated}` |
398
+ | `traverse(start_id, relationship?, direction?, depth?, node_type?, target?, max_path_length?)` | Walk, list (empty id = root), connect |
399
+ | `ingest(kind, …)` | `md` / `pdf` / `thoughts` / `bib`, per-kind params, lint + chunk + embed + link |
400
+ | `import_file(path, mode?) {"concept_id","images"}` / `import_bundle(path?, …, prune_missing?) {"concept_ids","images"}` | Single / whole-bundle delta import |
401
+ | `export_bundle(output_dir, directory_id?, concept_type?, tags?, flavor?) {"concept_ids",…}` / `export_concept(concept_id, output_dir, flavor?) {"path"}` | Both flavors |
402
+ | `list_images(concept_id)` / `get_image(asset_id)` | Image ops (metadata; bytes + base64) |
403
+ | `init() {"db_path","embedding_dim","model_id"}` / `model_info(…)` (static) / `reindex(if_dirty?)` | Schema, cache inspection, index rebuild |
404
+ | `doctor(stale_days?, fix?, strict?) {"report","fixed"}` / `lint(dir)` (static) / `produce(source_type, source_path?, output_dir?, prefix?, overwrite?)` (static) / `diff(old?, new?)` / `diff_dirs(old, new)` (static) | Health, pre-import gate, bundles from sources, structural diff; `strict` findings, lint errors and differences raise outcome errors with the result on `err.data` |
405
+ | `list_deleted()` / `recover_deleted(id)` / `purge_deleted(older_than?)` / `delete(concept_id)` / `detach(bundle_path?, verify?, force?)` | Soft-delete trio + `delete` (refuses file-backed concepts whose source exists — remedy: prune-missing) + mirror lifecycle |
406
+ | `list_broken_links() [{source, target}]` / `repair_links() {"repaired"}` | Unresolved refs; exact-id + unique-name repair |
407
+
408
+ Components remain reachable for advanced use (`search_engine.search_hybrid`,
409
+ `embed_engine.count_tokens`, `export_mgr`, `diff_mgr`, …); the ops are the
410
+ stable surface. `embed_engine.reconstruct_document(id)` stays the ~98%
411
+ chunk→markdown rebuild.
311
412
 
312
413
  ---
313
414
 
@@ -335,20 +436,20 @@ okfgraph/
335
436
  ├── okfgraph/
336
437
  │ ├── __init__.py # ConceptModel, OKFRouter, cli_main
337
438
  │ ├── models.py # ConceptModel / ChunkModel / ImageAssetModel (extra frontmatter allowed)
338
- │ ├── router.py # OKFRouter facade (owns resources, thin proxies)
339
- │ ├── cli.py # okf: 5 verbs + maintenance, slim help, okfgraph.toml
340
- │ ├── mcp_server.py # okf-mcp: 5 tools, MCP ≥ 2.0, lifespan-managed router
341
- │ ├── config.py # okfgraph.toml + env + CLI merge
439
+ │ ├── settings.py # okfgraph.toml + env + CLI merge (per-key precedence, config spellings raise)
440
+ │ ├── errors.py # OKFError(code, fields, remedy) + UsageError / StateError / OutcomeError
441
+ │ ├── router.py # OKFRouter facade = OKFRouter(AdminOps, ExportOps, IngestOps, QueryOps)
442
+ │ ├── ops/ # the 24-op vocabulary: query.py, ingest.py, export.py, admin.py
443
+ │ ├── cli.py # okf: 8 core verbs + maintenance + images/image, --json (D5/D6)
444
+ │ ├── mcp_server.py # okf-mcp: 8 tools, MCP ≥ 2.0, lifespan-managed router, envelope/_ToolFailure
342
445
  │ ├── images.py # IngestMode (text + vision-onnx since 0.8.0), planning helpers
343
446
  │ ├── security.py # SSRF/domain guards for remote images
344
- │ ├── tools.py # legacy tool definitions (superseded by mcp_server)
345
447
  │ └── components/ # ranking, links, search, lint, import_, export, diff, doctor,
346
448
  │ # embedding, converters, image_assets, delta, purge, schema, ingest
347
449
  ├── skills/ # okfgraph-mcp, okfgraph-cli, okfgraph-ingest (harness-neutral source)
348
450
  ├── tests/fixtures/ # conformance corpus: ppr, diff, doctor, obsidian, bundles
349
- ├── docs/ # converters, harness-integration, plan-retrieval-roundup, diagnostics…
451
+ ├── docs/ # architecture spec (v6.5), converters, chunking, harness guides; archive/ holds completed plans
350
452
  ├── .mcp.json # ready MCP wiring (uv run --project . okf-mcp)
351
- ├── architecture.md # long-form architecture spec (v6.5, as-built for 0.8.x)
352
453
  └── pyproject.toml # slim core deps + pdf/dev extras
353
454
  ```
354
455
 
@@ -356,7 +457,7 @@ okfgraph/
356
457
 
357
458
  ## Requirements
358
459
 
359
- Core (`uv sync`): `ladybug==0.21.2`, `embroider>=0.3,<0.4` (PyPI wheels,
460
+ Core (`uv sync`): `ladybug==0.21.2`, `embroider>=0.3.2,<0.4` (PyPI wheels,
360
461
  github.com/opticsWolf/embroider), `mordant>=0.9`,
361
462
  `mcp>=2.0`, `pydantic>=2`, `pyyaml>=6`,
362
463
  `numpy>=1.26`, `python-frontmatter>=1`, `fasteners>=0.19`. Python ≥ 3.11.
@@ -364,7 +465,7 @@ Plus exactly one ORT provider: `okfgraph[cpu]` (`onnxruntime==1.29.0`)
364
465
  or `okfgraph[gpu]` (`onnxruntime-gpu[cuda,cudnn]==1.29.0`) — shared with
365
466
  bobine via `ORT_DYLIB_PATH`.
366
467
 
367
- - `--extra pdf`: `bobine>=0.5` (default PDF converter).
468
+ - `--extra pdf`: `bobine>=0.6` (default PDF converter).
368
469
  - `--extra dev`: `pytest>=8`.
369
470
 
370
471
  ---