Metadata-Version: 2.4
Name: okf-retrieve
Version: 0.1.0
Summary: MCP-first agent retrieval over Open Knowledge Format (OKF) bundles.
Project-URL: Homepage, https://github.com/saikumar-geek/okf
Project-URL: Issues, https://github.com/saikumar-geek/okf/issues
Author: Sai Kumar
License: MIT
License-File: LICENSE
Keywords: agents,llm,mcp,okf,open-knowledge-format,rag,retrieval
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: agent
Requires-Dist: anthropic>=0.40; extra == 'agent'
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: numpy>=1.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == 'mcp'
Provides-Extra: semantic
Requires-Dist: numpy>=1.24; extra == 'semantic'
Requires-Dist: sentence-transformers>=2.2; extra == 'semantic'
Requires-Dist: voyageai>=0.2; extra == 'semantic'
Description-Content-Type: text/markdown

# okf

**Mount any [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle as a retrievable knowledge source for LLM agents — over MCP.**

OKF (announced by Google Cloud, June 2026) represents organizational knowledge
as a directory of markdown files with YAML frontmatter. The format was designed
for agent **progressive disclosure**: `index.md` listings, structured
`type`/`tags` frontmatter, and a resolvable cross-document link graph.

`okf` turns a bundle into agent-ready retrieval. Point an MCP-capable agent
(Claude Code, Claude Desktop, or the Messages API) at a bundle and it searches
for stubs, fetches bodies, and walks the link graph on demand — instead of you
flattening every doc into the context window.

```bash
pip install "okf-retrieve[mcp]"
okf serve-mcp ./sales          # serve the bundle to any agent over MCP (stdio)
```

## Why MCP-first

The OKF link graph and frontmatter are exactly what an agent needs to *navigate*
knowledge rather than be handed a wall of text. `okf` exposes that as four tools:

| Tool | Returns |
|------|---------|
| `search(query, type?, tags?, limit?)` | ranked document **stubs** (path, type, title, description) — not full bodies |
| `get(path)` | one document's full content |
| `neighbors(path, hops?)` | documents linked from/to a document (graph expansion) |
| `list_types()` / `list_by_type(type)` | structured browse |

`search` deliberately returns stubs so the agent decides what to read — the
progressive-disclosure pattern OKF was built for.

### Use it from Claude Code / Desktop

Add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):

```json
{
  "mcpServers": {
    "okf-sales": {
      "command": "okf",
      "args": ["serve-mcp", "/abs/path/to/sales"]
    }
  }
}
```

### Use it from the Messages API

Run `okf serve-mcp ./sales --transport streamable-http`, then reference it with
`mcp_servers` + `mcp_toolset` (beta `mcp-client-2025-11-20`) on
`client.beta.messages.create(...)`.

## Library

The same retrieval is available directly in Python:

```python
from okf import Bundle, StructuredRetriever, GraphExpandedRetriever, pack

bundle = Bundle.load("./sales")

doc = bundle["tables/orders.md"]
doc.type                       # "BigQuery Table"
doc.links                      # resolved internal links -> [Doc(customers), ...]
bundle.neighbors(doc, hops=2)  # graph expansion

# Keyword (BM25) retrieval with frontmatter filtering — no embeddings needed
hits = StructuredRetriever(bundle).search("weekly active users", type="Metric")

# Graph-expanded retrieval: surface structurally-related docs the query missed
graph = GraphExpandedRetriever(StructuredRetriever(bundle), bundle, hops=1)
hits = graph.search("weekly active users")

# Token-budgeted, citable context block, ready to drop into a prompt
ctx = pack(hits, max_tokens=4000)
ctx.text          # assembled markdown
ctx.citations     # ["metrics/weekly_active_users.md", ...]
```

### Semantic (vector) retrieval

```python
from okf import Bundle, SemanticRetriever
from okf.retrieve import VoyageEmbedder      # or SentenceTransformerEmbedder

bundle = Bundle.load("./sales")
retriever = SemanticRetriever(bundle, VoyageEmbedder())  # set VOYAGE_API_KEY
hits = retriever.search("which table has revenue per order")
```

Anthropic's Claude API has no embeddings endpoint, so the embedder is
pluggable. The `[semantic]` extra ships **Voyage AI** (Anthropic's recommended
embedding partner) and **sentence-transformers** (offline, no API key). Any
object with `embed_documents` / `embed_query` works. Wrap a `SemanticRetriever`
in `GraphExpandedRetriever` for vector + graph retrieval.

## CLI

```bash
okf validate ./sales                 # lint against the OKF spec (exit 1 on errors)
okf search ./sales "orders"          # keyword (BM25) search
okf search ./sales "orders" --graph  # + graph expansion
okf search ./sales "orders" --semantic  # vector search (OKF_EMBEDDER=voyage|local)
okf graph ./sales --json             # emit the resolved link graph
okf serve-mcp ./sales                # serve the bundle as an MCP tool server
```

## Install

```bash
pip install okf-retrieve              # core: model + graph + BM25 retrieval + CLI (PyYAML only)
pip install "okf-retrieve[mcp]"       # + MCP server
pip install "okf-retrieve[semantic]"  # + vector retrieval (numpy, Voyage, sentence-transformers)
```

Requires Python 3.10+. The distribution is `okf-retrieve`; you still `import okf`.

## Status

`0.1.0`, early alpha. Implemented: bundle model + link graph, validation,
BM25 / semantic / graph-expanded retrieval, context packing, the MCP server,
and the CLI. Roadmap: a reference Claude agent, pluggable vector stores, and
bundle generators.

## Related projects

The OKF tooling space is young. [`okf-toolkit`](https://github.com/akdira/okf-toolkit)
covers init/validate/search as a CLI; [`py-okf`](https://github.com/prabhay759/py-okf)
generates bundles from Python code; [`hermes-okf`](https://github.com/EliaszDev/hermes-okf)
is an agent-memory layer. `okf` focuses specifically on the **agent-native
retrieval surface (MCP)**.

## License

MIT
