convo-cli 0.1.0__py3-none-any.whl

convo/ui/commands.py

@@ -0,0 +1,37 @@
+"""One command registry shared by suggestions, completion, and /help."""
+
+from dataclasses import dataclass
+
+from textual.widgets import OptionList
+
+
+@dataclass(frozen=True)
+class Command:
+    name: str
+    description: str
+
+
+COMMANDS = (
+    Command("/file", "Choose a file to chat with"),
+    Command("/login", "Connect your ChatGPT account"),
+    Command("/models", "Choose an account model"),
+    Command("/thinking", "Choose the model's thinking effort"),
+    Command("/sessions", "Resume a saved conversation"),
+    Command("/new", "Start a new chat with this file"),
+    Command("/clear", "Start fresh, keep your file"),
+    Command("/reset", "Start fresh without a file"),
+    Command("/help", "Show commands and keyboard shortcuts"),
+    Command("/quit", "Exit Convo"),
+)
+
+
+def matching_commands(text: str) -> tuple[Command, ...]:
+    if not text.startswith("/") or any(character.isspace() for character in text):
+        return ()
+    return tuple(command for command in COMMANDS if command.name.startswith(text.casefold()))
+
+
+class CommandMenu(OptionList):
+    """Let the composer keep focus while arrows and Tab operate suggestions."""
+
+    can_focus = False

convo/ui/files.py

@@ -0,0 +1,110 @@
+"""A searchable picker rooted at the directory where Convo was launched."""
+
+from pathlib import Path
+from typing import ClassVar
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.events import Key
+from textual.screen import ModalScreen
+from textual.widgets import Input, OptionList, Static
+from textual.widgets.option_list import Option
+
+SUPPORTED = {".txt", ".md", ".pdf", ".docx", ".csv", ".json", ".py", ".rst", ".log"}
+
+
+class FilePicker(ModalScreen[Path | None]):
+    BINDINGS: ClassVar = [("escape", "cancel", "Cancel")]
+
+    def __init__(self, root: Path) -> None:
+        super().__init__()
+        self.root = root.resolve()
+        self.folder = self.root
+        self.entries: list[Path] = []
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="picker"):
+            yield Static("Choose a file", id="picker-title")
+            yield Static("", id="picker-path", markup=False)
+            yield Input(placeholder="Filter files…", id="file-search")
+            yield OptionList(id="file-options")
+            yield Static("↑ ↓ move   enter select   tab list   esc close", id="picker-help")
+
+    def on_mount(self) -> None:
+        self.refresh_entries()
+        self.query_one("#file-search", Input).focus()
+
+    def refresh_entries(self, search: str = "") -> None:
+        options = self.query_one("#file-options", OptionList)
+        options.clear_options()
+        self.entries = []
+        self.query_one("#picker-path", Static).update(str(self.folder))
+        try:
+            candidates = []
+            for path in self.folder.iterdir():
+                if path.name.startswith(".") or path.is_symlink():
+                    continue
+                if (
+                    path.is_dir() or path.suffix.lower() in SUPPORTED
+                ) and search.casefold() in path.name.casefold():
+                    candidates.append(path)
+            self.entries = sorted(candidates, key=lambda p: (not p.is_dir(), p.name.casefold()))
+            if self.folder != self.root:
+                self.entries.insert(0, self.folder.parent)
+            for index, path in enumerate(self.entries):
+                name = (
+                    "../"
+                    if path == self.folder.parent
+                    else path.name + ("/" if path.is_dir() else "")
+                )
+                options.add_option(Option(Text(name), id=str(index)))
+            if not self.entries:
+                options.add_option(Option("No supported files found", disabled=True))
+            else:
+                options.highlighted = 0
+        except OSError:
+            options.add_option(Option("Cannot read this directory", disabled=True))
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        event.stop()
+        self.refresh_entries(event.value)
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        event.stop()
+        options = self.query_one("#file-options", OptionList)
+        if options.highlighted is not None and self.entries:
+            self.choose(options.highlighted)
+
+    def on_key(self, event: Key) -> None:
+        if self.query_one("#file-search", Input).has_focus and event.key in {"down", "up"}:
+            options = self.query_one("#file-options", OptionList)
+            if event.key == "down":
+                options.action_cursor_down()
+            else:
+                options.action_cursor_up()
+            event.stop()
+            event.prevent_default()
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        event.stop()
+        self.choose(event.option_index)
+
+    def choose(self, index: int) -> None:
+        if not 0 <= index < len(self.entries):
+            return
+        path = self.entries[index].resolve()
+        if not path.is_relative_to(self.root):
+            return
+        if path.is_dir():
+            self.folder = path
+            self.query_one("#file-search", Input).value = ""
+            self.refresh_entries()
+            self.query_one("#file-search", Input).focus()
+        elif path.is_file():
+            self.dismiss(path)
+        else:
+            self.refresh_entries()
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)

convo/ui/models.py

@@ -0,0 +1,84 @@
+"""A searchable picker populated only from the signed-in account's catalog."""
+
+from typing import ClassVar
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.events import Key
+from textual.screen import ModalScreen
+from textual.widgets import Input, OptionList, Static
+from textual.widgets.option_list import Option
+
+from convo.core.contracts import ChatModel
+
+
+class ModelPicker(ModalScreen[str | None]):
+    BINDINGS: ClassVar = [("escape", "cancel", "Cancel")]
+
+    def __init__(self, models: tuple[ChatModel, ...], selected: str | None) -> None:
+        super().__init__()
+        self.models = models
+        self.selected = selected
+        self.entries: tuple[ChatModel, ...] = ()
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="model-picker"):
+            yield Static("Choose a ChatGPT model", id="model-title")
+            yield Static("Available to your connected account", id="model-subtitle")
+            yield Input(placeholder="Filter by model name…", id="model-search")
+            yield OptionList(id="model-options")
+            yield Static("↑ ↓ move   enter select   esc cancel", id="model-help")
+
+    def on_mount(self) -> None:
+        self.refresh_entries()
+        self.query_one("#model-search", Input).focus()
+
+    def refresh_entries(self, search: str = "") -> None:
+        options = self.query_one("#model-options", OptionList)
+        options.clear_options()
+        self.entries = tuple(
+            model
+            for model in self.models
+            if search.casefold() in f"{model.name} {model.id}".casefold()
+        )
+        for model in self.entries:
+            label = Text()
+            label.append("● " if model.id == self.selected else "  ", style="#aaaaaa")
+            label.append(model.name, style="bold")
+            label.append(f"\n  {model.id}", style="#888888")
+            options.add_option(Option(label, id=model.id))
+        if not self.entries:
+            options.add_option(Option("No matching models", disabled=True))
+        else:
+            options.highlighted = next(
+                (index for index, model in enumerate(self.entries) if model.id == self.selected), 0
+            )
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        event.stop()
+        self.refresh_entries(event.value)
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        event.stop()
+        highlighted = self.query_one("#model-options", OptionList).highlighted
+        if highlighted is not None and self.entries:
+            self.dismiss(self.entries[highlighted].id)
+
+    def on_key(self, event: Key) -> None:
+        if self.query_one("#model-search", Input).has_focus and event.key in {"up", "down"}:
+            options = self.query_one("#model-options", OptionList)
+            if event.key == "down":
+                options.action_cursor_down()
+            else:
+                options.action_cursor_up()
+            event.stop()
+            event.prevent_default()
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        event.stop()
+        if 0 <= event.option_index < len(self.entries):
+            self.dismiss(self.entries[event.option_index].id)
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)

convo/ui/preview.py

@@ -0,0 +1,20 @@
+"""UI-only adapter. This does not read, embed, upload, or answer from a file."""
+
+from pathlib import Path
+
+from convo.core.contracts import Answer, Document, Message
+from convo.core.exceptions import BackendNotConnected
+
+
+class ShellBackend:
+    async def prepare(self, path: Path) -> Document:
+        if not path.is_file():
+            raise ValueError("That file is no longer available. Use /file to choose another.")
+        return Document(id=str(path), path=path, indexed=False)
+
+    async def answer(
+        self, document: Document, question: str, history: tuple[Message, ...]
+    ) -> Answer:
+        raise BackendNotConnected(
+            "Shell preview only. Run `convo` to use local storage, embeddings, and ChatGPT."
+        )

convo/ui/sessions.py

@@ -0,0 +1,97 @@
+"""Search and resume the conversations stored in PostgreSQL."""
+
+from typing import ClassVar
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.events import Key
+from textual.screen import ModalScreen
+from textual.widgets import Input, OptionList, Static
+from textual.widgets.option_list import Option
+
+from convo.core.contracts import SessionSummary
+
+
+class SessionPicker(ModalScreen[str | None]):
+    BINDINGS: ClassVar = [("escape", "cancel", "Cancel")]
+
+    def __init__(self, sessions: tuple[SessionSummary, ...], selected: str | None) -> None:
+        super().__init__()
+        self.sessions, self.selected = sessions, selected
+        self.entries: tuple[SessionSummary, ...] = ()
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="session-picker"):
+            yield Static("Your conversations", id="session-title")
+            yield Static("Resume a saved file and its history", id="session-subtitle")
+            yield Input(placeholder="Filter by title, file, or session ID…", id="session-search")
+            yield OptionList(id="session-options")
+            yield Static("↑ ↓ move   enter resume   esc cancel", id="session-help")
+
+    def on_mount(self) -> None:
+        self.refresh_entries()
+        self.query_one("#session-search", Input).focus()
+
+    def refresh_entries(self, search: str = "") -> None:
+        options = self.query_one("#session-options", OptionList)
+        options.clear_options()
+        self.entries = tuple(
+            session
+            for session in self.sessions
+            if search.casefold()
+            in f"{session.title} {session.filename or ''} {session.id}".casefold()
+        )
+        for session in self.entries:
+            label = Text()
+            label.append("● " if session.id == self.selected else "  ", style="#aaaaaa")
+            label.append(session.title.replace("\n", " ")[:100], style="bold")
+            date = session.updated_at.astimezone().strftime("%d %b %H:%M")
+            turns = session.message_count // 2
+            turn_label = "turn" if turns == 1 else "turns"
+            label.append(
+                f"\n  {session.filename or 'no file'} · {turns} {turn_label} · {date}",
+                style="#888888",
+            )
+            options.add_option(Option(label, id=session.id))
+        if not self.entries:
+            options.add_option(
+                Option(
+                    "No matching sessions"
+                    if self.sessions
+                    else "No saved sessions yet. Start with /new or /file.",
+                    disabled=True,
+                )
+            )
+        else:
+            options.highlighted = next(
+                (index for index, item in enumerate(self.entries) if item.id == self.selected), 0
+            )
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        event.stop()
+        self.refresh_entries(event.value)
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        event.stop()
+        highlighted = self.query_one("#session-options", OptionList).highlighted
+        if highlighted is not None and self.entries:
+            self.dismiss(self.entries[highlighted].id)
+
+    def on_key(self, event: Key) -> None:
+        if self.query_one("#session-search", Input).has_focus and event.key in {"up", "down"}:
+            options = self.query_one("#session-options", OptionList)
+            if event.key == "down":
+                options.action_cursor_down()
+            else:
+                options.action_cursor_up()
+            event.stop()
+            event.prevent_default()
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        event.stop()
+        if 0 <= event.option_index < len(self.entries):
+            self.dismiss(self.entries[event.option_index].id)
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)

convo/ui/theme.tcss

@@ -0,0 +1,64 @@
+Screen {
+    background: #080808;
+    color: #dddddd;
+    padding: 2 3 1 3;
+}
+#masthead { height: 4; margin-bottom: 1; }
+#brand { width: 29; height: 4; }
+#identity { width: 1fr; height: 4; margin-left: 3; padding-top: 1; }
+#version { height: 1; color: #a7a095; }
+#tagline { height: 1; color: #777777; }
+#directory { height: 1; color: #555555; }
+#conversation { height: 1fr; min-height: 1; margin: 1 0; scrollbar-size: 1 1; scrollbar-color: #494134; scrollbar-background: #080808; }
+#welcome { color: #888888; height: auto; }
+.message { height: auto; margin-bottom: 2; }
+.user-message { background: #151515; border-left: solid #e6b85c; padding: 1 2; color: #eeeeee; }
+.assistant-message { padding: 0 3; }
+.notice-message { padding: 0 3; color: #bbbbbb; margin-bottom: 1; }
+.source-message { background: #0e0e0e; border-left: solid #494134; padding: 1 2; color: #aaaaaa; }
+.error-message { border-left: solid #b97863; padding: 0 2; }
+#composer { height: auto; }
+#input-panel { height: auto; background: #191919; border-left: solid #e6b85c; padding: 1 2; }
+#settings { height: 1; margin-top: 1; }
+#selection { height: 1; width: 1fr; min-width: 0; color: #e6b85c; }
+#thinking { height: 1; width: auto; margin-left: 2; color: #e6b85c; }
+#prompt { height: 1; border: none; background: #191919; padding: 0; }
+#prompt:focus { border: none; background: #191919; }
+#prompt:disabled { opacity: 60%; }
+Input { color: #eeeeee; }
+Input > .input--placeholder { color: #666666; }
+#status { height: 1; color: #888888; margin-top: 1; }
+#keys { height: 1; color: #666055; margin-top: 1; }
+#command-menu { display: none; border: solid #494134; background: #0c0c0c; padding: 0; margin-bottom: 1; scrollbar-size: 1 1; scrollbar-color: #6d582f; scrollbar-background: #0c0c0c; }
+#command-menu > .option-list--option-highlighted { background: #292318; color: #f2cc70; }
+FilePicker, ModelPicker, SessionPicker, ThinkingPicker { align: center middle; background: #000000 75%; padding: 1; }
+#picker, #model-picker, #session-picker, #thinking-picker { width: 80; max-width: 100%; height: 24; max-height: 100%; background: #0c0c0c; border: solid #a18245; padding: 1 2; }
+#thinking-picker { width: 52; height: auto; max-height: 100%; }
+#picker-title, #model-title, #session-title, #thinking-title { height: 1; color: #e6b85c; text-style: bold; margin-bottom: 1; }
+#picker-path, #model-subtitle, #session-subtitle, #thinking-subtitle { height: 1; color: #888888; margin-bottom: 1; }
+#file-search, #model-search, #session-search { height: 3; border: solid #444444; background: #0c0c0c; }
+#file-search:focus, #model-search:focus, #session-search:focus { border: solid #e6b85c; }
+#file-options, #model-options, #session-options, #thinking-options { height: 1fr; border: none; background: #0c0c0c; padding: 0; margin-top: 1; scrollbar-size: 1 1; scrollbar-color: #6d582f; scrollbar-background: #0c0c0c; }
+#thinking-options { height: auto; max-height: 8; margin-top: 0; }
+#file-options > .option-list--option-highlighted, #model-options > .option-list--option-highlighted, #session-options > .option-list--option-highlighted, #thinking-options > .option-list--option-highlighted { background: #292318; color: #f2cc70; text-style: none; }
+#picker-help, #model-help, #session-help, #thinking-help { height: auto; color: #777777; margin-top: 1; }
+Screen.compact { padding: 1; }
+Screen.compact #masthead { height: 1; margin-bottom: 0; }
+Screen.compact #brand { width: 1fr; height: 1; }
+Screen.compact #identity { display: none; }
+Screen.compact #conversation { margin: 1 0 0 0; }
+Screen.compact #input-panel { padding: 0 1; }
+Screen.compact #settings { margin-top: 0; }
+Screen.compact #status { margin-top: 0; }
+Screen.compact #keys { margin-top: 0; }
+Screen.compact #command-menu { margin-bottom: 0; }
+ThinkingPicker.compact #thinking-picker { padding: 0 2; }
+ThinkingPicker.compact #thinking-title, ThinkingPicker.compact #thinking-subtitle { margin-bottom: 0; }
+Screen.chatting { padding: 1 2; }
+Screen.chatting #masthead { height: 1; margin-bottom: 0; }
+Screen.chatting #brand { width: 1fr; height: 1; }
+Screen.chatting #identity { display: none; }
+Screen.chatting.compact { padding: 1; }
+Screen.compact .message { margin-bottom: 1; }
+Screen.compact .user-message, Screen.compact .source-message { padding: 0 1; }
+Screen.compact .assistant-message, Screen.compact .notice-message { padding: 0 2; }

convo/ui/thinking.py

@@ -0,0 +1,70 @@
+"""Direct thinking selection and the configurable cycling shortcut."""
+
+import re
+from typing import ClassVar
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.events import Resize
+from textual.screen import ModalScreen
+from textual.widgets import OptionList, Static
+from textual.widgets.option_list import Option
+
+from convo.core.contracts import ChatModel, ReasoningEffort
+
+GOLD = "#e6b85c"
+
+
+def thinking_key(value: str) -> str:
+    """Accept terminal-friendly shortcuts without replacing essential controls."""
+    key = value.strip().lower()
+    if key == "shift+tab" or re.fullmatch(r"f(?:[3-9]|1[0-9]|2[0-4])", key):
+        return key
+    if re.fullmatch(r"(?:ctrl|alt)\+[a-z]", key) and key not in {
+        "ctrl+c",
+        "ctrl+o",
+        "ctrl+i",
+        "ctrl+j",
+        "ctrl+m",
+        "ctrl+h",
+        "ctrl+z",
+    }:
+        return key
+    raise ValueError(
+        "Use ctrl+t, another Ctrl/Alt letter, or F3–F24; reserved keys are unavailable."
+    )
+
+
+class ThinkingPicker(ModalScreen[str | None]):
+    BINDINGS: ClassVar = [("escape", "cancel", "Cancel")]
+
+    def __init__(self, model: ChatModel, selected: ReasoningEffort | None) -> None:
+        super().__init__()
+        self.model = model
+        self.selected = selected or "auto"
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="thinking-picker"):
+            yield Static("Thinking effort", id="thinking-title")
+            yield Static(self.model.name, id="thinking-subtitle", markup=False)
+            options = [Option("auto  ·  model default", id="auto")]
+            options.extend(Option(effort, id=effort) for effort in self.model.reasoning_efforts)
+            yield OptionList(*options, id="thinking-options")
+            yield Static("↑ ↓ move   enter select   esc cancel", id="thinking-help")
+
+    def on_mount(self) -> None:
+        self.set_class(self.app.size.height < 24, "compact")
+        options = self.query_one("#thinking-options", OptionList)
+        choices = ("auto", *self.model.reasoning_efforts)
+        options.highlighted = choices.index(self.selected) if self.selected in choices else 0
+        options.focus()
+
+    def on_resize(self, event: Resize) -> None:
+        self.set_class(event.size.height < 24, "compact")
+
+    def on_option_list_option_selected(self, event: OptionList.OptionSelected) -> None:
+        event.stop()
+        self.dismiss(event.option.id)
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)

convo_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: convo-cli
+Version: 0.1.0
+Summary: A local terminal RAG assistant for chatting with selected files.
+Project-URL: Homepage, https://github.com/madvillax/convo
+Project-URL: Repository, https://github.com/madvillax/convo
+Project-URL: Issues, https://github.com/madvillax/convo/issues
+Author: Mohit Sharma
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,local-first,rag,terminal,textual
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: General
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.20.0
+Requires-Dist: docx2txt>=0.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: keyring>=25.6
+Requires-Dist: llama-index-core>=0.14.25
+Requires-Dist: llama-index-readers-file>=0.7.0
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: openai>=2.0
+Requires-Dist: pgvector>=0.5.1
+Requires-Dist: psycopg[binary]>=3
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pyjwt[crypto]>=2.10
+Requires-Dist: python-dotenv>=1.2.4
+Requires-Dist: sentence-transformers>=6.1.0
+Requires-Dist: sqlalchemy<3,>=2.0
+Requires-Dist: textual<9,>=8.2
+Requires-Dist: transformers>=4.51
+Description-Content-Type: text/markdown
+
+# Convo
+
+Convo is an open-source, local-first terminal app for chatting with a selected file. Qwen3 embeddings and PostgreSQL full-text search retrieve passages together; a local cross-encoder reranks them; your connected ChatGPT account returns a structured answer with supporting quotations.
+
+It is released under the [MIT License](LICENSE). Contributions are welcome—see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Install and start
+
+The supported release install uses [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install convo-cli
+convo
+```
+
+On first launch, `convo` creates a private settings file at `~/.config/convo/.env`, pulls `pgvector/pgvector:pg16`, starts a loopback-only `convo-postgres` container, and runs migrations before opening the terminal app. It generates a random database password and preserves existing data. Later launches restart Convo's local container if needed and apply pending migrations.
+
+Local storage needs Docker Desktop or Podman installed. Start Docker Desktop first if you use Docker. On macOS, Convo starts or initializes a Podman machine when Podman is installed. First use downloads Python dependencies, a database image, and—when indexing your first file—the embedding/reranker models.
+
+If you already use PostgreSQL, set `DATABASE_URL` to a `postgresql+psycopg://...` URL, run `convo --setup` once to migrate that database, then run `convo`. Explicit database connections are used as configured; startup only manages storage created by Convo.
+
+For a one-command install on macOS/Linux, inspect and then run the repository installer:
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/madvillax/convo/main/scripts/install.sh | sh
+```
+
+It installs uv if needed, installs `convo-cli`, and adds uv's tool directory to your shell path. Then type `convo` to start. Open a new terminal if `convo` is not immediately found.
+
+To use an unreleased checkout while developing:
+
+```sh
+uv sync --python 3.12
+uv run convo
+```
+
+`--directory ~/Documents` changes the file browser root. Environment variables always override the user settings file; `.env.example` is only for checkout-based development.
+
+Optional model download/warmup outside the TUI:
+
+```sh
+uv run convo --download-model
+```
+
+This prepares both Qwen3 and `cross-encoder/ms-marco-MiniLM-L6-v2`. Models otherwise load/download on demand in an isolated process. File preparation shows stages and elapsed time; Esc cancels it. Download/native logs stay in `~/.cache/convo/rag-worker.log` (respecting `XDG_CACHE_HOME`). After storage preparation, startup restores account preferences locally; models and the account catalog load when needed.
+
+For a UI preview without services or backend dependencies:
+
+```sh
+uv run convo --shell
+```
+
+## Use
+
+Type `/` for command suggestions. Filter by typing, use ↑/↓ to move, Tab to complete, Enter to run, and Esc to dismiss.
+
+| Command/key | Action |
+| --- | --- |
+| `/login` | Connect your ChatGPT account through browser sign-in |
+| `/models` | Search and select an account model |
+| `/models <id>` | Select a model directly |
+| Ctrl+T or Shift+Tab | Cycle auto and the model's supported thinking levels |
+| F2 or `/thinking` | Choose a thinking level directly |
+| `/thinking high`, `/thinking auto` | Set a supported level or restore the model default |
+| `/file`, Ctrl+O | Select and index a file; create a saved conversation |
+| `/sessions` | Search saved conversations by title, filename, or ID and resume one |
+| `/sessions <uuid>` | Resume a conversation directly |
+| `/new` | Create a new saved conversation, keeping the selected file |
+| `/clear` | Same behavior as `/new`; previous conversations remain saved |
+| `/reset` | Create a new saved conversation without a selected file |
+| Esc during file preparation | Stop preparation and restore the input |
+| `/help` | Show commands and keys |
+| `/quit`, `/exit`, Ctrl+C | Exit |
+| PageUp / PageDown | Scroll the transcript while keeping the input focused |
+
+Questions appear in shaded blocks with a gold left edge. Answers use spaced Markdown with highlighted code, and source quotations appear in a separate subdued block. The composer groups your input with the gold model name and thinking level underneath. The ASCII title collapses once chatting starts and in smaller terminals, leaving more room to read. Long replies open at the question and the beginning of the answer; use PageUp/PageDown or the mouse wheel to keep reading.
+
+Change the cycling shortcut with `convo --thinking-key ctrl+g` or set `CONVO_THINKING_KEY=ctrl+g` in `.env` (export it for `--shell`). The command-line flag takes precedence. Shift+Tab and F2 remain available. Choose a Ctrl/Alt letter or F3–F24; essential keys are reserved. `/help` shows the configured shortcut. Only thinking levels supported by the selected account model can be saved.
+
+Sessions, completed message pairs, displayed source quotes, and structured answers persist in PostgreSQL. Use `/sessions` after restarting. Resuming uses the saved indexed snapshot, so the original file can have moved or disappeared. Use `/file` again to index changed content. A failed request never saves a partial turn. Account tokens remain in the OS keyring; model/thinking preferences remain in the local account profile.
+
+Greetings such as `hello` and acknowledgements such as `thank you` receive a short local reply without retrieval or model calls. Mixed greetings and file questions still use retrieval. Specific questions use hybrid search, reciprocal rank fusion, cross-encoder reranking, and weak-match filtering. Broad file overviews sample sections across the snapshot and rerank their order without applying a QA relevance cutoff.
+
+ChatGPT returns JSON sections containing text and citation objects. Python validates the schema, requires citations on answered sections, checks source IDs and exact supporting quotes, then renders readable Markdown with numbered citations. Only cited quotes appear under sources. An empty evidence set returns an insufficient-evidence response without an LLM call. These checks verify structure and quotations; they do not prove every generated claim is entailed by its quote.
+
+Supported files: `.txt`, `.md`, `.pdf`, `.docx`, `.csv`, `.json`, `.py`, `.rst`, `.log`. Limits: 10 MB input, 500,000 extracted characters, and 2,000 chunks. LlamaIndex is used only for readers and chunking. The TUI supports terminals down to 50 columns × 18 rows.
+
+## Architecture
+
+```text
+convo/
+├── core/       settings, shared values and UI/backend contracts
+├── ui/         Textual app, commands, file/model/session pickers
+├── llm/        ChatGPT connection, credentials, catalog and Responses transport
+├── pipeline/   chat flow, routing, ingestion, embeddings, reranking and worker
+├── prompts/    answer instructions, context builder and structured schema
+└── db/         SQLAlchemy models, connections, document/search/session queries
+```
+
+[ARCHITECTURE.md](ARCHITECTURE.md) explains the files, schema, data flow, tuning, and verification. [changes.md](changes.md) records implementation approaches and validation.
+
+## Checks
+
+```sh
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest -q
+```
+
+PostgreSQL integration checks use a disposable database, enabled explicitly with `CONVO_TEST_DATABASE_URL`. `CONVO_TEST_MODELS=1` also exercises real Qwen/reranking models. See [ARCHITECTURE.md](ARCHITECTURE.md) for these opt-in checks and their prerequisites.
+
+## Releasing to PyPI
+
+Maintainers should test a release on TestPyPI first, then create a GitHub release. The included `Publish to PyPI` workflow uses PyPI Trusted Publishing, so it does not require a long-lived token in the repository. Configure the repository and `.github/workflows/publish.yml` as a Trusted Publisher in PyPI before publishing.
+
+```sh
+uv build --no-sources
+uv publish --token "$PYPI_TOKEN" # one-time/manual alternative
+```