Okf Generator

OKF Generator & Lookup Skill

Generates structured OKF v0.2 knowledge bundles from codebases (18 languages via tree-sitter AST + stdlib ast), and provides fast concept lookup for AI agents like OpenCode.

Pipeline Overview

Copy code
codebase
   |
   v
okf generate  -->  okf_bundle/          (domain/resource-path layout)
                       |
                okf lookup               (zero-LLM concept search)
                       |
                okf pairs          -->  okf_pairs.jsonl  (training data)

CLI Reference

All features via single okf CLI (installed from PyPI).

Dependencies

bashCopy code
pip install okf-generator
# With LLM enrichment:
pip install "okf-generator[llm]"

Task: Generate OKF Bundle

When: user says "index my codebase", "generate OKF bundle", "extract knowledge from code"

Static extraction (no LLM — always run this first)

bashCopy code
okf generate <source_dir> <output_dir>

With LLM enrichment (fills missing docstrings and descriptions)

Configure enrichment in .okfconfig (JSON), then run:

bashCopy code
okf generate <source_dir> <output_dir> --enrich
# or run enrichment standalone on an existing bundle:
okf enrich <output_dir>

jsoncCopy code
// .okfconfig
{
  "llm": { "enabled": true, "base_url": "http://localhost:8080/v1", "api_key": "llamabarn" },
  "providers": {
    "default": { "model": "ggml-org/gemma-3-4b-it-qat-GGUF:Q4_0", "max_workers": 2 }
  }
}

Enrichment is resumable — rerun safely if interrupted. Already-enriched concepts are skipped automatically (checks disk on every run).

Output layout (mirrors source tree)

Copy code
okf_bundle/
├── SUMMARY.md              <- bird's-eye view for AI agents
├── index.md                <- root index
├── log.md                  <- generation history
└── <domain>/
    └── <module>/
        ├── index.md        <- lists all concepts in folder
        ├── <module>.md     <- Module concept
        └── <ClassName>.md  <- Class / Function concepts

Task: Look Up a Concept

When: user asks "what does X do", "find class X", "look up X", or needs to prime OpenCode with exact concept context before editing code.

bashCopy code
# Full detail — signature, docstring, params, returns, related
okf lookup WorldBankConnector

# All concepts from one source file
okf lookup --file StockAI/RnD/python/connectors/economic_data.py

# Filter by type
okf lookup --type Class connector

# Filter by tag
okf lookup --tag lang:python --tag type:Function fetch

# Compact list (many results)
okf lookup --compact connector

# JSON output (programmatic / agent use)
okf lookup --json WorldBankConnector

# Custom bundle path
okf lookup --bundle ./Knowlege/okf_bundle WorldBankConnector

Default bundle path: ./okf_bundle. Also auto-tries ./Knowlege/okf_bundle and ./knowledge/okf_bundle.

Task: Generate Training Pairs

When: user wants JSONL training data from the OKF bundle.

bashCopy code
# Static only (instant, no LLM)
SKIP_SYNTH=1 okf pairs <bundle_dir> output.jsonl

# With LLM (QA, doc, summarize pairs)
SYNTH_BASE_URL="http://localhost:8080/v1" \
SYNTH_API_KEY="llamabarn" \
SYNTH_MODEL="ggml-org/gemma-3-4b-it-qat-GGUF:Q4_0" \
MAX_WORKERS=2 \
QA_PER_CONCEPT=3 \
okf pairs <bundle_dir> output.jsonl

# Specific pair types only
PAIR_TYPES="codegen,qa" okf pairs <bundle_dir> output.jsonl

Pair types

Task: Regenerate SUMMARY.md Only

bashCopy code
okf summarize <bundle_dir>

Use after enrichment finishes to refresh the summary without re-scanning.

OpenCode Integration

See references/opencode-integration.md for full setup.

Quick setup:

bashCopy code
# 1. Add to AGENTS.md (auto-loaded by OpenCode)
echo "OKF bundle at ./okf_bundle — use: okf lookup <Name>" >> AGENTS.md

# 2. Add lookup command
mkdir -p .opencode/commands
echo "RUN okf lookup --bundle ./okf_bundle \$NAME" \
  > .opencode/commands/lookup.md

Supported Languages

Troubleshooting

No concepts found: Check that source dir is not inside a SKIP_DIRS name (node_modules, .venv, dist, etc). Leading path components like /tmp are no longer skipped (fixed in v0.1.3).

Enrichment slow: Set max_workers: 1 in the provider config. Local models process ~1 request at a time. At 32 tok/sec expect ~3-5s per concept.

Enrichment interrupted: Rerun same command. Enriched files are skipped.

JS/TS concepts missing: Ensure tree-sitter-typescript is installed. TypeScript uses a separate grammar from JavaScript.

Lookup wrong result: Add --type or --file to narrow the search scope.