okf-agents: Instructions file for Codex

AGENTS.md — okf-agents

This file is for AI coding agents (Cursor, Claude Code, Codex, Copilot, etc.) that are writing code using the okf-agents library. Follow these instructions exactly.

What this library does

okf-agents connects OKF (Open Knowledge Format) Markdown bundles to LangGraph/LangChain. An OKF bundle is a directory of .md files with YAML frontmatter. This library parses them, builds a link graph, and exposes typed LangChain tools, retrievers, a router, and a navigator subgraph.

Install

pip install okf-agents

Public exports

Everything is importable from the top-level package:

from okf_agents import (
    OKFBundle,
    Concept, ConceptFrontmatter, LinkEdge, BundleIndex, SyncResult,
    create_okf_tools,
    OKFRetriever, OKFGraphRetriever,
    create_okf_router,
    create_okf_navigator,
    sync_bundle_to_vector_store,
    OKFError, BundleNotFoundError, BundleValidationError,
    ConceptNotFoundError, LinkResolutionError,  # LinkResolutionError is deprecated, never raised
)

Do NOT import from submodules like okf_agents.bundle or okf_agents.models. Always import from okf_agents.

create_okf_tools, create_okf_router, create_okf_navigator, OKFRetriever, and OKFGraphRetriever all validate their bundle argument eagerly and raise immediately (TypeError, or pydantic.ValidationError for the two retrievers) if it is not an OKFBundle — they never wait until first use to fail.

Patterns

Pattern 1: Load a bundle

from okf_agents import OKFBundle

bundle = OKFBundle.load("path/to/bundle")
concept = bundle.get("concepts/orders")
results = bundle.search("customer", top_k=5)

OKFBundle.load() takes a str | Path. It eagerly parses all .md files on init. The bundle is immutable after loading.

Pattern 2: Create agent tools

from okf_agents import OKFBundle, create_okf_tools

bundle = OKFBundle.load("path/to/bundle")
tools = create_okf_tools(bundle)
# Returns 4 tools: read_concept, search_concepts, list_links, read_index
# Pass `tools` to any LangChain/LangGraph tool-calling agent.