Skip to content

Add interactive chat REPL with persistent sessions#18

Merged
rejojer merged 6 commits intodevfrom
feat/chat-repl-squashed
Apr 11, 2026
Merged

Add interactive chat REPL with persistent sessions#18
rejojer merged 6 commits intodevfrom
feat/chat-repl-squashed

Conversation

@rejojer
Copy link
Copy Markdown
Member

@rejojer rejojer commented Apr 11, 2026

Summary

Introduces openkb chat, a multi-turn conversation REPL for the knowledge base. Conversations are automatically persisted to .openkb/chats/<id>.json and can be resumed across invocations. Also bundles a handful of adjacent cleanups that were surfaced while building it.

Supersedes #16 (same content, squashed into logical commits, plus one new commit sanitizing image payloads from persisted chat history).

Main feature

  • New openkb chat CLI command with --resume [ID] (latest or by id / unique prefix), --list, --delete ID, and --no-color.
  • Built on prompt_toolkit: bottom toolbar, styled prompt, Ctrl-C aborts current response while Ctrl-D / /exit quit cleanly.
  • In-REPL slash commands: /exit, /clear (start a fresh session, previous is kept on disk), /save [name] (export markdown transcript to wiki/explorations/), /help.
  • Streams the agent response with the same visual language as openkb query (dim tool-call lines flush against the preceding text, blank line separating a tool batch from the following response paragraph).
  • Header mirrors the Claude Code layout: brand-colored title with version, then <kb dir> · <model> · session <id>, then a short key hint.
  • Resume view shows prior turns compactly (older turns collapsed to ... N earlier turns omitted).
  • Reuses the existing build_query_agent so tool behavior is identical to single-shot query.
  • Persisted history strips base64 image payloads from get_image tool outputs and replaces them with a text reference (source path + "call get_image again" hint), so .openkb/chats/<id>.json stays small and legacy sessions are sanitized on load.

Prompt / agent polish bundled in

  • Fix a copy-paste bug where the Q&A and lint agents were told to "Write all wiki content in X language" — they don't write wiki content. Switched to "Answer in X" and "Write the lint report in X".
  • Give all three agents an "OpenKB" identity so the model introduces itself consistently.
  • Finish the Q&A search-strategy step on summaries (tell the model to follow full_text when a summary is too thin), move the get_image "when to call" guidance into the tool docstring, and reword step 5 to refer to the tool by name.

Refactor bundled in

  • Normalize get_page_content naming: rename the helper in openkb.agent.tools to get_wiki_page_content (matching the *_wiki_* sibling convention), rename the agent-side wrapper from get_page_content_tool to get_page_content so the tool name the model sees matches what the instructions have always said, drop the lazy-import workaround, and fix a stale test assertion.
  • Derive openkb.__version__ from installed package metadata (importlib.metadata) so pyproject.toml is the single source of truth for the version string.

Test plan

  • openkb chat from a kb root starts a new session, header renders, prompt works
  • Single-turn question streams a response, tool-call lines render dim, blank-line spacing is correct
  • Multi-turn: follow-up questions ("what about that?") use conversation context
  • /save writes a readable transcript to wiki/explorations/
  • /clear starts a fresh session; previous shows up in openkb chat --list
  • Ctrl-C during streaming aborts the current response but keeps the REPL alive
  • Ctrl-D / /exit quit with the friendly goodbye message
  • openkb chat --resume picks up the latest session; --resume <prefix> resolves a unique prefix
  • openkb chat --list and --delete <id> work
  • After a turn that calls get_image, the saved .openkb/chats/<id>.json no longer contains the base64 data URL
  • Existing openkb query still works (shared agent)
  • pytest tests/test_agent_tools.py tests/test_query.py tests/test_chat_session.py passes

rejojer added 6 commits April 11, 2026 22:58
Introduces `openkb chat`, a multi-turn conversation REPL that stores each
session under `.openkb/chats/<id>.json` so conversations survive across
invocations and can be resumed by id or prefix. Built on prompt_toolkit
for input editing and a bottom toolbar, and reuses the existing query
agent so tool calls and streaming behavior match `openkb query`.

Supports `--resume`, `--list`, `--delete`, and `--no-color`, plus in-REPL
slash commands (/exit, /clear, /save, /help) where /save exports a
human-readable transcript to wiki/explorations/.
Three related touch-ups to the three agent prompts:

- Fix a copy-paste bug where the Q&A and lint agents were told to
  "Write all wiki content in X language" — the Q&A agent doesn't write
  wiki content, and the lint agent writes reports. Switch them to
  "Answer in X" and "Write the lint report in X" respectively. The
  compiler agent keeps its original wording since it actually writes
  wiki content.

- Give all three agents an OpenKB identity in their opening line so
  the model introduces itself consistently when asked who it is.

- In the Q&A search strategy, finish the thought on summaries (tell
  the model to follow the `full_text` path when a summary is too
  thin), trim step 5 so the get_image tool's "when to call" guidance
  lives in the tool docstring instead of the instructions template,
  and reword step 5 to refer to the tool by name with "the ... tool".
The Q&A agent had an odd naming wart: the helper in openkb.agent.tools
was called get_page_content (no wiki_ prefix like its siblings
read_wiki_file, list_wiki_files, read_wiki_image, write_wiki_file), so
the @function_tool wrapper had to be named get_page_content_tool and
do a lazy local import to avoid a name collision. The instructions
template meanwhile referred to the tool as get_page_content — a third
name — leaving three spellings for one concept.

Rename the helper to get_wiki_page_content so it matches the wiki_
convention, rename the wrapper to get_page_content so the tool name
the model sees matches what the instructions have always said, and
drop the lazy-import workaround. Update the test imports, call sites,
class name, and the one assertion in test_query that was still
checking for the old wrapper name (that assertion was already broken
by earlier work).
Previously openkb/__init__.py had a hand-written __version__ = "0.1.0"
that drifted out of sync with pyproject.toml's version = "0.1.0.dev0",
and the chat REPL had a three-level try/except fallback to paper over
which string it would actually read. Make pyproject.toml the single
source of truth by having __init__.py pull its __version__ from the
installed package metadata via importlib.metadata, and simplify
_openkb_version in chat.py to just import __version__.
Add a dedicated "Interactive chat" subsection under Usage that covers
what chat is, how it differs from one-off query, the session
management flags, and where to find the slash commands. Add the
`openkb chat` row to the Commands table, add a chat step in the
Quick start (replacing the lint step, which was already covered by
its own bullet), and surface chat as its own feature bullet.

While there, polish a few of the existing feature bullets: rename
"Any format" to "Broad format support" to avoid overclaiming,
tighten the "Auto wiki" bullet into "Compiled Wiki" with a single
sentence that ends on the "kept in sync" value prop, and tag the
"Query" bullet as one-off so it reads in contrast to chat.
@rejojer rejojer merged commit 05270b5 into dev Apr 11, 2026
@rejojer rejojer mentioned this pull request Apr 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant