docs(examples): openkb usage guides with real generated artifacts#141
Merged
Conversation
Add examples/ as a use-case-indexed set of guides. Each case is its own directory: a README walkthrough plus the actual artifact OpenKB produced. - configuration — init, config.yaml, keys, LiteLLM tuning - commands — the everyday loop (+ a compiled sample-wiki/) - pageindex-cloud — long docs: local vs cloud + cloud import - chat — the interactive REPL: sessions + slash commands - skills — a generated SKILL.md + references/ + marketplace.json - slides — a generated single-file HTML deck - visualize — a generated interactive knowledge graph Every artifact was produced by running openkb over the sample attention-is-all-you-need.pdf with gpt-5.4-mini. The heavy/third-party test PDFs stay gitignored under examples/docs/. Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
…eout Cover recurring install/usage questions from the issue tracker: - #130 / #24: openkb pins a pre-release dependency (pageindex==0.3.0.dev1), which uv/pip skip by default. Show `uv tool install --prerelease=allow` / `pip install --pre`, plus a PATH note for the "command not found" case. - #140: local runtimes (LM Studio on Mac, Ollama, llama.cpp) abort on the default request timeout; document raising litellm.timeout in config. Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
Replace the ad-hoc ko/Korean language examples with the six official UN languages (en/zh/es/fr/ar/ru) so the config docs lead with widely-used options. Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
KylinMountain
changed the title
Add an Examples section pointing to examples/ (and examples/README.md), with a table of the per-feature cases. Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
Keep the README as a feature overview (what each command does); move the deep usage into examples/ and point to it: - collapse the Skill Factory walkthrough (output layout / install / share / iterate-from-chat / validate-eval-rollback) to a one-line pointer - replace the chat slash-command list with a pointer - tighten the skill-command table to feature-level descriptions - add a Configuration pointer for LiteLLM tuning (Ollama/LM Studio/Copilot) Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
…tup) Provider/model + key setup is already covered in Getting Started > 'Set up your LLM'; Configuration > Settings repeated it. Trim Settings to the core config.yaml keys + a pointer to examples/configuration (entity_types, OAuth, LiteLLM tuning). PageIndex Setup (kept for referral) and AGENTS.md are unchanged. Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
Critical pass on Usage — it described the generators twice (Layer 2 table + narrative subsections): - drop the (i) Query & Chat and (iii) Visualize subsections (already in the Layer 2 table; depth is in examples/) - shorten Skill Factory to a flagship blurb + pointer (no walkthrough) - add the missing deck/slides generator to the Layer 2 table - fix the Skill Factory anchor link; remove a dead commented-out lint row Quick Start: add optional visualize + deck (deck noted as needing a theme). Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
…install The deck themes (openkb-deck-neon / openkb-deck-editorial) and the html critic lived only in the repo's top-level skills/, which the wheel didn't ship — so a fresh `pip install openkb` failed `deck new` / `--critique` (and chat `/deck`, `/critique`) with "Deck skill ... is not installed". - force-include the three skills into the wheel at openkb/_skills/ - scan_local_skills also scans bundled roots (wheel openkb/_skills + the source-checkout skills/), at lowest priority so KB/user skills still override - tests: isolate bundled roots in the scan unit tests; add coverage for bundled discovery + KB-overrides-bundled - docs: drop the now-stale "install a theme first" notes Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
The standalone Examples section duplicated the Usage tables. Remove it and link each command to its specific walkthrough instead: - Layer 2 generators table gets an Example column (query/chat/visualize/skill/deck) - a wiki-foundation 'everyday loop' link under Layer 1 -> examples/commands/ - PageIndex example linked from PageIndex Setup; config from Configuration Every example folder stays linked from its natural context; no duplicate table. Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
…ding)
From a critical pass over the examples docs:
- threshold is >= (a 20-page PDF is long, converter.py:183): fix the boundary in
pageindex-cloud (<= / > -> < / >=) and configuration ("more than" -> "or more")
- fix the Bishop sample link — href pointed at ../docs/ (a dir), not the PDF
- remove --keep-empty keeps concept AND entity pages, not just concepts
- deck_grammar quote: add the kind_attr line so it matches the real SKILL.md
Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
The code default (DEFAULT_CONFIG) was gpt-5.4-mini while config.yaml.example and all docs use gpt-5.4. Standardize on gpt-5.4: - DEFAULT_CONFIG model gpt-5.4-mini -> gpt-5.4 (+ update test_config assertion) - cli.py: fix the cross-family gpt-4o-mini fallback and the --model help example to gpt-5.4; lead the init model list with gpt-5.4 - examples/README: showcase commands use gpt-5.4 Also drop the empty separator row in the README Layer 2 generators table. Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
examples/as a use-case-indexed set of usage guides. Each case is its owndirectory — a
README.mdwalkthrough plus the real artifact OpenKB producedfor it (generated, not hand-written):
configuration/commands/sample-wiki/pageindex-cloud/chat/skills/SKILL.md+marketplace.jsonslides/attention-intro.htmlvisualize/graph.htmlEvery artifact was produced by running
openkbover a single sample paper(
examples/docs/attention-is-all-you-need.pdf) withgpt-5.4-mini. Theheavy/third-party test PDFs stay gitignored under
examples/docs/.Issues these examples address
ChatGPT-subscription / Copilot headers), [Feature] Support importing existing PageIndex Cloud indices #88 (PageIndex Cloud import), openkb visualize is not a command #133
(
openkb visualize), [bug] API 供应商切换配置流程缺失，导致认证失败 #70 (provider switching / keys), Remove Document #41 openkb remove leaves orphan hash and reformats unrelated wiki #58 (remove).pageindex==0.3.0.dev1);configuration/now documentsuv tool install --prerelease=allow/pip install --pre, plus a PATH note for "command not found".default request timeout;
configuration/documents raisinglitellm.timeout.Notes
examples/<case>/; nothing else in the repo changes.skills/marketplace.jsonhas its git-derivedowner/authorscrubbed to aplaceholder.