okf-wiki-kit 0.2.0__tar.gz

okf_wiki_kit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 okf-wiki-kit contributors
+
+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.

okf_wiki_kit-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: okf-wiki-kit
+Version: 0.2.0
+Summary: Build Open-Knowledge-Format (OKF) / Obsidian LLM wikis from any source material.
+Author: okf-wiki-kit contributors
+License: MIT
+Project-URL: Homepage, https://github.com/olivermorgan2/okf-wiki-kit
+Project-URL: Issues, https://github.com/olivermorgan2/okf-wiki-kit/issues
+Project-URL: Repository, https://github.com/olivermorgan2/okf-wiki-kit
+Keywords: okf,obsidian,knowledge-graph,llm,rag,wiki,markdown
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == "openai"
+Provides-Extra: rag
+Requires-Dist: numpy>=1.24; extra == "rag"
+Provides-Extra: voyage
+Requires-Dist: voyageai>=0.3; extra == "voyage"
+Provides-Extra: local-embeddings
+Requires-Dist: numpy>=1.24; extra == "local-embeddings"
+Requires-Dist: model2vec>=0.3; extra == "local-embeddings"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# okf-wiki-kit
+
+Build a cross-linked **[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
+(OKF)** knowledge wiki — browsable in **Obsidian** and consumable by **LLMs/agents** — from *any*
+source material.
+
+OKF represents knowledge as a directory of markdown files: each file is a typed node with YAML
+frontmatter (only `type` is required) and `[[wikilinks]]` that form a knowledge graph richer than
+the folder hierarchy. `okf-wiki-kit` gives you a small, dependency-light engine that turns your
+content into such a bundle, with optional LLM enrichment.
+
+## How it works
+
+```
+your source ──► SourceAdapter.load() ──► [Node, Node, …] ──► engine ──► OKF/Obsidian vault
+                (you write ~40 lines,        (normalized)      (generic: frontmatter, wikilinks,
+                 or use a built-in one)                          indexes, link-inference, validate)
+```
+
+You implement **one method** — `load() -> Iterable[Node]` — that turns your source into a list of
+`Node`s. The engine does everything else: unique filenames, frontmatter, wikilinks, per-type and
+root `index.md` files, optional mention-based link inference, validation, and optional LLM
+enrichment.
+
+## Quickstart (zero code)
+
+Point the built-in *markdown-folder* adapter at any folder of `.md` files:
+
+```bash
+pip install -e .                     # or: pip install okf-wiki-kit
+cp okf.config.example.yaml okf.config.yaml
+# edit okf.config.yaml -> adapter_options.path: ./my-notes
+okf build                            # writes ./vault
+okf validate                         # every node typed, every wikilink resolves
+```
+
+Open the `./vault` folder in Obsidian and look at the Graph View.
+
+## Optional: LLM enrichment
+
+```bash
+pip install -e ".[openai]"           # or ".[anthropic]"
+export OPENROUTER_API_KEY=...        # or ANTHROPIC_API_KEY
+okf enrich                           # writes enrichment.json (canonical concepts + descriptions)
+okf build                            # rebuild, applying the enrichment
+```
+
+Enrichment is **provider-flexible**: Anthropic (`claude-sonnet-4-6`) or any OpenAI-compatible
+endpoint such as **OpenRouter** (`qwen/qwen3.7-plus`). Provider is auto-detected from your env keys.
+
+## Writing your own adapter
+
+For structured sources (JSON, a database, a CMS), write a small adapter:
+
+```python
+from okfkit.model import Node, Link
+from okfkit.adapters.base import SourceAdapter
+
+class MyAdapter(SourceAdapter):
+    def load(self):
+        for row in my_source():
+            yield Node(
+                id=row["slug"], type="Article", title=row["title"],
+                body=row["markdown"],
+                frontmatter={"author": row["author"]},
+                links=[Link(target=t, rel="related", section="See also")
+                       for t in row["related_slugs"]],
+                tags=row["tags"],
+            )
+```
+
+Point `okf.config.yaml` at it: `adapter: path/to/my_adapter.py:MyAdapter`. See
+[`docs/writing-an-adapter.md`](docs/writing-an-adapter.md) and the worked example in
+[`examples/textbook/`](examples/textbook/).
+
+## The `Node` model
+
+| field | meaning |
+|-------|---------|
+| `id` | stable unique id → becomes the filename / wikilink target |
+| `type` | OKF `type:` value (required) — `"Chapter"`, `"Concept"`, or anything you invent |
+| `title` | human-readable name (wikilink display) |
+| `body` | markdown body (no frontmatter) |
+| `frontmatter` | any extra YAML fields (may contain `[[wikilinks]]`) |
+| `links` | edges to other nodes; each `Link(target, rel, section)` renders under a `## section` heading |
+| `tags`, `aliases` | Obsidian-native tags and aliases |
+
+## Use with Claude Code / Claude Desktop
+
+Serve a built vault as a read-only MCP server so agents can query it as tools:
+
+```bash
+pip install -e ".[mcp]"
+claude mcp add okf-wiki -- okf serve -c /abs/path/okf.config.yaml
+```
+
+The server exposes five read-only tools: `okf_vault_info` (orientation — call first),
+`okf_search` (semantic; needs a prior `okf index`), `okf_list_notes` (browse/paginate by type or
+tag), `okf_get_note` (full note with links and backlinks), and `okf_neighbors` (walk the link
+graph). The graph tools need no API keys. Use `okf serve --vault /abs/path/vault` to serve any
+OKF vault without a config, and `--no-rag` for graph tools only.
+
+## Roadmap
+
+- **Build** — engine, markdown-folder adapter, custom adapters, link inference, LLM enrichment, CLI.
+- **Semantic RAG (Phase 7) ✓** — `okf index` / `okf search` / `okf ask`: embeddings index + retrieval-augmented Q&A.
+- **MCP server (Phase 8) ✓** — `okf serve`: expose the vault as read-only tools for Claude Code / Desktop / any MCP client.
+
+See [`docs/roadmap.md`](docs/roadmap.md) for details.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

okf_wiki_kit-0.2.0/README.md

@@ -0,0 +1,113 @@
+# okf-wiki-kit
+
+Build a cross-linked **[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
+(OKF)** knowledge wiki — browsable in **Obsidian** and consumable by **LLMs/agents** — from *any*
+source material.
+
+OKF represents knowledge as a directory of markdown files: each file is a typed node with YAML
+frontmatter (only `type` is required) and `[[wikilinks]]` that form a knowledge graph richer than
+the folder hierarchy. `okf-wiki-kit` gives you a small, dependency-light engine that turns your
+content into such a bundle, with optional LLM enrichment.
+
+## How it works
+
+```
+your source ──► SourceAdapter.load() ──► [Node, Node, …] ──► engine ──► OKF/Obsidian vault
+                (you write ~40 lines,        (normalized)      (generic: frontmatter, wikilinks,
+                 or use a built-in one)                          indexes, link-inference, validate)
+```
+
+You implement **one method** — `load() -> Iterable[Node]` — that turns your source into a list of
+`Node`s. The engine does everything else: unique filenames, frontmatter, wikilinks, per-type and
+root `index.md` files, optional mention-based link inference, validation, and optional LLM
+enrichment.
+
+## Quickstart (zero code)
+
+Point the built-in *markdown-folder* adapter at any folder of `.md` files:
+
+```bash
+pip install -e .                     # or: pip install okf-wiki-kit
+cp okf.config.example.yaml okf.config.yaml
+# edit okf.config.yaml -> adapter_options.path: ./my-notes
+okf build                            # writes ./vault
+okf validate                         # every node typed, every wikilink resolves
+```
+
+Open the `./vault` folder in Obsidian and look at the Graph View.
+
+## Optional: LLM enrichment
+
+```bash
+pip install -e ".[openai]"           # or ".[anthropic]"
+export OPENROUTER_API_KEY=...        # or ANTHROPIC_API_KEY
+okf enrich                           # writes enrichment.json (canonical concepts + descriptions)
+okf build                            # rebuild, applying the enrichment
+```
+
+Enrichment is **provider-flexible**: Anthropic (`claude-sonnet-4-6`) or any OpenAI-compatible
+endpoint such as **OpenRouter** (`qwen/qwen3.7-plus`). Provider is auto-detected from your env keys.
+
+## Writing your own adapter
+
+For structured sources (JSON, a database, a CMS), write a small adapter:
+
+```python
+from okfkit.model import Node, Link
+from okfkit.adapters.base import SourceAdapter
+
+class MyAdapter(SourceAdapter):
+    def load(self):
+        for row in my_source():
+            yield Node(
+                id=row["slug"], type="Article", title=row["title"],
+                body=row["markdown"],
+                frontmatter={"author": row["author"]},
+                links=[Link(target=t, rel="related", section="See also")
+                       for t in row["related_slugs"]],
+                tags=row["tags"],
+            )
+```
+
+Point `okf.config.yaml` at it: `adapter: path/to/my_adapter.py:MyAdapter`. See
+[`docs/writing-an-adapter.md`](docs/writing-an-adapter.md) and the worked example in
+[`examples/textbook/`](examples/textbook/).
+
+## The `Node` model
+
+| field | meaning |
+|-------|---------|
+| `id` | stable unique id → becomes the filename / wikilink target |
+| `type` | OKF `type:` value (required) — `"Chapter"`, `"Concept"`, or anything you invent |
+| `title` | human-readable name (wikilink display) |
+| `body` | markdown body (no frontmatter) |
+| `frontmatter` | any extra YAML fields (may contain `[[wikilinks]]`) |
+| `links` | edges to other nodes; each `Link(target, rel, section)` renders under a `## section` heading |
+| `tags`, `aliases` | Obsidian-native tags and aliases |
+
+## Use with Claude Code / Claude Desktop
+
+Serve a built vault as a read-only MCP server so agents can query it as tools:
+
+```bash
+pip install -e ".[mcp]"
+claude mcp add okf-wiki -- okf serve -c /abs/path/okf.config.yaml
+```
+
+The server exposes five read-only tools: `okf_vault_info` (orientation — call first),
+`okf_search` (semantic; needs a prior `okf index`), `okf_list_notes` (browse/paginate by type or
+tag), `okf_get_note` (full note with links and backlinks), and `okf_neighbors` (walk the link
+graph). The graph tools need no API keys. Use `okf serve --vault /abs/path/vault` to serve any
+OKF vault without a config, and `--no-rag` for graph tools only.
+
+## Roadmap
+
+- **Build** — engine, markdown-folder adapter, custom adapters, link inference, LLM enrichment, CLI.
+- **Semantic RAG (Phase 7) ✓** — `okf index` / `okf search` / `okf ask`: embeddings index + retrieval-augmented Q&A.
+- **MCP server (Phase 8) ✓** — `okf serve`: expose the vault as read-only tools for Claude Code / Desktop / any MCP client.
+
+See [`docs/roadmap.md`](docs/roadmap.md) for details.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

okf_wiki_kit-0.2.0/okf_wiki_kit.egg-info/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: okf-wiki-kit
+Version: 0.2.0
+Summary: Build Open-Knowledge-Format (OKF) / Obsidian LLM wikis from any source material.
+Author: okf-wiki-kit contributors
+License: MIT
+Project-URL: Homepage, https://github.com/olivermorgan2/okf-wiki-kit
+Project-URL: Issues, https://github.com/olivermorgan2/okf-wiki-kit/issues
+Project-URL: Repository, https://github.com/olivermorgan2/okf-wiki-kit
+Keywords: okf,obsidian,knowledge-graph,llm,rag,wiki,markdown
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == "openai"
+Provides-Extra: rag
+Requires-Dist: numpy>=1.24; extra == "rag"
+Provides-Extra: voyage
+Requires-Dist: voyageai>=0.3; extra == "voyage"
+Provides-Extra: local-embeddings
+Requires-Dist: numpy>=1.24; extra == "local-embeddings"
+Requires-Dist: model2vec>=0.3; extra == "local-embeddings"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# okf-wiki-kit
+
+Build a cross-linked **[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
+(OKF)** knowledge wiki — browsable in **Obsidian** and consumable by **LLMs/agents** — from *any*
+source material.
+
+OKF represents knowledge as a directory of markdown files: each file is a typed node with YAML
+frontmatter (only `type` is required) and `[[wikilinks]]` that form a knowledge graph richer than
+the folder hierarchy. `okf-wiki-kit` gives you a small, dependency-light engine that turns your
+content into such a bundle, with optional LLM enrichment.
+
+## How it works
+
+```
+your source ──► SourceAdapter.load() ──► [Node, Node, …] ──► engine ──► OKF/Obsidian vault
+                (you write ~40 lines,        (normalized)      (generic: frontmatter, wikilinks,
+                 or use a built-in one)                          indexes, link-inference, validate)
+```
+
+You implement **one method** — `load() -> Iterable[Node]` — that turns your source into a list of
+`Node`s. The engine does everything else: unique filenames, frontmatter, wikilinks, per-type and
+root `index.md` files, optional mention-based link inference, validation, and optional LLM
+enrichment.
+
+## Quickstart (zero code)
+
+Point the built-in *markdown-folder* adapter at any folder of `.md` files:
+
+```bash
+pip install -e .                     # or: pip install okf-wiki-kit
+cp okf.config.example.yaml okf.config.yaml
+# edit okf.config.yaml -> adapter_options.path: ./my-notes
+okf build                            # writes ./vault
+okf validate                         # every node typed, every wikilink resolves
+```
+
+Open the `./vault` folder in Obsidian and look at the Graph View.
+
+## Optional: LLM enrichment
+
+```bash
+pip install -e ".[openai]"           # or ".[anthropic]"
+export OPENROUTER_API_KEY=...        # or ANTHROPIC_API_KEY
+okf enrich                           # writes enrichment.json (canonical concepts + descriptions)
+okf build                            # rebuild, applying the enrichment
+```
+
+Enrichment is **provider-flexible**: Anthropic (`claude-sonnet-4-6`) or any OpenAI-compatible
+endpoint such as **OpenRouter** (`qwen/qwen3.7-plus`). Provider is auto-detected from your env keys.
+
+## Writing your own adapter
+
+For structured sources (JSON, a database, a CMS), write a small adapter:
+
+```python
+from okfkit.model import Node, Link
+from okfkit.adapters.base import SourceAdapter
+
+class MyAdapter(SourceAdapter):
+    def load(self):
+        for row in my_source():
+            yield Node(
+                id=row["slug"], type="Article", title=row["title"],
+                body=row["markdown"],
+                frontmatter={"author": row["author"]},
+                links=[Link(target=t, rel="related", section="See also")
+                       for t in row["related_slugs"]],
+                tags=row["tags"],
+            )
+```
+
+Point `okf.config.yaml` at it: `adapter: path/to/my_adapter.py:MyAdapter`. See
+[`docs/writing-an-adapter.md`](docs/writing-an-adapter.md) and the worked example in
+[`examples/textbook/`](examples/textbook/).
+
+## The `Node` model
+
+| field | meaning |
+|-------|---------|
+| `id` | stable unique id → becomes the filename / wikilink target |
+| `type` | OKF `type:` value (required) — `"Chapter"`, `"Concept"`, or anything you invent |
+| `title` | human-readable name (wikilink display) |
+| `body` | markdown body (no frontmatter) |
+| `frontmatter` | any extra YAML fields (may contain `[[wikilinks]]`) |
+| `links` | edges to other nodes; each `Link(target, rel, section)` renders under a `## section` heading |
+| `tags`, `aliases` | Obsidian-native tags and aliases |
+
+## Use with Claude Code / Claude Desktop
+
+Serve a built vault as a read-only MCP server so agents can query it as tools:
+
+```bash
+pip install -e ".[mcp]"
+claude mcp add okf-wiki -- okf serve -c /abs/path/okf.config.yaml
+```
+
+The server exposes five read-only tools: `okf_vault_info` (orientation — call first),
+`okf_search` (semantic; needs a prior `okf index`), `okf_list_notes` (browse/paginate by type or
+tag), `okf_get_note` (full note with links and backlinks), and `okf_neighbors` (walk the link
+graph). The graph tools need no API keys. Use `okf serve --vault /abs/path/vault` to serve any
+OKF vault without a config, and `--no-rag` for graph tools only.
+
+## Roadmap
+
+- **Build** — engine, markdown-folder adapter, custom adapters, link inference, LLM enrichment, CLI.
+- **Semantic RAG (Phase 7) ✓** — `okf index` / `okf search` / `okf ask`: embeddings index + retrieval-augmented Q&A.
+- **MCP server (Phase 8) ✓** — `okf serve`: expose the vault as read-only tools for Claude Code / Desktop / any MCP client.
+
+See [`docs/roadmap.md`](docs/roadmap.md) for details.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

okf_wiki_kit-0.2.0/okf_wiki_kit.egg-info/SOURCES.txt

@@ -0,0 +1,29 @@
+LICENSE
+README.md
+pyproject.toml
+okf_wiki_kit.egg-info/PKG-INFO
+okf_wiki_kit.egg-info/SOURCES.txt
+okf_wiki_kit.egg-info/dependency_links.txt
+okf_wiki_kit.egg-info/entry_points.txt
+okf_wiki_kit.egg-info/requires.txt
+okf_wiki_kit.egg-info/top_level.txt
+okfkit/__init__.py
+okfkit/cli.py
+okfkit/config.py
+okfkit/engine.py
+okfkit/enrich.py
+okfkit/model.py
+okfkit/render.py
+okfkit/adapters/__init__.py
+okfkit/adapters/base.py
+okfkit/adapters/markdown_folder.py
+okfkit/serve/__init__.py
+okfkit/serve/embeddings.py
+okfkit/serve/mcp.py
+okfkit/serve/rag.py
+okfkit/serve/vault.py
+tests/test_adapters.py
+tests/test_engine.py
+tests/test_render.py
+tests/test_serve_mcp.py
+tests/test_serve_rag.py

okf_wiki_kit-0.2.0/okf_wiki_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

okf_wiki_kit-0.2.0/okf_wiki_kit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+okf = okfkit.cli:main

okf_wiki_kit-0.2.0/okf_wiki_kit.egg-info/requires.txt

@@ -0,0 +1,23 @@
+PyYAML>=6.0
+
+[anthropic]
+anthropic>=0.40
+
+[dev]
+pytest>=7.0
+
+[local-embeddings]
+numpy>=1.24
+model2vec>=0.3
+
+[mcp]
+mcp>=1.2
+
+[openai]
+openai>=1.40
+
+[rag]
+numpy>=1.24
+
+[voyage]
+voyageai>=0.3

okf_wiki_kit-0.2.0/okf_wiki_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+okfkit

okf_wiki_kit-0.2.0/okfkit/__init__.py

@@ -0,0 +1,6 @@
+"""okf-wiki-kit — build OKF/Obsidian LLM wikis from any source material."""
+
+from okfkit.model import Node, Link
+
+__version__ = "0.2.0"
+__all__ = ["Node", "Link"]

okf_wiki_kit-0.2.0/okfkit/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Source adapters — turn a specific source into `Node`s.
+
+Built-in adapters are resolved by short name (e.g. "markdown_folder"). Custom
+adapters are resolved by "path/to/file.py:ClassName".
+"""
+
+from okfkit.adapters.base import SourceAdapter, load_adapter
+
+__all__ = ["SourceAdapter", "load_adapter"]

okf_wiki_kit-0.2.0/okfkit/adapters/base.py

@@ -0,0 +1,66 @@
+"""The SourceAdapter contract and the resolver that loads one by name/path."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from okfkit.model import Node
+
+# short name -> "module:Class" for built-in adapters
+BUILTINS = {
+    "markdown_folder": "okfkit.adapters.markdown_folder:MarkdownFolderAdapter",
+}
+
+
+class SourceAdapter(ABC):
+    """Subclass this and implement `load()`. That is the entire contract.
+
+    Options from `okf.config.yaml`'s `adapter_options:` are passed as keyword
+    arguments and stored on `self.options`.
+    """
+
+    def __init__(self, **options):
+        self.options = options
+
+    @abstractmethod
+    def load(self) -> Iterable[Node]:
+        """Yield (or return a list of) `Node`s built from the source."""
+        raise NotImplementedError
+
+
+def load_adapter(spec: str, options: dict | None = None) -> SourceAdapter:
+    """Instantiate an adapter from a built-in name or a "path.py:Class" / "module:Class" spec."""
+    options = options or {}
+    if spec in BUILTINS:
+        spec = BUILTINS[spec]
+    if ":" not in spec:
+        raise ValueError(
+            f"Adapter spec {spec!r} must be a built-in name ({', '.join(BUILTINS)}) "
+            f"or 'module_or_path:ClassName'."
+        )
+    target, class_name = spec.rsplit(":", 1)
+
+    if target.endswith(".py") or os.path.sep in target or os.path.exists(target):
+        module = _import_from_path(target)
+    else:
+        module = importlib.import_module(target)
+
+    cls = getattr(module, class_name, None)
+    if cls is None or not (isinstance(cls, type) and issubclass(cls, SourceAdapter)):
+        raise ValueError(f"{class_name!r} in {target!r} is not a SourceAdapter subclass.")
+    return cls(**options)
+
+
+def _import_from_path(path: str):
+    path = os.path.abspath(os.path.expanduser(path))
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"Adapter file not found: {path}")
+    name = "okfkit_adapter_" + os.path.splitext(os.path.basename(path))[0]
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module

okf_wiki_kit-0.2.0/okfkit/adapters/markdown_folder.py

@@ -0,0 +1,48 @@
+"""Built-in zero-code adapter: turn a folder of markdown files into OKF nodes.
+
+Each `.md` file becomes one node. `type`, `title`, `tags`, and `aliases` are read
+from YAML frontmatter if present (falling back to sensible defaults). The file's
+existing inline `[[wikilinks]]` are left in the body untouched — filenames are
+preserved as node ids so those links keep resolving.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from okfkit import render
+from okfkit.adapters.base import SourceAdapter
+from okfkit.model import Node
+
+
+class MarkdownFolderAdapter(SourceAdapter):
+    def load(self):
+        root = Path(self.options.get("path", ".")).expanduser()
+        if not root.is_dir():
+            raise NotADirectoryError(f"markdown_folder: path is not a directory: {root}")
+        default_type = self.options.get("default_type", "Note")
+
+        for f in sorted(root.glob("**/*.md")):
+            if f.name.lower() == "readme.md":
+                continue
+            fm, body = render.split_frontmatter(f.read_text(encoding="utf-8"))
+            node_id = str(fm.get("id") or f.stem)      # preserve filename → inline links resolve
+            yield Node(
+                id=node_id,
+                type=str(fm.get("type") or default_type),
+                title=str(fm.get("title") or f.stem),
+                body=body.strip(),
+                frontmatter={k: v for k, v in fm.items()
+                             if k not in ("id", "title", "type", "tags", "aliases")},
+                links=[],   # inline [[wikilinks]] already live in the body
+                tags=_as_list(fm.get("tags")),
+                aliases=_as_list(fm.get("aliases")),
+            )
+
+
+def _as_list(v):
+    if v is None:
+        return []
+    if isinstance(v, (list, tuple)):
+        return [str(x) for x in v]
+    return [str(v)]