convo-cli 0.1.0__py3-none-any.whl

convo/__init__.py

@@ -0,0 +1,3 @@
+"""A local terminal RAG assistant for chatting with selected files."""
+
+__version__ = "0.1.0"

convo/__main__.py

@@ -0,0 +1,110 @@
+import argparse
+import os
+from pathlib import Path
+
+from convo.ui.app import ConvoApp
+from convo.ui.preview import ShellBackend
+from convo.ui.thinking import thinking_key
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Chat with a file in your current directory.")
+    parser.add_argument("--directory", type=Path, default=None, help="Browse this folder instead")
+    parser.add_argument(
+        "--thinking-key",
+        type=thinking_key,
+        default=None,
+        help="Thinking cycle shortcut (default: CONVO_THINKING_KEY or ctrl+t)",
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--shell",
+        action="store_true",
+        help="Run the UI preview without PostgreSQL, embeddings, or ChatGPT",
+    )
+    mode.add_argument(
+        "--download-model",
+        action="store_true",
+        help="Download and warm Qwen3 and the reranker outside the TUI, then exit",
+    )
+    mode.add_argument(
+        "--setup",
+        action="store_true",
+        help="Create and migrate Convo's local PostgreSQL/pgvector storage, then exit",
+    )
+    args = parser.parse_args()
+    directory = (args.directory or Path.cwd()).expanduser().resolve()
+    if not directory.is_dir():
+        parser.error(f"Not a directory: {directory}")
+    if args.shell:
+        try:
+            app = ConvoApp(directory, ShellBackend(), thinking_shortcut=args.thinking_key)
+        except ValueError as error:
+            parser.error(str(error))
+        app.run()
+        return
+
+    try:
+        from convo.core.config import load_settings
+        from convo.pipeline.chat import RagBackend
+    except ImportError as error:
+        parser.error(
+            f"Backend dependency {error.name} is missing. Install the published command with "
+            "`uv tool install --force convo-cli`; from a checkout run `uv run convo`."
+        )
+
+    if args.setup:
+        from convo.bootstrap import SetupError, setup
+
+        try:
+            settings_path = setup()
+        except (SetupError, ValueError) as error:
+            parser.error(str(error))
+        print(f"Convo storage is ready. Settings are in {settings_path}. Run `convo` to start.")
+        return
+
+    if args.download_model:
+        # Warming models does not require a running database or a container runtime.
+        from convo.core.config import Settings, load_environment
+        from convo.core.contracts import Hit
+        from convo.pipeline.embeddings import Embedder
+        from convo.pipeline.reranking import Reranker
+
+        load_environment()
+        settings = Settings(
+            "",
+            os.getenv("EMBEDDING_MODEL", "Qwen/Qwen3-Embedding-0.6B"),
+            reranker_model=os.getenv("RERANKER_MODEL", "cross-encoder/ms-marco-MiniLM-L6-v2"),
+        )
+        print(
+            "Downloading/loading Qwen3 embeddings. First use can take several minutes.", flush=True
+        )
+        Embedder(settings.embedding_model).query("warm up")
+        print("Downloading/loading the local reranker…", flush=True)
+        Reranker(settings.reranker_model).rerank(
+            "What is being cached?", [Hit("Model weights are cached locally.", "warmup", 0.0)]
+        )
+        print("Both models are ready. Run convo and choose a file with /file.")
+        return
+
+    from convo.bootstrap import SetupError, ensure_storage
+
+    try:
+        ensure_storage()
+        settings = load_settings()
+    except (SetupError, ValueError) as error:
+        parser.error(str(error))
+
+    backend = RagBackend(settings)
+    try:
+        try:
+            app = ConvoApp(directory, backend, thinking_shortcut=args.thinking_key)
+        except ValueError as error:
+            parser.error(str(error))
+        app.run()
+    finally:
+        backend.close()
+
+
+if __name__ == "__main__":
+    main()

convo/bootstrap.py

@@ -0,0 +1,273 @@
+"""Prepare local pgvector storage on startup and keep migrations available in wheels.
+
+Convo manages only its labelled container and named volume. Explicit DATABASE_URL
+connections are left alone at startup; ``convo --setup`` migrates them on request.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+import shutil
+import subprocess
+import sys
+import time
+from importlib.resources import as_file, files
+from pathlib import Path
+from urllib.parse import quote
+
+CONTAINER_NAME = "convo-postgres"
+VOLUME_NAME = "convo-postgres-data"
+IMAGE = "pgvector/pgvector:pg16"
+DATABASE_NAME = "convo"
+DATABASE_USER = "convo"
+
+
+class SetupError(RuntimeError):
+    """The machine cannot safely complete the requested local setup."""
+
+
+def _run(command: list[str], *, allow_failure: bool = False) -> subprocess.CompletedProcess[str]:
+    try:
+        result = subprocess.run(command, check=False, capture_output=True, text=True)
+    except OSError as error:
+        raise SetupError(f"Could not run {command[0]!r}: {error}") from error
+    if result.returncode and not allow_failure:
+        detail = result.stderr.strip() or result.stdout.strip() or "unknown error"
+        raise SetupError(f"{' '.join(command[:2])} failed: {detail}")
+    return result
+
+
+def _container_runtime() -> str:
+    installed = []
+    for candidate in ("docker", "podman"):
+        if shutil.which(candidate):
+            installed.append(candidate)
+            if _run([candidate, "info"], allow_failure=True).returncode == 0:
+                return candidate
+    if installed:
+        if "podman" in installed and sys.platform == "darwin":
+            return "podman"
+        return installed[0]
+    raise SetupError(
+        "Convo needs Docker Desktop or Podman to create its local PostgreSQL storage. "
+        "Install one, start it, then run `convo` again."
+    )
+
+
+def _ensure_podman_machine(runtime: str) -> None:
+    """Start Podman's macOS VM when it exists; leave other platforms untouched."""
+    if runtime != "podman" or sys.platform != "darwin":
+        return
+    if _run([runtime, "info"], allow_failure=True).returncode == 0:
+        return
+    machines = _run([runtime, "machine", "list", "--format", "{{.Name}}"], allow_failure=True)
+    if machines.returncode:
+        raise SetupError(
+            "Podman is installed but unavailable. Start Podman, then run `convo --setup`."
+        )
+    if not machines.stdout.strip():
+        _run([runtime, "machine", "init"])
+    _run([runtime, "machine", "start"])
+
+
+def _write_local_settings(database_url: str) -> Path:
+    from convo.core.config import user_settings_path
+
+    target = user_settings_path()
+    target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    contents = (
+        "# Created by `convo --setup`. Keep this file private.\n"
+        f"DATABASE_URL={database_url}\n"
+        "CONVO_LOCAL_CONTAINER=1\n"
+        "EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B\n"
+        "RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L6-v2\n"
+        "RERANK_MIN_SCORE=-3\n"
+        "RETRIEVAL_CANDIDATES=20\n"
+    )
+    try:
+        descriptor = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError as error:
+        raise SetupError(
+            f"Settings already exist at {target}. Configure DATABASE_URL there."
+        ) from error
+    with os.fdopen(descriptor, "w", encoding="utf-8") as output:
+        output.write(contents)
+    return target
+
+
+def _configured_database_url() -> str | None:
+    from convo.core.config import load_environment, load_settings
+
+    load_environment()
+    if not os.getenv("DATABASE_URL"):
+        return None
+    # Invalid supplied settings must be reported, never replaced by a new database.
+    return load_settings().database_url
+
+
+def _is_managed_database(database_url: str | None) -> bool:
+    from dotenv import dotenv_values
+
+    from convo.core.config import user_settings_path
+
+    saved = dotenv_values(user_settings_path())
+    return bool(
+        database_url
+        and saved.get("CONVO_LOCAL_CONTAINER") == "1"
+        and saved.get("DATABASE_URL") == database_url
+    )
+
+
+def _ensure_container(runtime: str, database_url: str | None) -> str:
+    from convo.core.config import user_settings_path
+
+    existing = _run([runtime, "container", "inspect", CONTAINER_NAME], allow_failure=True)
+    if existing.returncode == 0:
+        if database_url is None:
+            raise SetupError(
+                f"{CONTAINER_NAME!r} already exists, but Convo has no saved database URL. "
+                "Set DATABASE_URL yourself or remove that unused container manually before retrying."
+            )
+        label = _run(
+            [
+                runtime,
+                "inspect",
+                "--format",
+                '{{index .Config.Labels "io.convo.managed"}}',
+                CONTAINER_NAME,
+            ]
+        )
+        if label.stdout.strip() != "true":
+            raise SetupError(
+                f"{CONTAINER_NAME!r} belongs to another setup. Set DATABASE_URL to use it explicitly."
+            )
+        _run([runtime, "start", CONTAINER_NAME])
+        return database_url
+
+    if database_url is not None:
+        raise SetupError(
+            f"Saved local storage exists but {CONTAINER_NAME!r} is missing. "
+            f"Restore the container using the saved credentials and volume {VOLUME_NAME!r}."
+        )
+    if _run([runtime, "volume", "inspect", VOLUME_NAME], allow_failure=True).returncode == 0:
+        raise SetupError(
+            f"Volume {VOLUME_NAME!r} already exists without saved credentials. "
+            "Restore its connection settings before starting Convo."
+        )
+    if user_settings_path().exists():
+        raise SetupError(
+            f"Settings already exist at {user_settings_path()}. Configure DATABASE_URL there."
+        )
+    password = secrets.token_urlsafe(24)
+    database_url = (
+        f"postgresql+psycopg://{DATABASE_USER}:{quote(password, safe='')}"
+        f"@localhost:5432/{DATABASE_NAME}"
+    )
+    _run(
+        [
+            runtime,
+            "run",
+            "--name",
+            CONTAINER_NAME,
+            "--label",
+            "io.convo.managed=true",
+            "-e",
+            f"POSTGRES_USER={DATABASE_USER}",
+            "-e",
+            f"POSTGRES_PASSWORD={password}",
+            "-e",
+            f"POSTGRES_DB={DATABASE_NAME}",
+            "-p",
+            "127.0.0.1:5432:5432",
+            "-v",
+            f"{VOLUME_NAME}:/var/lib/postgresql/data",
+            "-d",
+            IMAGE,
+        ]
+    )
+    _write_local_settings(database_url)
+    return database_url
+
+
+def _wait_for_postgres(runtime: str) -> None:
+    for _attempt in range(30):
+        ready = _run(
+            [
+                runtime,
+                "exec",
+                CONTAINER_NAME,
+                "pg_isready",
+                "-U",
+                DATABASE_USER,
+                "-d",
+                DATABASE_NAME,
+            ],
+            allow_failure=True,
+        )
+        if ready.returncode == 0:
+            return
+        time.sleep(1)
+    raise SetupError("PostgreSQL did not become ready within 30 seconds. Check the container logs.")
+
+
+def _migration_directory() -> Path | None:
+    from convo.core.config import PROJECT_ROOT
+
+    source_directory = PROJECT_ROOT / "migrations"
+    if source_directory.is_dir():
+        return source_directory
+    return None
+
+
+def _upgrade_database() -> None:
+    from alembic import command
+    from alembic.config import Config
+
+    migration_directory = _migration_directory()
+    if migration_directory is not None:
+        config = Config()
+        config.set_main_option("script_location", str(migration_directory))
+        command.upgrade(config, "head")
+        return
+    # Hatch copies the source migration tree into the installed package. Keep
+    # `as_file` open while Alembic reads scripts for zip-safe resource access.
+    with as_file(files("convo").joinpath("migrations")) as packaged_directory:
+        config = Config()
+        config.set_main_option("script_location", str(packaged_directory))
+        command.upgrade(config, "head")
+
+
+def setup() -> Path:
+    """Provision local storage or migrate an explicitly configured PostgreSQL database."""
+    configured_url = _configured_database_url()
+    local_container = _is_managed_database(configured_url)
+    if configured_url is not None and not local_container:
+        # An explicitly supplied DATABASE_URL may point at an existing remote or
+        # shared database. Do not create a second local container around it.
+        database_url = configured_url
+    else:
+        print("Preparing Convo's local storage…", flush=True)
+        runtime = _container_runtime()
+        _ensure_podman_machine(runtime)
+        database_url = _ensure_container(runtime, configured_url)
+        _wait_for_postgres(runtime)
+    # `load_settings` reads the saved file; this assignment also supports an external DATABASE_URL.
+    os.environ["DATABASE_URL"] = database_url
+    try:
+        _upgrade_database()
+    except Exception as error:  # Alembic has several driver-specific exception classes.
+        raise SetupError(
+            "Could not prepare the database schema. Check PostgreSQL access and pgvector, "
+            "then retry `convo --setup`."
+        ) from error
+    from convo.core.config import user_settings_path
+
+    return user_settings_path()
+
+
+def ensure_storage() -> None:
+    """Bootstrap first use and restart managed storage before entering the TUI."""
+    database_url = _configured_database_url()
+    if database_url is None or _is_managed_database(database_url):
+        setup()

convo/core/__init__.py

@@ -0,0 +1 @@
+"""Shared backend configuration, values, and errors."""

convo/core/config.py

@@ -0,0 +1,53 @@
+import math
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+EMBEDDING_DIMENSIONS = 1024
+
+
+def user_settings_path() -> Path:
+    """Return the private per-user settings file used by an installed CLI."""
+    config_home = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return config_home / "convo" / ".env"
+
+
+@dataclass(frozen=True)
+class Settings:
+    database_url: str = field(repr=False)
+    embedding_model: str
+    reranker_model: str = "cross-encoder/ms-marco-MiniLM-L6-v2"
+    rerank_min_score: float = -3.0
+    retrieval_candidates: int = 20
+
+
+def load_environment() -> None:
+    # Environment variables win. The user file makes an installed tool independent
+    # of its read-only site-packages directory; the repository file remains useful
+    # for contributors running from a checkout.
+    load_dotenv(user_settings_path(), override=False)
+    load_dotenv(PROJECT_ROOT / ".env", override=False)
+
+
+def load_settings() -> Settings:
+    load_environment()
+    database_url = os.environ.get("DATABASE_URL", "")
+    if not database_url.startswith("postgresql+psycopg://"):
+        raise ValueError("Set DATABASE_URL to a PostgreSQL/Psycopg URL")
+    embedding_model = os.getenv("EMBEDDING_MODEL", "Qwen/Qwen3-Embedding-0.6B")
+    if embedding_model != "Qwen/Qwen3-Embedding-0.6B":
+        raise ValueError("Changing the embedding model requires a dimension/schema review")
+    rerank_min_score = float(os.getenv("RERANK_MIN_SCORE", "-3"))
+    retrieval_candidates = int(os.getenv("RETRIEVAL_CANDIDATES", "20"))
+    if not math.isfinite(rerank_min_score) or not 5 <= retrieval_candidates <= 50:
+        raise ValueError("Use a finite RERANK_MIN_SCORE and RETRIEVAL_CANDIDATES between 5 and 50")
+    return Settings(
+        database_url=database_url,
+        embedding_model=embedding_model,
+        reranker_model=os.getenv("RERANKER_MODEL", "cross-encoder/ms-marco-MiniLM-L6-v2"),
+        rerank_min_score=rerank_min_score,
+        retrieval_candidates=retrieval_candidates,
+    )

convo/core/contracts.py

@@ -0,0 +1,160 @@
+"""Shared values and the single boundary between the TUI and backend."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Literal, Protocol, runtime_checkable
+
+ReasoningEffort = Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]
+REASONING_EFFORTS: tuple[ReasoningEffort, ...] = (
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+)
+
+
+@dataclass(frozen=True)
+class ChatModel:
+    """A displayable model from the connected account's catalog."""
+
+    id: str
+    name: str
+    reasoning_efforts: tuple[ReasoningEffort, ...] = ()
+    default_reasoning_effort: ReasoningEffort | None = None
+
+
+@dataclass(frozen=True)
+class GenerationSelection:
+    model: ChatModel | None = None
+    reasoning_effort: ReasoningEffort | None = None  # None lets the server choose its default.
+    connected: bool = False
+
+
+@dataclass(frozen=True)
+class Document:
+    id: str
+    path: Path
+    indexed: bool = True
+
+
+@dataclass(frozen=True)
+class Message:
+    role: Literal["user", "assistant"]
+    content: str
+    sources: tuple[Source, ...] = ()
+    structured: dict[str, object] | None = None
+
+
+@dataclass(frozen=True)
+class Source:
+    label: str  # e.g. "notes.md · lines 12–24"; never invent a locator.
+    excerpt: str
+
+
+@dataclass(frozen=True)
+class Answer:
+    text: str
+    sources: tuple[Source, ...] = ()
+    structured: dict[str, object] | None = None
+
+
+@dataclass(frozen=True)
+class ChunkData:
+    text: str
+    locator: str
+
+
+@dataclass(frozen=True)
+class Hit:
+    text: str
+    locator: str
+    distance: float
+    chunk_id: int | None = None
+    score: float | None = None
+
+
+@dataclass(frozen=True)
+class SessionSummary:
+    id: str
+    title: str
+    filename: str | None
+    updated_at: datetime
+    message_count: int
+
+
+@dataclass(frozen=True)
+class SessionSnapshot:
+    id: str
+    title: str
+    document: Document | None
+    history: tuple[Message, ...] = ()
+
+
+class Backend(Protocol):
+    async def prepare(self, path: Path) -> Document:
+        """Parse, chunk, embed and index a file; return only when ready."""
+        ...
+
+    async def answer(
+        self, document: Document, question: str, history: tuple[Message, ...]
+    ) -> Answer:
+        """Retrieve only this document, call ChatGPT, return text and sources.
+
+        history contains completed turns, excluding the current question.
+        """
+        ...
+
+
+@runtime_checkable
+class PreparationControls(Protocol):
+    """Optional progress reporting; callbacks run on the UI event loop."""
+
+    async def prepare_with_progress(
+        self, path: Path, progress: Callable[[str], None]
+    ) -> Document: ...
+
+
+@runtime_checkable
+class SessionControls(Protocol):
+    """Durable sessions; successful turns are saved before the response returns."""
+
+    async def new_session(self, document: Document | None = None) -> SessionSnapshot: ...
+
+    async def list_sessions(self) -> tuple[SessionSummary, ...]: ...
+
+    async def load_session(self, session_id: str) -> SessionSnapshot: ...
+
+    async def answer_session(
+        self, session_id: str, question: str, progress: Callable[[str], None] | None = None
+    ) -> Answer: ...
+
+
+@runtime_checkable
+class AccountControls(Protocol):
+    """Optional ChatGPT sign-in exposed by a completed backend."""
+
+    async def login_openai(self) -> str:
+        """Connect a ChatGPT account through Sign in with ChatGPT."""
+        ...
+
+
+@runtime_checkable
+class GenerationControls(Protocol):
+    """Optional account model and thinking controls, independent of the TUI."""
+
+    def generation_selection(self) -> GenerationSelection: ...
+
+    async def list_models(self) -> tuple[ChatModel, ...]: ...
+
+    async def select_model(self, model_id: str) -> GenerationSelection: ...
+
+    async def cycle_reasoning(self) -> GenerationSelection: ...
+
+    async def select_reasoning(self, effort: ReasoningEffort | None) -> GenerationSelection: ...

convo/core/exceptions.py

@@ -0,0 +1,5 @@
+"""Errors the UI and backend use to communicate expected failure states."""
+
+
+class BackendNotConnected(RuntimeError):
+    """The selected backend operation needs credentials or setup."""

convo/db/__init__.py

@@ -0,0 +1 @@
+"""SQLAlchemy models, connections, and document queries."""

convo/db/base.py

@@ -0,0 +1,13 @@
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(
+        naming_convention={
+            "ix": "ix_%(column_0_label)s",
+            "uq": "uq_%(table_name)s_%(column_0_name)s",
+            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+            "pk": "pk_%(table_name)s",
+        }
+    )