Context-aware tab-completion for the OC Chat REPL (Phase 2 PR 2.A).
Purpose
-------
The :class:`OCChatCompleter` understands the *shape* of partial input
and picks completions from the appropriate live registry — never
hardcoded. It is plugged into ``prompt_toolkit.PromptSession`` by
:class:`~oc_ui.terminal.input.PromptDriver`.
This module imports ``prompt_toolkit`` at top-level — only modules
that need completion functionality should import it, and they should
only do so after the optional dependency has been verified to be
available. The :class:`PromptDriver` handles that gating; tests use
``importorskip``.
Completion sources (in order of input shape):
================================== =====================================
Input shape Source
================================== =====================================
``/<partial>`` ``oc_chat.core.commands.COMMANDS``
``/model <p>`` / ``/use <p>`` ``ctx.model_manager.known_models()``
``/session load <p>`` ``list_sessions()`` names
``/session switch <p>`` ``list_sessions()`` names
``/session save <p>`` ``list_sessions()`` names + free
``/session new <p>`` free (no completion)
``/context <p>`` / ``/read <p>`` paths via ``PathCompleter``
``/ui reasoning <p>`` ``(\"show\", \"dim\", \"hide\")``
``/effort <p>`` ``REASONING_EFFORT_LEVELS``
``/help``, free text, etc. no completions
================================== =====================================
Responsibilities
----------------
- :class:`OCChatCompleter` — top-level completer that routes the
prompt-toolkit ``Document`` / ``CompleteEvent`` to one of the
per-shape sub-completers.
- Per-verb completion logic for ``/model``, ``/session``, ``/read``,
``/context``, ``/ui``, ``/effort``.
Diagnostics
-----------
Domain: OC_UI.TERMINAL
Levels:
L2 — lifecycle events
L3 — semantic details
L4 — deep tracing
Contracts
---------
- ``get_completions`` is a generator and must not block.
- All registry reads happen at call time so completions stay fresh
as the user adds models / sessions during a REPL run.
- Unknown verbs yield no completions rather than raising.
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- prompt_toolkit.completion (interactive REPL input with completion and history)
- prompt_toolkit.document (interactive REPL input with completion and history)
- oc_chat.core.commands (lazy; COMMANDS, COMMAND_HELP and UI_REASONING_VALUES for verb and choice completion)
- oc_chat.core.config (lazy; REASONING_EFFORT_LEVELS for /effort completion)
- oc_chat.core.persistence (lazy; list_sessions for session name completion)
1.15.0