ochat utilities

Host scope: this is the existing file-backed completion/utility CLI. New durable agent sessions use ochat-agent-server, while daemon-free native TUI uses the local guide. ochat shell store administration targets legacy sessions, not daemon IDs.

This document describes the implementation module of the ochat command-line application that ships with this repository. The public-facing entry points and examples are listed in the command index; the goal here is to explain how the OCaml code wires everything together and to provide a reference for maintainers.

---

1 Module role

bin/main.ml contains a single compilation unit which:

1. Defines the completion, indexing, query, tokenization, and HTML conversion commands, plus the nested shell-management command group.
2. Collects them under a Core.Command.group called main_command and delegates execution to Command_unix.run.

The file does not export a .mli interface – the produced binary is meant to be used externally only through its command-line surface.

---

2 Sub-command API

Below is a condensed overview of each value bound in the module. All of them follow the conventional Core.Command pattern and therefore share common behaviour w.r.t flag parsing, -help, etc.

2.1 index_command

val index_command : Core.Command.t

Builds a dense-vector + BM-25 corpus from an OCaml source tree. The heavy work is delegated to Indexer.index while the surrounding code merely:

• parses CLI flags;
• prints a few progress messages with Io.log;
• opens an Eio.Switch to enforce structured concurrency.

Example:

$ ochat index -folder-to-index ./lib -vector-db-folder ./vector

2.2 query_command

val query_command : Core.Command.t

Performs hybrid retrieval (cosine ✕ BM-25) over a corpus generated by index_command. The function:

1. Loads vector and lexical indices from disk.
2. Fetches a single OpenAI embedding for the user query.
3. Calls Vector_db.query_hybrid to obtain the top-k snippet IDs.
4. Pretty-prints the associated code blocks.

$ ochat query -vector-db-folder ./vector \
           -query-text "tail-recursive map" \
           -num-results 3

2.3 chat_completion_command

val chat_completion_command : Core.Command.t

Streams an assistant reply from the OpenAI Responses endpoint based on a chatmd conversation. The implementation is a one-liner around Chat_response.Driver.run_completion_stream.

Flags of interest:

Flag	Default	Meaning
-prompt-file	(none)	Template appended before execution on every invocation supplying it; omit when continuing existing history
-output-file	./prompts/default.md	Running conversation log

2.4 tokenize_command

val tokenize_command : Core.Command.t

Counts how many o200k_base tokens a file occupies according to the Tikitoken encoding.

$ ochat tokenize -file Readme.md

2.5 html_to_markdown_command / h2md

val html_to_markdown_command : Core.Command.t

Converts an HTML document to Markdown and prints the chunk boundaries that Odoc_snippet.Chunker discovers. Primarily useful for debugging automatic snippet extraction.

$ ochat h2md -file tutorial.html

2.6 main_command

val main_command : Core.Command.t

A Core.Command.group that ties all previous commands together. The call to Command_unix.run at the very end of the file is the only side-effect executed at module initialisation time.

---

3 Internal helpers

The module opens Io and therefore uses Io.run_main and Io.console_log for concise interaction with the underlying Eio environment. These helpers are application-specific and documented separately in Io.

---

4 Known limitations

• Verification scope – the offline documentation gate checks selected examples and contracts; it does not execute every utility or paid request.
• Provider configuration – completion uses the prompt configuration; retrieval uses its separate embedding settings. See the provider environment guide.
• Exit codes – unhandled OCaml exceptions propagate to the top and result in a non-zero exit status without structured error handling.

---

5 ochat shell subcommands

The top-level shell group provides non-executing inspection and security management:

ochat shell inspect CHATMD [-canonical]
ochat shell audit validate PATH
ochat shell audit replay PATH
ochat shell audit request PATH REQUEST_ID
ochat shell grants list SESSION_ID
ochat shell grants explain SESSION_ID GRANT_ID
ochat shell grants revoke SESSION_ID GRANT_ID [-reason TEXT] -confirm
ochat shell manifest-grants list SESSION_ID
ochat shell manifest-grants explain SESSION_ID GRANT_ID
ochat shell manifest-grants revoke SESSION_ID GRANT_ID [-reason TEXT] -confirm
ochat shell interrupted list SESSION_ID

Inspection compiles and reports requested/live authority but grants nothing and executes no command. Audit replay validates/reconstructs events without rerun. Grant revocation refuses to mutate state without -confirm and appends a management audit event. Output is non-secret/redacted.

See docs-src/cli/shell-runtime-management.md.

6 Related modules

• Indexer – building the corpus
• Vector_db – hybrid retrieval engine
• Chat_response.Driver – ChatMD runtime
• Odoc_snippet – Markdown chunking logic

---